GetOrderInventorySummaryRequest
| Field | Type | Description |
|---|---|---|
order_id | string | Order to summarize inventory demand for. |
Order Stock and Reservations
All operations use POST /public-api/publicapi.v1.Inventory/ and require the
creator’s inventory access in addition to the exact scope listed on each method.
Order IDs are commercial order IDs, not work-order IDs. Quantities and
Unix-second timestamps are int64 values, encoded as JSON strings. Reservation,
allocation, return, and demand status values are stable lowercase strings
(on_stock, back_order, negative, unspecified), never internal enum
integers.
Order inventory summary
Section titled “Order inventory summary”GetOrderInventorySummary aggregates the order’s required, reserved, and
shortage quantities overall and per product, with a per-location reservation
breakdown. Read-only; it neither reserves nor allocates stock.
Generated Reference
POST /public-api/publicapi.v1.Inventory/GetOrderInventorySummary Summarizes required, reserved, and short quantities for one order, broken down by product and reserving location. Requires customer read access to the order's customer in addition to inventory read.
GetOrderInventorySummaryResponse
| Field | Type | Description |
|---|---|---|
summary | OrderInventorySummary | Aggregated required, reserved, and shortage quantities for the order. |
List order reservations
Section titled “List order reservations”ListOrderReservations returns the reservations backing one order, newest
first, each with its lines, per-line stockStatus, and lifecycle timestamps.
Released reservations are excluded unless includeReleased is true. The internal
idempotency key of each reservation is never exposed.
Generated Reference
POST /public-api/publicapi.v1.Inventory/ListOrderReservations Lists the stock reservations backing one order, including per-line stock status. Requires customer read access to the order's customer.
ListOrderReservationsRequest
| Field | Type | Description |
|---|---|---|
order_id | string | Order whose reservations to list. |
include_released | bool | When true, include reservations that have been released. |
ListOrderReservationsResponse
| Field | Type | Description |
|---|---|---|
reservations | repeated OrderReservation | Reservations backing the order, newest first. |
List order stock demand
Section titled “List order stock demand”ListOrderStockDemand returns one bounded, numbered page of orders that still
have unfulfilled stock demand across the workspace, each with customer context,
linked work orders, and per-product shortage lines. page defaults to 1;
pageSize defaults to 25, maximum 100. Increment page while hasMore is true.
Generated Reference
POST /public-api/publicapi.v1.Inventory/ListOrderStockDemand Lists workspace-wide unfulfilled order stock demand. Gated on inventory read only, so it exposes order and customer references across customers.
ListOrderStockDemandRequest
| Field | Type | Description |
|---|---|---|
page | int32 | 1-based page number into the workspace demand list. Defaults to 1. |
page_size | int32 | Maximum orders to return; defaults are applied when zero. |
ListOrderStockDemandResponse
| Field | Type | Description |
|---|---|---|
orders | repeated OrderStockDemand | Orders with unfulfilled stock demand for the requested page. |
page | int32 | Echoed 1-based page number. |
page_size | int32 | Effective page size used to build this response. |
has_more | bool | True when more orders exist beyond this page. |
Allocate order stock
Section titled “Allocate order stock”AllocateOrderStock commits and reserves stock of one product at one location to
an order. Set confirmShortage to true to allocate beyond the physically
available stock, creating a tracked shortage; otherwise a shortfall returns
FailedPrecondition. expectedAvailableAt is honored only when less than the
requested quantity is physically reserved. Requires inventory:reserve.
idempotencyKey makes retries safe; reusing it with a different payload
conflicts.
Generated Reference
POST /public-api/publicapi.v1.Inventory/AllocateOrderStock Commits and physically reserves stock for one order line at one location. Creating a shortage reservation requires confirm_shortage. Idempotent by key.
AllocateOrderStockRequest
| Field | Type | Description |
|---|---|---|
order_id | string | Order to allocate stock for. |
product_id | string | Product to commit and reserve. |
location_id | string | Location to reserve stock from. |
quantity | int64 | Quantity to commit to the order. |
confirm_shortage | bool | Must be true to allocate more than the physically available stock, creating a shortage; otherwise a shortfall returns FailedPrecondition. |
work_order_id | optional string | Optional work order to attribute the allocation to; must belong to the order. |
expected_available_at | int64 | Unix seconds the shortfall is expected to be available; honored only when physically reserving less than requested. |
idempotency_key | string | Idempotency key; reusing it with a different payload conflicts. |
AllocateOrderStockResponse
| Field | Type | Description |
|---|---|---|
reservation_id | string | Reservation the allocation was recorded on. |
committed_quantity | int64 | Quantity committed to the order. |
physically_reserved_quantity | int64 | Quantity physically reserved from on-hand stock. |
shortage_quantity | int64 | Quantity left short after allocation. |
status | string | Resulting stock status: on_stock, back_order, negative, or unspecified. |
expected_available_at | int64 | Unix seconds the shortfall is expected to be available; zero when none. |
Create an order reservation
Section titled “Create an order reservation”CreateOrderReservation reserves one or more explicit product/location lines for
an order in a single call. Requires inventory:reserve. idempotencyKey makes
retries safe; reusing it with a different payload conflicts.
Generated Reference
POST /public-api/publicapi.v1.Inventory/CreateOrderReservation Creates a multi-line reservation for an order at caller-chosen locations. Idempotent by key. Prefer AllocateOrderStock for shortage-aware allocation.
CreateOrderReservationRequest
| Field | Type | Description |
|---|---|---|
order_id | string | Order to reserve stock for. |
work_order_id | optional string | Optional work order to attribute the reservation to; must belong to the order. |
lines | repeated ReservationLineInput | Lines to reserve, each at an explicit location. |
idempotency_key | string | Idempotency key; reusing it with a different payload conflicts. |
CreateOrderReservationResponse
| Field | Type | Description |
|---|---|---|
reservation_id | string | Identifier of the created (or existing, on idempotent reuse) reservation. |
status | string | Reservation lifecycle status. |
Release a reservation
Section titled “Release a reservation”ReleaseReservation returns an active reservation’s committed stock to
available. It is state-convergent: releasing an already-released reservation
returns its released status rather than erroring. Requires inventory:reserve.
Generated Reference
POST /public-api/publicapi.v1.Inventory/ReleaseReservation Releases a reservation and returns its reserved stock. State-convergent: releasing an already-released reservation returns its current status.
ReleaseReservationRequest
| Field | Type | Description |
|---|---|---|
reservation_id | string | Reservation to release. |
ReleaseReservationResponse
| Field | Type | Description |
|---|---|---|
reservation_id | string | Released reservation identifier. |
status | string | Reservation status after the release. |
Consume a reservation
Section titled “Consume a reservation”ConsumeReservation permanently deducts a reservation’s reserved stock from
on-hand as delivered. This depletes physical stock and cannot be undone by
releasing; credit stock back with ReturnInventory. Consuming an
already-consumed reservation returns its consumed status. Requires
inventory:consume.
Generated Reference
POST /public-api/publicapi.v1.Inventory/ConsumeReservation Consumes an active reservation, permanently deducting on-hand and reserved stock. State-convergent: consuming an already-consumed reservation is a no-op.
ConsumeReservationRequest
| Field | Type | Description |
|---|---|---|
reservation_id | string | Reservation to consume. |
ConsumeReservationResponse
| Field | Type | Description |
|---|---|---|
reservation_id | string | Consumed reservation identifier. |
status | string | Reservation status after consumption. |
consumed_at | int64 | Unix seconds the reservation was consumed. |
Return inventory
Section titled “Return inventory”ReturnInventory credits previously consumed stock back to a location against a
consumed reservation. The product must match a consumed line, and the quantity
cannot exceed the consumed-minus-returned remainder. Requires inventory:return.
idempotencyKey makes retries safe; reusing it with a different payload
conflicts.
Generated Reference
POST /public-api/publicapi.v1.Inventory/ReturnInventory Returns stock previously consumed against a reservation, crediting on-hand. Only valid against a consumed reservation. Idempotent by key.
ReturnInventoryRequest
| Field | Type | Description |
|---|---|---|
reservation_id | string | Consumed reservation to return stock against. |
product_id | string | Product being returned; must match a consumed line. |
location_id | string | Location to credit the returned stock to. |
quantity | int64 | Quantity to return; cannot exceed the consumed-minus-returned remainder. |
reason | string | Human-readable reason for the return. |
idempotency_key | string | Idempotency key; reusing it with a different payload conflicts. |
ReturnInventoryResponse
| Field | Type | Description |
|---|---|---|
return_id | string | Identifier of the recorded return. |
movement_id | string | Identifier of the stock movement created by the return. |
balance | InventoryBalance | Balance for the product/location after the return. |