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, but its lines and meta information can still be edited — see Editing a submitted delivery below. 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.

Editing a submitted delivery

The lines of a submitted delivery can be edited through the API, just like in the Web App. The same endpoints used for drafts apply — Edit a Delivery, Add a Package, Edit a Package, and Delete a Package — with a few extra rules that apply to a submitted delivery:

• Editing a delivered quantity requires a price. When you change a line's quantity_delivered, you must send its actual_price in the same request. Otherwise the request is rejected with A price is required when the delivered quantity is edited.
• Line amounts drive the delivery total. Editing lines recalculates the delivery's total actual_price as the sum of the line amounts.
• A bulk edit replaces the full set of lines. When you send delivered_packages to Edit a Delivery, any existing line you omit is zeroed (quantity_delivered = 0, intake_reason = "Not delivered"). Always send the complete set of lines you want to keep.
• Intake reasons are recomputed from the quantity when not set explicitly. On a submitted delivery, an intake_reason that is omitted or sent as null is derived from the delivered quantity (quantity_delivered > 0 → "Accepted", 0 → "Not delivered"). The bulk Edit a Delivery replaces every line, so an omitted reason is recomputed just like an explicit null. The single-line Edit a Package is an edit rather than a replace: an omitted intake_reason keeps the stored value, while sending null recomputes it. If a kept reason no longer matches the new quantity (for example an accepted reason on a line whose quantity is changed to 0), the request is rejected and a consistent reason must be sent.
• Deleting a line zeroes it instead of removing it. On a submitted delivery, Delete a Package does not physically remove the line; it resets it to quantity_delivered = 0 and intake_reason = "Not delivered" (an already-rejected reason is kept).
• The stock-impact flag is fixed. update_stock cannot be changed after submission; attempting to do so returns update_stock cannot be changed after the delivery submit.
• Price-edit flags are sticky. A line already flagged with has_updated_price keeps that flag on later edits.

On a draft delivery these rules do not apply — a quantity can be changed without sending a price.

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.