Skip to content

Mark a purchase order as ordered

POST
/stores/{storeRef}/purchase-orders/{id}/order
curl --request POST \
--url https://apibase.ecomweb.app/api/v1/stores/example/purchase-orders/1/order \
--header 'x-api-key: <x-api-key>'

Places a draft order: its status becomes ordered and its units count as incoming stock at the destination location. The order needs a supplier, a destination location and at least one line, otherwise the request answers 400 with the code PURCHASE_ORDER_INCOMPLETE. Nothing is sent to the supplier; use the send route for that. Returns the updated order.

Required scopes: write:purchase_orders

id
required
integer

The purchase order ID.

storeRef
required
string

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

Media typeapplication/json
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
lines
required

The lines of the order.

Array<object>
object
id
required

Line ID.

number
variant_id
required

ID of the ordered variant, or null once the variant was deleted.

number
nullable
product_id
required

ID of the ordered product, or null once the product was deleted.

number
nullable
product_name
required

Product name as it was when the line was added. Kept after the product is deleted.

string
variant_title
required

Variant title as it was when the line was added, or null.

string
nullable
sku
required

SKU as it was when the line was added, or null.

string
nullable
product_image
required

Current image URL of the product, or null when it has none or the variant was deleted.

string
nullable
supplier_sku
required

The supplier’s own SKU for the item, or null.

string
nullable
qty_ordered
required

Units ordered.

number
qty_accepted
required

Units received and accepted into stock.

number
qty_rejected
required

Units received and rejected. They never enter stock.

number
qty_outstanding
required

Units still expected: ordered minus accepted minus rejected.

number
unit_cost
required

Cost per unit, before tax, in the purchase order currency.

number
tax_rate
required

Tax rate as a percent, from 0 to 100.

number
line_subtotal
required

Line cost before tax.

number
line_tax
required

Tax on the line.

number
receipts
required

Deliveries recorded against the order, oldest first.

Array<object>
object
created_by
required

Who recorded the receipt.

object
id
required

ID of the user or API key creator that recorded the receipt, or null.

string
nullable
name
required

Display name, or null when it cannot be resolved.

string
nullable
lines
required

Units accepted and rejected per line.

Array<object>
object
line_id
required

ID of the purchase order line.

number
accepted
required

Units accepted into stock.

number
rejected
required

Units rejected.

number
id
required

Receipt ID.

number
note
required

Note recorded with the receipt, or null.

string
nullable
created_at
required

When the receipt was recorded, as an ISO 8601 timestamp.

string
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

Example

{
"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"
}

The resource does not exist in this store.

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 request conflicts with the resource’s current state.

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"
}