Order
Private Order API endpoints
An API endpoint to get list of orders. Results are scoped to the shop that owns the API key. Archived orders are excluded unless archived=1 is passed.
Query parameters
pageoptionalintegerPage
Defaults to 1.
per_pageoptionalintegerEntities per page
Defaults to 50.
customer_idoptionalintegerFilter by customer ID. Must belong to the shop.
subscription_idoptionalintegerFilter by subscription ID. Must belong to the shop.
product_idoptionalintegerFilter to orders that have at least one line item for this exact product ID. The match is on the line item's product, so plans and variants must be passed by their own ID. The parent product ID is not expanded. Must belong to the shop.
statuses[]optionalstring[]Filter by order status. Values must be distinct.
fulfillment_statuses[]optionalstring[]Filter by fulfillment status. Values must be distinct.
tags[]optionalinteger[]Filter to orders carrying at least one of these tag IDs. Values must be distinct and must be existing tag IDs of the shop.
archivedoptionalbooleanFilter by the archived flag. Accepts 1/0 (or true/false). Defaults to false, which excludes archived orders; pass 1 to return only archived orders.
Defaults to false.
created_at[gte]optionalstringFilter to include only orders created on or after this date. Format Y-m-d\TH:i:s, interpreted as UTC. Inclusive.
Format: date-time.
created_at[lte]optionalstringFilter to include only orders created on or before this date. Format Y-m-d\TH:i:s, interpreted as UTC. Inclusive.
Format: date-time.
created_at_startoptionalstringDeprecatedDeprecated alias of created_at[gte]. When both arrive, created_at[gte] wins.
Format: date-time.
created_at_endoptionalstringDeprecatedDeprecated alias of created_at[lte]. When both arrive, created_at[lte] wins.
Format: date-time.
due_date[gte]optionalstringFilter to include only orders due on or after this date. Format Y-m-d\TH:i:s, interpreted as UTC. Inclusive.
Format: date-time.
due_date[lte]optionalstringFilter to include only orders due on or before this date. Format Y-m-d\TH:i:s, interpreted as UTC. Inclusive.
Format: date-time.
due_date_startoptionalstringDeprecatedDeprecated alias of due_date[gte]. When both arrive, due_date[gte] wins.
Format: date-time.
due_date_endoptionalstringDeprecatedDeprecated alias of due_date[lte]. When both arrive, due_date[lte] wins.
Format: date-time.
expand[]optionalstring[]List of relations to expand. items, tags, metadata and shipping_items are always present and do not need to be requested. Available keys: customer, shipping_address, shipping_method, local_pickup, items.product, items.bundle.items.product, items.bundle.items.variant.
Returnsobject
Orders list response
Error responses
401objectMissing or invalid API key.
422objectOne or more query parameters failed validation, e.g. an unknown status, a tag ID that does not belong to the shop, or a malformed date.
A detailed description of the order. The order must belong to the shop that owns the API key.
Path parameters
order_idRequiredintegerOrder ID
Format: integer.
Query parameters
expand[]optionalstring[]List of relations to expand. items, tags, metadata and shipping_items are always present and do not need to be requested. Available keys: customer, shipping_address, shipping_method, local_pickup, items.product, items.bundle.items.product, items.bundle.items.variant.
ReturnsOrder
Order object response
Error responses
400objectThe order exists but belongs to another shop.
401objectMissing or invalid API key.
404objectNo order exists with this ID.
422objectThe expand[] parameter failed validation.
Partially update an order. Every field is optional and any field left out of the body is untouched. Only the keys present in the request are applied. gift.message and gift.recipient_email are always persisted, but they are echoed back only inside the gift block, which is null unless the order is a gift.
items, tags, metadata and shipping_items are always included in the response; customer, shipping_address and items.product have to be requested through expand.
Path parameters
order_idRequiredintegerOrder ID
Format: integer.
Query parameters
expand[]optionalstring[]List of relations to expand. items, tags, metadata and shipping_items are always present and do not need to be requested. Available keys: customer, shipping_address, shipping_method, local_pickup, items.product, items.bundle.items.product, items.bundle.items.variant.
Request body
due_dateoptionalstringDue date in Y-m-d\TH:i:s format. Must be after yesterday. Cannot be null. Send no key at all to leave it unchanged.
giftoptionalobjectGift details, mirroring the gift block of the order response. Omit the key to leave both fields unchanged.
tagsoptionalobjectAttach and detach order tags. Deletions are applied before creations. Omit the key to leave the order's tags unchanged.
ReturnsOrder
Order object response
Error responses
404objectThe order does not exist or belongs to another shop.
422objectValidation failed, for example due_date is not in Y-m-d\TH:i:s format or is not after yesterday, a tags.create value is duplicated, or a tags.delete ID is not a tag of this shop.
Marks the order as shipped. Only orders in awaiting_delivery or future_shipment can be shipped. Any other status responds with 400. Shipping the order sends the customer the order shipped email and increments the successful shipment number of the linked subscription.
Path parameters
order_idRequiredintegerOrder ID
Format: integer.
Query parameters
expand[]optionalstring[]List of relations to expand. items, tags, metadata and shipping_items are always present and do not need to be requested. Available keys: customer, shipping_address, shipping_method, local_pickup, items.product, items.bundle.items.product, items.bundle.items.variant.
ReturnsOrder
Order object response
Error responses
400objectThe order cannot be shipped from its current status (for example it is already shipped or cancelled).
404objectOrder not found, or it belongs to another shop.
Marks the order as cancelled. Orders that are already shipped or cancelled respond with 400. Cancelling removes the order shipping items and returns their quantities to the inventory item stock, and sends the customer the order cancelled email.
Path parameters
order_idRequiredintegerOrder ID
Format: integer.
Query parameters
expand[]optionalstring[]List of relations to expand. items, tags, metadata and shipping_items are always present and do not need to be requested. Available keys: customer, shipping_address, shipping_method, local_pickup, items.product, items.bundle.items.product, items.bundle.items.variant.
ReturnsOrder
Order object response
Error responses
400objectThe order is already shipped or already cancelled.
404objectOrder not found, or it belongs to another shop.
Moves the order back to awaiting_delivery. Only orders in shipped or future_shipment that are not archived can be moved. Anything else responds with 400. When the order comes from future_shipment its shipping items are re-created from the product and survey configuration.
Path parameters
order_idRequiredintegerOrder ID
Format: integer.
Query parameters
expand[]optionalstring[]List of relations to expand. items, tags, metadata and shipping_items are always present and do not need to be requested. Available keys: customer, shipping_address, shipping_method, local_pickup, items.product, items.bundle.items.product, items.bundle.items.variant.
ReturnsOrder
Order object response
Error responses
400objectThe order is archived, or its current status is neither shipped nor future_shipment.
404objectOrder not found, or it belongs to another shop.
Archives the order. Archived orders are excluded from the order list unless it is requested with archived=true. An order that is already archived responds with 400. Archiving cannot be undone through the API. There is no unarchive endpoint.
Path parameters
order_idRequiredintegerOrder ID
Format: integer.
Query parameters
expand[]optionalstring[]List of relations to expand. items, tags, metadata and shipping_items are always present and do not need to be requested. Available keys: customer, shipping_address, shipping_method, local_pickup, items.product, items.bundle.items.product, items.bundle.items.variant.
ReturnsOrder
Order object response
Error responses
400objectThe order is already archived.
404objectOrder not found, or it belongs to another shop.
Moves the order to future_shipment and sets the given due date. Only orders in awaiting_delivery can be moved. Anything else responds with 400. The order shipping items are removed and their quantities are returned to the inventory item stock, in the same way as cancelling.
Path parameters
order_idRequiredintegerOrder ID
Format: integer.
Query parameters
expand[]optionalstring[]List of relations to expand. items, tags, metadata and shipping_items are always present and do not need to be requested. Available keys: customer, shipping_address, shipping_method, local_pickup, items.product, items.bundle.items.product, items.bundle.items.variant.
Request body
Future shipment due date body
due_dateRequiredstringThe new due date of the order, in Y-m-d\TH:i:s format. Must be later than the current date and time.
Format: date-time.
ReturnsOrder
Order object response
Error responses
400objectThe order status is not awaiting_delivery.
404objectOrder not found, or it belongs to another shop.
422objectdue_date is missing, is not in Y-m-d\TH:i:s format, or is not after the current date and time.
Add, change and remove the shipping items of an order in a single call. The payload is validated as a whole before anything is applied, so a failure in any entry leaves the order untouched. Operations are applied in the order delete, update, create, and each one adjusts the linked inventory item's stock: added quantity is taken out of stock, removed quantity is returned to it.
A shipped order cannot be synced. The request responds with 400 (error code bad_request).
Path parameters
order_idRequiredintegerOrder ID
Format: integer.
Query parameters
expand[]optionalstring[]List of relations to expand. items, tags, metadata and shipping_items are always present and do not need to be requested. Available keys: customer, shipping_address, shipping_method, local_pickup, items.product, items.bundle.items.product, items.bundle.items.variant.
Request body
shipping_itemsRequiredobjectReturnsOrder
Order object response, with the synced shipping_items.
Error responses
400objectThe order has already been shipped and its shipping items can no longer be changed.
404objectThe order does not exist or belongs to another shop.
422objectValidation failed, for example an unknown or archived inventory_id, a shipping item ID that is not on this order, a duplicate entry, a quantity below 1, or an update entry on a manual item or above its current quantity.