> For the complete documentation index, see [llms.txt](https://docs.hotwax.co/documents/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.hotwax.co/documents/integrate-with-hotwax/components/fulfillment/purchase-shipments.md).

# Purchase Shipments

purchaseShipments

## get PurchaseShipments

> PURCHASE\_SHIPMENT shipments, paged (PurchaseShipmentSummary), each with the quantity received against it\
> &#x20;           (the sum of its ShipmentReceipt.quantityAccepted) and the quantity rejected on receipt. The purchase order\
> &#x20;           is optional: a shipment without one comes back with null primaryOrderId, orderName and orderExternalId.\
> &#x20;           The keyword matches the shipment id, external id, purchase order id and purchase order name,\
> &#x20;           case-insensitively; the arrival dates filter estimatedArrivalDate, inclusive of the whole thru day.\
> &#x20;           primaryOrderId and shipmentId narrow to one purchase order's or one shipment's. productStoreId keeps the\
> &#x20;           shipments bound for the store's facilities (its current ProductStoreFacility rows); a store with none matches\
> &#x20;           nothing.

```json
{"openapi":"3.1.1","info":{"title":"Poorti API","version":"1.0.0"},"tags":[{"name":"purchaseShipments","description":"purchaseShipments"}],"servers":[{"url":"https://dev-maarg.hotwax.io/rest/s1/poorti"}],"security":[{"basicAuth":[]},{"api_key":[]}],"components":{"securitySchemes":{"basicAuth":{"type":"http","scheme":"basic"},"api_key":{"type":"apiKey","name":"api_key","in":"header","description":"HTTP Header api_key"}},"schemas":{"co.hotwax.poorti.PurchaseShipmentServices.getPurchaseShipments.Out":{"type":"object","properties":{"shipments":{"type":"array"},"shipmentsCount":{"type":"integer","format":"int64"}}}}},"paths":{"/purchaseShipments":{"get":{"tags":["purchaseShipments"],"summary":"get PurchaseShipments","description":"PURCHASE_SHIPMENT shipments, paged (PurchaseShipmentSummary), each with the quantity received against it\n            (the sum of its ShipmentReceipt.quantityAccepted) and the quantity rejected on receipt. The purchase order\n            is optional: a shipment without one comes back with null primaryOrderId, orderName and orderExternalId.\n            The keyword matches the shipment id, external id, purchase order id and purchase order name,\n            case-insensitively; the arrival dates filter estimatedArrivalDate, inclusive of the whole thru day.\n            primaryOrderId and shipmentId narrow to one purchase order's or one shipment's. productStoreId keeps the\n            shipments bound for the store's facilities (its current ProductStoreFacility rows); a store with none matches\n            nothing.","parameters":[{"schema":{"type":"string","format":""},"name":"keyword","in":"query","required":false,"description":null},{"schema":{"type":"string","format":""},"name":"productStoreId","in":"query","required":false,"description":null},{"schema":{"type":"string","format":""},"name":"statusId","in":"query","required":false,"description":"Comma-separated shipment statusIds."},{"schema":{"type":"string","format":""},"name":"destinationFacilityId","in":"query","required":false,"description":null},{"schema":{"type":"string","format":""},"name":"arrivalDateFrom","in":"query","required":false,"description":null},{"schema":{"type":"string","format":""},"name":"arrivalDateThru","in":"query","required":false,"description":null},{"schema":{"type":"string","format":""},"name":"primaryOrderId","in":"query","required":false,"description":null},{"schema":{"type":"string","format":""},"name":"shipmentId","in":"query","required":false,"description":null},{"schema":{"type":"string","format":""},"name":"orderBy","in":"query","required":false,"description":null},{"schema":{"type":"integer","format":"int32"},"name":"pageIndex","in":"query","required":false,"description":null},{"schema":{"type":"integer","format":"int32"},"name":"pageSize","in":"query","required":false,"description":null}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/co.hotwax.poorti.PurchaseShipmentServices.getPurchaseShipments.Out"}}}},"401":{"description":"Authentication required"},"403":{"description":"Access Forbidden (no authz)"},"429":{"description":"Too Many Requests (tarpit)"},"500":{"description":"General Error"}}}}}}
```

## create PurchaseShipment

> Creates an inbound PURCHASE\_SHIPMENT for open lines of one approved purchase order (POST purchaseShipments,\
> &#x20;           hotwax/preorder-maarg#84): per line, a quantity up to what is still unshipped, and the arrival date. The shipment\
> &#x20;           goes to the purchase order's destination and each item is linked to its line by oms create#IncomingShipment\
> &#x20;           (OrderShipment), and a line with an ACTIVE future inventory batch carves a shipment batch out of it for the\
> &#x20;           shipped quantity, with the arrival date as its promise date (oms store#PurchaseShipmentFutureInventory; waiting\
> &#x20;           reservations stay on the purchase order line's batch). externalId is the retry key within the order: its PURCHASE\_SHIPMENT\
> &#x20;           with the same externalId, lines and arrival date is returned; with other lines, quantities or date it is refused.\
> &#x20;           Another order's shipment or another kind of shipment with the same externalId is not a retry, and a new shipment\
> &#x20;           is created. The arrival date of a retry is matched whatever the retrying caller's time zone. The order row is\
> &#x20;           locked, so two creates for one order run one after the other.

```json
{"openapi":"3.1.1","info":{"title":"Poorti API","version":"1.0.0"},"tags":[{"name":"purchaseShipments","description":"purchaseShipments"}],"servers":[{"url":"https://dev-maarg.hotwax.io/rest/s1/poorti"}],"security":[{"basicAuth":[]},{"api_key":[]}],"components":{"securitySchemes":{"basicAuth":{"type":"http","scheme":"basic"},"api_key":{"type":"apiKey","name":"api_key","in":"header","description":"HTTP Header api_key"}},"schemas":{"co.hotwax.poorti.PurchaseShipmentServices.createPurchaseShipment.Out":{"type":"object","properties":{"shipmentId":{"type":"string"},"futureInventoryItemIds":{"type":"array"}}},"co.hotwax.poorti.PurchaseShipmentServices.createPurchaseShipment.In":{"type":"object","properties":{"orderId":{"type":"string"},"externalId":{"type":"string"},"arrivalDate":{"type":"string","description":"yyyy-MM-dd in the user's time zone: the end of that day. A retry names the same day, from any time zone."},"items":{"type":"array","items":{"type":"object","properties":{"orderItemSeqId":{"type":"string"},"quantity":{"type":"number"}}}}},"required":["orderId","externalId","arrivalDate","items"]}}},"paths":{"/purchaseShipments":{"post":{"tags":["purchaseShipments"],"summary":"create PurchaseShipment","description":"Creates an inbound PURCHASE_SHIPMENT for open lines of one approved purchase order (POST purchaseShipments,\n            hotwax/preorder-maarg#84): per line, a quantity up to what is still unshipped, and the arrival date. The shipment\n            goes to the purchase order's destination and each item is linked to its line by oms create#IncomingShipment\n            (OrderShipment), and a line with an ACTIVE future inventory batch carves a shipment batch out of it for the\n            shipped quantity, with the arrival date as its promise date (oms store#PurchaseShipmentFutureInventory; waiting\n            reservations stay on the purchase order line's batch). externalId is the retry key within the order: its PURCHASE_SHIPMENT\n            with the same externalId, lines and arrival date is returned; with other lines, quantities or date it is refused.\n            Another order's shipment or another kind of shipment with the same externalId is not a retry, and a new shipment\n            is created. The arrival date of a retry is matched whatever the retrying caller's time zone. The order row is\n            locked, so two creates for one order run one after the other.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/co.hotwax.poorti.PurchaseShipmentServices.createPurchaseShipment.Out"}}}},"401":{"description":"Authentication required"},"403":{"description":"Access Forbidden (no authz)"},"429":{"description":"Too Many Requests (tarpit)"},"500":{"description":"General Error"}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/co.hotwax.poorti.PurchaseShipmentServices.createPurchaseShipment.In"}},"multipart/form-data":{"schema":{"$ref":"#/components/schemas/co.hotwax.poorti.PurchaseShipmentServices.createPurchaseShipment.In"}}},"required":true}}}}}
```

## get PurchaseShipment

> One PURCHASE\_SHIPMENT: its get#PurchaseShipments row, its items with the quantity accepted and rejected\
> &#x20;           against each, and its receipts.

```json
{"openapi":"3.1.1","info":{"title":"Poorti API","version":"1.0.0"},"tags":[{"name":"purchaseShipments","description":"purchaseShipments"}],"servers":[{"url":"https://dev-maarg.hotwax.io/rest/s1/poorti"}],"security":[{"basicAuth":[]},{"api_key":[]}],"components":{"securitySchemes":{"basicAuth":{"type":"http","scheme":"basic"},"api_key":{"type":"apiKey","name":"api_key","in":"header","description":"HTTP Header api_key"}},"schemas":{"co.hotwax.poorti.PurchaseShipmentServices.getPurchaseShipment.Out":{"type":"object","properties":{"shipment":{"type":"object"}}}}},"paths":{"/purchaseShipments/{shipmentId}":{"get":{"tags":["purchaseShipments"],"summary":"get PurchaseShipment","description":"One PURCHASE_SHIPMENT: its get#PurchaseShipments row, its items with the quantity accepted and rejected\n            against each, and its receipts.","parameters":[{"schema":{"type":"string"},"name":"shipmentId","in":"path","required":true,"description":null}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/co.hotwax.poorti.PurchaseShipmentServices.getPurchaseShipment.Out"}}}},"401":{"description":"Authentication required"},"403":{"description":"Access Forbidden (no authz)"},"429":{"description":"Too Many Requests (tarpit)"},"500":{"description":"General Error"}}}}}}
```

## receive PurchaseShipmentItems

> Receives an inbound PURCHASE\_SHIPMENT (POST purchaseShipments/{shipmentId}/receive, hotwax/preorder-maarg#84),\
> &#x20;           in part or in full, through poorti receive#ProductInventory, which writes the ShipmentReceipt and the stock: the\
> &#x20;           receipt issues the shipment item's future inventory batch (QOO and ATP fall equally) in this transaction through oms\
> &#x20;           issue#ReceiptFutureInventory. Reservations waiting on that batch are not moved to the received stock. items names the shipment items and the quantity accepted\
> &#x20;           and rejected of each; with no items, everything still unreceived is accepted (the final receipt). A quantity over\
> &#x20;           what an item has left, or an accepted quantity over the purchase order line's open quantity (summed over the\
> &#x20;           shipment items of that line), is refused, and nothing is received. The\
> &#x20;           shipment becomes PURCH\_SHIP\_RECEIVED once every item is fully received; a shipment already received receives\
> &#x20;           nothing and returns, so a repeated final receipt changes nothing. The shipment row is locked, so two receipts of\
> &#x20;           one shipment run one after the other.

```json
{"openapi":"3.1.1","info":{"title":"Poorti API","version":"1.0.0"},"tags":[{"name":"purchaseShipments","description":"purchaseShipments"}],"servers":[{"url":"https://dev-maarg.hotwax.io/rest/s1/poorti"}],"security":[{"basicAuth":[]},{"api_key":[]}],"components":{"securitySchemes":{"basicAuth":{"type":"http","scheme":"basic"},"api_key":{"type":"apiKey","name":"api_key","in":"header","description":"HTTP Header api_key"}},"schemas":{"co.hotwax.poorti.PurchaseShipmentServices.receivePurchaseShipmentItems.Out":{"type":"object","properties":{"receiptIds":{"type":"array"},"fullyReceived":{"type":"boolean"}}},"co.hotwax.poorti.PurchaseShipmentServices.receivePurchaseShipmentItems.In":{"type":"object","properties":{"shipmentId":{"type":"string"},"items":{"type":"array","items":{"type":"object","properties":{"shipmentItemSeqId":{"type":"string"},"quantityAccepted":{"type":"number"},"quantityRejected":{"type":"number"}}}}},"required":["shipmentId"]}}},"paths":{"/purchaseShipments/{shipmentId}/receive":{"post":{"tags":["purchaseShipments"],"summary":"receive PurchaseShipmentItems","description":"Receives an inbound PURCHASE_SHIPMENT (POST purchaseShipments/{shipmentId}/receive, hotwax/preorder-maarg#84),\n            in part or in full, through poorti receive#ProductInventory, which writes the ShipmentReceipt and the stock: the\n            receipt issues the shipment item's future inventory batch (QOO and ATP fall equally) in this transaction through oms\n            issue#ReceiptFutureInventory. Reservations waiting on that batch are not moved to the received stock. items names the shipment items and the quantity accepted\n            and rejected of each; with no items, everything still unreceived is accepted (the final receipt). A quantity over\n            what an item has left, or an accepted quantity over the purchase order line's open quantity (summed over the\n            shipment items of that line), is refused, and nothing is received. The\n            shipment becomes PURCH_SHIP_RECEIVED once every item is fully received; a shipment already received receives\n            nothing and returns, so a repeated final receipt changes nothing. The shipment row is locked, so two receipts of\n            one shipment run one after the other.","parameters":[{"schema":{"type":"string"},"name":"shipmentId","in":"path","required":true,"description":null}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/co.hotwax.poorti.PurchaseShipmentServices.receivePurchaseShipmentItems.Out"}}}},"401":{"description":"Authentication required"},"403":{"description":"Access Forbidden (no authz)"},"429":{"description":"Too Many Requests (tarpit)"},"500":{"description":"General Error"}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/co.hotwax.poorti.PurchaseShipmentServices.receivePurchaseShipmentItems.In"}},"multipart/form-data":{"schema":{"$ref":"#/components/schemas/co.hotwax.poorti.PurchaseShipmentServices.receivePurchaseShipmentItems.In"}}},"required":true}}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.hotwax.co/documents/integrate-with-hotwax/components/fulfillment/purchase-shipments.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
