List All Purchase Orders

GET

/purchase_orders

🚀 Paid plan only

Lists purchase orders. Rows are the SAME shape as Get Purchase Order, already carrying the nested supplier, destination warehouse, creator and the full line-item array - no per-row follow-up read is needed.

This endpoint is search-index backed and indexing is asynchronous, so a just-created or just-updated purchase order can be absent or stale here. Confirm a write with Get Purchase Order, which reads the database.

Pagination totals are returned in the X-Total-Count, X-Total-Pages-Count, X-Page-Index and X-Per-Page response headers, not in the body. Do not send pageable - it is not a supported parameter here and errors.

Parameters

Query Parameters

page_size

integer

default: 25

Results per page. Default 25, silently capped at 100.

Example

25

page

integer

default: 1

Page to show. Totals are returned in the X-Total-Count and X-Total-Pages-Count response headers.

Example

1

query

string

Free-text search across supplier name and post code, purchase order number, reference number, and line-item variant title, SKU, UPC and supplier reference. Substring matching. Search-index backed, so a just-written purchase order can be missing here - read it back with Get Purchase Order instead.

Example

acme

state

string

Allowed values: draft active completed not_received partially_received fully_received past_due all

Lifecycle state, or a received-status aggregate. An unrecognised value is a 400. There is no default, so drafts are included unless you filter. not_received, partially_received, fully_received, past_due and all are FILTER-ONLY values and never appear in a response state.

Example

active

supplier_id

integer

Only purchase orders for this supplier.

destination_warehouse_id

integer

Only purchase orders delivering to this warehouse.

product_variant_id

integer

Only ACTIVE purchase orders containing this variant (sellable) id.

product_variant_upc_code

string

Only purchase orders containing a line item with this UPC.

reference_number

string

Exact match on the purchase order reference number.

created[after]

string

Created on or after this date. A range where after > before is a 400.

Example

2026-01-01

created[before]

string

Created on or before this date (inclusive of that whole day).

Example

2026-01-31

created_at_min

string format: date-time

Created at or after this timestamp.

updated_at_min

string format: date-time

Updated at or after this timestamp.

since_id

integer

Only purchase orders with an id greater than this.

sort_by

string

Field to sort on. Only supplier_name, created_at, expected_date, estimated_delivery_days and sort_by_received_percent are honoured; any other value is IGNORED silently and the results come back created_at descending, which is also the default when this is omitted.

order

string

default: asc

Allowed values: asc desc

Sort direction. Only used alongside a recognised sort_by.

Header Parameters

x-api-key

string

E.g. 123

Example

123

Responses

200

OK

Array<object>

object

billing_address_country

string

nullable

billing_address_line_1

string

nullable

billing_address_line_2

string

nullable

billing_address_postcode

string

nullable

billing_address_state

string

nullable

billing_address_town

string

nullable

created_at

string format: date-time

created_by

object

email

string

id

number

login

string

created_by_id

number

nullable

currency_code

string

nullable

currency_rate

Decimal serialized as a JSON string. Coerce before arithmetic. Defaults to 0. Set it explicitly for a purchase order in a currency other than the company’s: receiving multiplies the cost price by it.

string

destination_warehouse

object

address_line_1

string

nullable

address_line_2

string

nullable

city

string

nullable

click_and_collect_days

nullable

click_and_collect_enabled

boolean

country

string

nullable

created_at

string format: date-time

created_by_id

number

nullable

cut_off_times

nullable

cut_off_times_enabled

boolean

default_min_reorder

number

nullable

deleted_at

string format: date-time

nullable

deleted_by_id

number

nullable

display_position

number

nullable

eori_id

string

nullable

external_id

string

nullable

id

number

inventory_type_code

string

nullable

ioss_id

string

nullable

letterbox_address_status

nullable

name

string

phone

string

nullable

post_code

string

nullable

region

string

nullable

requested_carrier_account

nullable

tax_id

string

nullable

trading_name

string

nullable

uk_ims_id

string

nullable

updated_at

string format: date-time

updated_by_id

number

nullable

destination_warehouse_id

number

estimated_delivery_days

Whole days from created_at to expected_date, recalculated on any save that changes either date. A value you send is kept only until expected_date next changes, so treat it as derived and drive it with expected_date.

number

nullable

expected_date

string format: date-time

nullable

id

number

note

string

nullable

