Receiving Purchase Orders

There is a full API collection for receiving purchase orders. The API currently supports receiving existing purchase orders only — creating or sending new orders is not supported.

Receiving a purchase order is a multi-step process. Follow each step sequentially.

Purchase order statuses

Before retrieving an order to receive, it helps to understand the possible states a purchase order can be in:

In addition, the delivery_closed flag indicates whether additional deliveries can still be registered. An order is only in a true final state when delivery_closed is true. Orders in IN_PROGRESS or ORDERED state always have delivery_closed set to false.

Only orders in ORDERED or DELIVERED state (with delivery_closed set to false) can receive new deliveries.

Step by step instructions

1. Get Purchase Orders. Use the available filters, such as order number, to retrieve the specific order you want to receive. Note that the id returned here is different from the human-readable order number.

2. Create a Delivery Draft. Specify the delivered packages with their quantities, prices, and any optional details such as intake reasons or discounts. The packages do not have to match the original order exactly: additional or different packages can be included. Save the delivery id from the response for the next step. Inventory is not updated at this point.

3. Submit the Delivery Draft. This commits the delivery and updates inventory with the delivered quantities. You can optionally specify a delivery_date; inputs without explicit timezone information are assumed to be UTC+0. After submission, the draft can no longer be cancelled and its packages can no longer be edited, but meta information such as notes can still be updated. The order remains open for additional deliveries after this step.

4. Close Deliveries. This signals that no further deliveries are expected and prevents new deliveries from being added to the order. You can close an order without having delivered all of the originally ordered packages.

A delivery draft can be cancelled at any point before submission. This permanently deletes the draft and cannot be undone.

Intake reasons

Each package in a delivery can be assigned an intake_reason to record why it was received in the way it was. There is an important constraint: codes that indicate an accepted delivery can only be used when quantity_delivered is greater than 0, and codes that indicate a non-accepted delivery can only be used when quantity_delivered is 0.

Attaching delivery note files

Delivery note files can be attached to a delivery using the Upload Delivery Note File endpoint. Up to 10 files can be attached per delivery. PDF and image formats are supported, with a file size limit of 20 MB per file.