Stock reservations API (0.1.0)

Download OpenAPI specification:Download

team-order-management: team-order-management@newstore.com URL: https://goodscloud.atlassian.net/wiki/spaces/HQ/overview

Places the stock holds an order needs: a reservation against current ATP, and a future allocation for a pre-order item, which has no current stock to reserve.

Both operations are idempotent per sales order item. An item that already holds a reservation or a future allocation keeps the one it has and is reported as placed, so a caller retrying after a timeout cannot double-place a hold.

Neither operation falls back to the other. An item reported as not placed holds no stock, and the caller decides what that means for the order.

future-allocations

Holds placed against future stock for a sales order's pre-order items.

Allocate a sales order's pre-order items against future stock

Allocates the given items of one sales order against future inventory, for items sold before the product is in stock.

With preferred_fulfillment_node_id, allocates as much as that node's future availability covers and places the remaining items at other nodes. Without it, works through the nodes with the highest future availability first. An item that no node can cover comes back in unallocated_item_ids, and the response is still a 200.

Items already holding a future allocation keep it and are returned in allocated_items.

Request Body schema: application/json

The sales order and the items to allocate against future inventory.

sales_order_uuid required	string [ 1 .. 256 ] characters The uuid of the sales order the items belong to.
preferred_fulfillment_node_id	string <= 256 characters The fulfillment node to allocate at. Items it cannot cover are allocated elsewhere. When omitted stock picks the node with the highest future availability.
required	Array of objects [ 1 .. 2000 ] items

Responses

Request samples

Payload

Content type

application/json

{"sales_order_uuid": "8e3ba7ef-b3d3-4c40-a05a-9a83f6f6b6a4",
"preferred_fulfillment_node_id": "US01",
"items": [{"sales_order_item_id": "a7d4b7b3-0b0d-4a1b-9c3a-6d2a1e9c4f11",
"product_id": "NS-COAT-PREORDER-M"
}
]
}

Response samples

200
400
409
500

Content type

application/json

{"allocated_items": [{"sales_order_item_id": "a7d4b7b3-0b0d-4a1b-9c3a-6d2a1e9c4f11",
"fulfillment_node_id": "DC01"
}
],
"unallocated_item_ids": [ ]
}

reservations

Holds placed against current stock for a sales order's items.

Reserve current stock for a sales order

Reserves current stock for the given items of one sales order, holding it until the reservation expires.

Reserves as much as it can: an item with no current stock at its fulfillment node comes back in non_reserved_item_ids and the response is still a 200, because a partly reserved order is a normal outcome rather than a failure. Items already holding a reservation are returned in reserved_items without being reserved again.

Request Body schema: application/json

The sales order and the items to reserve stock for.

sales_order_uuid required	string [ 1 .. 256 ] characters The uuid of the sales order the items belong to.
required	Array of objects [ 1 .. 2000 ] items

Responses

Request samples

Payload

Content type

application/json

{"sales_order_uuid": "8e3ba7ef-b3d3-4c40-a05a-9a83f6f6b6a4",
"items": [{"sales_order_item_id": "a7d4b7b3-0b0d-4a1b-9c3a-6d2a1e9c4f11",
"product_id": "NS-SHIRT-BLUE-M",
"fulfillment_node_id": "US01"
},
{"sales_order_item_id": "b9f5c8c4-1c1e-4b2c-8d4b-7e3b2f0d5a22",
"product_id": "NS-SHIRT-BLUE-L",
"fulfillment_node_id": "US01"
}
]
}

Response samples

200
400
409
500

Content type

application/json

{"reserved_items": [{"sales_order_item_id": "a7d4b7b3-0b0d-4a1b-9c3a-6d2a1e9c4f11",
"reservation_id": "6f1c1f6e-9a4a-4a7e-b0a2-2f9c4d3e8b10"
}
],
"non_reserved_item_ids": ["b9f5c8c4-1c1e-4b2c-8d4b-7e3b2f0d5a22"
]
}