number

string

product_variants_count

number

purchase_order_product_variants

The line items. This is the key - there is no line_items field on a purchase order.

Array<object>

object

cost

Unit cost. Decimal serialized as a JSON string. Coerce before arithmetic.

string

created_at

string format: date-time

created_by_id

number

nullable

id

Line item id. Pass it to the line-item sub-routes.

number

product_variant_id

The SELLABLE id, the same id the sellables endpoints return. No translation is needed in either direction.

number

purchase_order_id

number

quantity

Units ordered.

number

received

Units received so far. Set indirectly by sending received_quantity as a delta, and never settable directly.

number

nullable

received_at

string format: date-time

nullable

shipped

boolean

nullable

supplier_id

Always the purchase order’s supplier - a sent value is overwritten.

number

tax_rate

Decimal serialized as a JSON string. Coerce before arithmetic.

string

total_amount_excluding_tax

Decimal serialized as a JSON string. Coerce before arithmetic.

string

total_amount_including_tax

Decimal serialized as a JSON string. Coerce before arithmetic.

string

updated_at

string format: date-time

updated_by_id

number

nullable

supplier_product_variant

object

average_cost

Decimal serialized as a JSON string. Coerce before arithmetic.

string

cost

Decimal serialized as a JSON string. Coerce before arithmetic.

string

created_by_id

number

nullable

default_supplier

boolean

has_active_purchase_order

boolean

id

number

lead_time

number

nullable

product_variant_id

number

reference_number

string

nullable

supplier_id

number

tax_rate

number

nullable

title

string

nullable

updated_by_id

number

nullable

supplier

The same supplier shape as the purchase order’s own supplier.

object

product_variant

object

active_channels

Array

allocated_stock_level_at_all_warehouses

number

available_stock_level_at_all_warehouses

number

channel_sellables

Array

cost_price

number

created_at

string

created_by_id

number

full_title

string

id

number

images

Array

inventory

object

allocated_stock_level_at_all_warehouses

number

available_stock_level_at_all_warehouses

number

incoming_stock_level_at_all_warehouses

number

infinite

boolean

physical_stock_level_at_all_warehouses

number

margin

number

measurement_attributes

object

depth

number

dimensions_unit

string

height

number

id

number

width

number

min_reorder_level

number

model_number

string

on_hand_value

number

price

number

product

object

description

string

estimated_delivery

nullable

hs_tariff_number

nullable

id

number

main_image

object

binary_data

nullable

content_type

nullable

created_at

string

created_by_id

nullable

deleted_at

nullable

deleted_by_id

nullable

display_position

nullable

id

number

picture_content_type

nullable

picture_file_name

nullable

picture_file_size

nullable

picture_order

number

picture_updated_at

nullable

product_id

number

src

string

updated_at

string

updated_by_id

nullable

main_image_src

string

origin_country

nullable

tax_rate

number

title

string

weight

number

product_title

string

profit

number

quantity_to_reorder

number

sellable_title

string

sku_code

string

stock_entries

Array<object>

object

allocated_stock_level

number

available_stock_level

number

incoming_stock_level

number

infinite

boolean

location

nullable

physical_stock_level

number

sellable_id

number

sellable_on_hand_value

number

stock_running_low

boolean

updated_at

string

warehouse

object

address_line_1

string

address_line_2

string

city

string

click_and_collect_days

nullable

click_and_collect_enabled

boolean

country

nullable

created_at

string

created_by_id

number

default_min_reorder

number

deleted_at

nullable

deleted_by_id

nullable

id

number

inventory_type_code

string

name

string

phone

nullable

post_code

string

region

string

requested_carrier_account

nullable

updated_at

string

updated_by_id

nullable

user_id

nullable

warehouse_id

number

stock_level_at_all_warehouses

number

tax_rate

number

title

string

total_quantity_sold

number

type

string

upc_code

string

updated_at

string

variant_option_specifics

Array

variant_property_specifics

Array

weight

number

received_at

string format: date-time

nullable

received_product_variants_count

number

reference_number

Unique per company when present. A duplicate is a 400.

string

nullable

sent_at

string format: date-time

nullable

shipping_address_country

string

nullable

shipping_address_line_1

string

nullable

shipping_address_line_2

string

nullable

shipping_address_postcode

string

nullable

shipping_address_state

string

nullable

shipping_address_town

