PO line reconciliation figures — External API
The External V1 API's purchase order line-item object now exposes a full set of reconciliation quantities. These are the same figures the PO line-item grid displays, computed from the same source, so the API and the UI cannot drift apart.
Where line items appear
The same object is returned by three endpoints:
| Endpoint | Notes |
|---|---|
GET /external/api/v1/purchase-orders/items | Paginated list across all POs; accepts line-level filters |
GET /external/api/v1/purchase-orders | Each PO includes an items[] array |
GET /external/api/v1/purchase-orders/{id} | Single PO with items[]; also populates allocations per line |
Units of measure — read this before comparing fields
A line carries two units. Subtracting a field in one unit from a field in the other produces a meaningless number.
| Basis | What it is | Fields in this basis |
|---|---|---|
| Ordered UOM | The unit the PO line was purchased in (cases, pallets, drums) | quantity, quantity_shipped, quantity_billed, remaining_to_ship |
| Base UOM | The unit stock is tracked in (usually eaches) | quantity_ordered, quantity_received, quantity_allocated, available_to_allocate |
A line ordered as 10 cases of 12 has quantity 10 and quantity_ordered 120. Both are correct — they are the same purchase counted in two units.
Quantity fields
| Field | Basis | Signed? | Description |
|---|---|---|---|
quantity | Ordered | — | How much was ordered, in the ordered UOM |
quantity_ordered | Base | — | The same order converted to the base UOM |
quantity_shipped | Ordered | — | Total across all shipment lines linked to this PO line, converted per line |
quantity_received | Base | — | Total across receipts, summed from individual receipt lines |
quantity_billed | Ordered | — | Total across all bill lines linked to this PO line (gross; drafts count; credits not netted) |
quantity_allocated | Base | — | Open sales-order reservation (purchase-to-order). 0 if not in use |
remaining_to_ship | Ordered | Yes | quantity − quantity_shipped. Negative means over-shipped |
remaining_to_receive | Mixed* | Yes | quantity − quantity_received. Negative means over-received |
available_to_allocate | Base | Floored at 0 | quantity_ordered − quantity_received − quantity_allocated. How much of this incoming stock is free to commit to a sales order |
*remaining_to_receive spans two bases because quantity_received is in base UOM; treat it as approximate on lines where ordered and base units differ.
The two flooring rules
remaining_to_*is signed. Over-shipping is a supported flow; the negative is the number you need to spot variances.available_to_*is floored at 0. You cannot commit a negative quantity to a sales order.
Filtering
All five reconciliation fields are filterable on GET /purchase-orders/items using bracket notation (field[op]=value, operators: eq, neq, gt, gte, lt, lte, in, notin, contains, notcontains, set, notset).
Useful examples:
Lines shipped more than was ordered (over-shipments):
GET /external/api/v1/purchase-orders/items?remaining_to_ship[lt]=0
Lines still awaiting receipt on a specific PO:
GET /external/api/v1/purchase-orders/items?purchase_order_id=4471&remaining_to_receive[gt]=0
Received but not yet fully billed:
GET /external/api/v1/purchase-orders/items?quantity_received[gt]=0&quantity_billed[lt]=1
Field name change — action required if you integrated recently
The field quantity_remaining (first published 2026-08-06) has been renamed to available_to_allocate. The old name is not aliased and will not be returned. If you integrated against quantity_remaining in the past two weeks, update your code to use available_to_allocate.
The field received_quantity (published since 2024) is deprecated in favour of quantity_received. Both are still returned and carry the same value; prefer quantity_received in new code.
Related
- PO shipment lines:
GET /external/api/v1/purchase-order-shipments - Bill variance:
GET /external/api/v1/bills/{id}/variance