Skip to content

List purchase orders

GET
/stores/{storeRef}/purchase-orders
curl --request GET \
--url 'https://apibase.ecomweb.app/api/v1/stores/example/purchase-orders?limit=20&offset=0&sort_by=po_number&sort_order=asc' \
--header 'x-api-key: <x-api-key>'

Returns the store’s purchase orders, newest first by default, one page at a time. Rows carry totals and line counts but no lines or receipts; fetch one order for those. Use search to match the order code, reference number or supplier name, sort_by and sort_order to order the page, and filters to narrow by status, supplier, location or date.

Required scopes: read:purchase_orders

storeRef
required
string

The store’s ref, as returned by GET /stores.

limit
number
default: 20 >= 1 <= 100

Maximum number of purchase orders to return, from 1 to 100.

offset
number
0

Number of purchase orders to skip.

search
string
<= 255 characters

Matches PO code, reference number or supplier name

sort_by
string
Allowed values: po_number created_at expected_arrival_at total
sort_order
string
default: desc
Allowed values: asc desc
filters
string

JSON array of {field, operator, values}, e.g. [{“field”:“status”,“operator”:“is”,“values”:[“ordered”]}]

Media typeapplication/json
object
data
required
Array<object>
object
status
required

Status: draft, ordered, partially_received, received, closed or cancelled.

string
Allowed values: draft ordered partially_received received closed cancelled
supplier
required

The supplier, or null while none is chosen.

object
id
required

Supplier ID.

number
name
required

Supplier name.

string
email
required

Supplier email address, or null.

string
nullable
archived
required

True when the supplier has been archived.

boolean
location
required

The inventory location the order delivers to, or null while none is chosen.

object
id
required

Location ID.

number
name
required

Location name.

string
payment_terms
required

Payment terms agreed with the supplier.

string
Allowed values: none cash_on_delivery due_on_receipt in_advance net_7 net_15 net_30 net_45 net_60
line_count
required

Number of lines on the order.

number
received_items
required

Units received and accepted into stock so far.

number
id
required

Purchase order ID.

number
po_number
required

Sequence number of the purchase order within the store, starting at 1.

number
po_code
required

Purchase order code, such as PO1042.

string
reference_number
required

Your own reference number, or null.

string
nullable
supplier_note
required

Note shown to the supplier, or null.

string
nullable
payment_due_at
required

When payment is due, as an ISO 8601 timestamp. Null for terms without a due date and for an order not yet placed.

string
nullable
currency_code
required

Currency code of every amount on the order.

string
expected_arrival_at
required

When the delivery is expected, as an ISO 8601 timestamp, or null.

string
nullable
carrier
required

Carrier delivering the order, or null.

string
nullable
tracking_number
required

Carrier tracking number, or null.

string
nullable
tags
required

Tags on the order.

Array<string>
subtotal
required

Sum of the line costs before tax.

number
tax_total
required

Sum of the line taxes.

number
shipping_cost
required

Shipping cost charged by the supplier.

number
other_costs
required

Other costs, such as customs or handling.

number
total
required

Grand total: subtotal, tax, shipping and other costs.

number
total_items
required

Total units ordered across all lines.

number
ordered_at
required

When the order was placed, as an ISO 8601 timestamp, or null for a draft.

string
nullable
closed_at
required

When the order reached a final status (received, closed or cancelled), as an ISO 8601 timestamp, or null.

string
nullable
last_sent_at
required

When the order was last emailed to the supplier, as an ISO 8601 timestamp, or null if it never was.

string
nullable
created_at
required

When the order was created, as an ISO 8601 timestamp.

string
updated_at
required

When the order was last updated, as an ISO 8601 timestamp.

string
meta
required
object
total
required

Total number of items matching the request.

number
limit
required

Maximum number of items in this page.

number
offset
required

Number of items skipped before this page.

number
page
required

Current page number, starting at 1.

number
totalPages
required

Total number of pages.

number
hasNext
required

Whether a next page exists.

boolean
hasPrev
required

Whether a previous page exists.

boolean

Example

{
"data": [
{
"status": "draft",
"payment_terms": "none"
}
]
}

The request is malformed or failed validation.

Media typeapplication/json
One of:
object
statusCode
required

The HTTP status code.

number
message
required

What went wrong; validation failures list one message per problem.

One of:
string
error

The HTTP status text, such as Bad Request.

string

Example generated

{
"statusCode": 1,
"message": [
"example"
],
"error": "example"
}

The key is missing, invalid, revoked or expired.

Media typeapplication/json
One of:
object
statusCode
required

The HTTP status code.

number
message
required

What went wrong; validation failures list one message per problem.

One of:
string
error

The HTTP status text, such as Bad Request.

string

Example generated

{
"statusCode": 1,
"message": [
"example"
],
"error": "example"
}

The key may not do this: a missing scope, a readonly key, a publishable key on a Store API route, or a disallowed origin.

Media typeapplication/json
One of:
object
statusCode
required

The HTTP status code.

number
message
required

What went wrong; validation failures list one message per problem.

One of:
string
error

The HTTP status text, such as Bad Request.

string

Example generated

{
"statusCode": 1,
"message": [
"example"
],
"error": "example"
}