string

nullable

shipping_and_handling

Decimal serialized as a JSON string. Coerce before arithmetic.

string

state

Only these three values are ever returned. The received-status values accepted by the list state filter are filter-only inputs.

string

Allowed values: draft active completed

subtotal

Computed on read, never stored. Decimal serialized as a JSON string. Coerce before arithmetic.

string

supplier

object

accounting_contact_email

string

nullable

accounting_contact_name

string

nullable

accounting_phone_number

string

nullable

active_purchase_order_count

number

address_line_1

string

nullable

address_line_2

string

nullable

city

string

nullable

completed_purchase_order_count

number

country

string

nullable

created_at

string format: date-time

created_by_id

number

nullable

currency_code

string

nullable

deleted_at

string format: date-time

nullable

deleted_by_id

number

nullable

id

number

name

string

post_code

string

nullable

purchase_order_template

The template used to render this supplier’s purchase order document, on a plan with customizable templates.

string

nullable

region

string

nullable

reminder_email_template

string

nullable

sales_contact_email

Reminder and report emails go here. Can be blank, and the send still reports success.

string

nullable

sales_contact_name

string

nullable

sales_phone_number

string

nullable

updated_at

string format: date-time

updated_by_id

number

nullable

supplier_id

number

supplier_report_format

Write-only: there is no stored column, so List and Get always return null. A Create or Update response echoes the value sent in that same request.

string

nullable

total_excluding_tax

Decimal serialized as a JSON string. Coerce before arithmetic.

string

total_including_tax

Use this for the purchase order value, computed on read and never stored. Decimal serialized as a JSON string. Coerce before arithmetic.

string

total_tax

Decimal serialized as a JSON string. Coerce before arithmetic.

string

units_ordered

number

units_received

number

updated_at

string format: date-time

updated_by_id

number

nullable

user_id

number

Example

[
  {
    "id": 491,
    "number": "PO-0000001",
    "reference_number": null,
    "state": "active",
    "supplier_id": 1748,
    "destination_warehouse_id": 1784,
    "user_id": 1923,
    "created_by_id": 1923,
    "updated_by_id": null,
    "created_at": "2026-05-28T21:34:51Z",
    "updated_at": "2026-05-28T21:34:51Z",
    "expected_date": "2026-06-04T00:00:00Z",
    "estimated_delivery_days": 7,
    "currency_code": "gbp",
    "currency_rate": "1.0",
    "note": null,
    "units_ordered": 10,
    "units_received": 0,
    "product_variants_count": 1,
    "received_product_variants_count": 0,
    "subtotal": "45.0",
    "total_tax": "9.0",
    "total_excluding_tax": "45.0",
    "total_including_tax": "54.0",
    "shipping_and_handling": "0.0",
    "supplier_report_format": null,
    "sent_at": null,
    "received_at": null,
    "supplier": {
      "id": 1748,
      "name": "Default supplier",
      "sales_contact_email": "buying@example.com",
      "currency_code": "gbp"
    },
    "destination_warehouse": {
      "id": 1784,
      "name": "Main warehouse"
    },
    "created_by": {
      "id": 1923,
      "login": "seller",
      "email": "seller@example.com"
    },
    "purchase_order_product_variants": [
      {
        "id": 1575,
        "purchase_order_id": 491,
        "product_variant_id": 1226617,
        "supplier_id": 1748,
        "quantity": 10,
        "received": 0,
        "received_at": null,
        "cost": "4.5",
        "tax_rate": "20.0",
        "total_amount_excluding_tax": "45.0",
        "total_amount_including_tax": "54.0",
        "shipped": null,
        "supplier_product_variant": {
          "id": 8811,
          "supplier_id": 1748,
          "product_variant_id": 1226617,
          "cost": "4.5",
          "title": "APPLE MAGIC MOUSE [TEST]",
          "product_variant": {
            "id": 1226617,
            "sku_code": "MOUSE-01",
            "full_title": "APPLE MAGIC MOUSE [TEST]"
          }
        }
      }
    ]
  }
]

Headers

X-Total-Count

string

X-Total-Pages-Count

string

X-Page-Index

string

X-Per-Page

string

ETag

string

X-Request-Id

string

403

The company’s plan does not include purchase orders, or the user lacks the manage_purchase_orders permission. Body is {"error_messages":[...]}. Checked before the body is read.