Orders

List orders

Orders, newest first, with items, amounts, payment status and the order link. Filter by status, payment status and date.

GET/stores/{storeId}/v1/orders

Scopeorders:readRead orders

Customer data in customer and shipping_address is included only with customers:read. For periodic sync, use updated_after. See Working with orders for details.

Query parameters

limitinteger = 25: Number of items per page.
cursorstring: The meta.next_cursor value from the previous page. Valid for 15 minutes and bound to the same filters.
statusstring: Order status.pending processing completed cancelled returned
payment_statusstring: Payment status.unpaid paid refunded
created_afterstring (date-time): Orders created after this time.
created_beforestring (date-time): Orders created before this time.
updated_afterstring (date-time): Orders updated after this time; use it for periodic sync.

Response

dataarray<object>required
idstringrequired: Stable order ID.
numberintegerrequired: Order number shown to the merchant and the customer.
statusstringrequired: Order status as the merchant sees it. Any refund makes it returned.pending processing completed cancelled returned
payment_statusstringrequired: unpaid paid refunded
currencystringrequired
totalsobjectrequired
subtotalstring: Items total before discount and shipping.
discountstring: Discount.
shippingstring: Shipping fee.
totalstringrequired: Amount paid by the customer.
itemsarray<object>required
product_idstringrequired
namestringrequired: Product name at the time of the order.
kindstring: Product kind.digital physical service
quantityintegerrequired
unit_pricestringrequired: Unit price in SAR.
totalstringrequired: Unit price × quantity.
order_urlstring | null (uri): The customer's orders page in the store (<store origin>/orders), the same link as the order email. It is not a link to one order and carries no sign-in token. null when the store has no https domain.
created_atstring (date-time)required
updated_atstring (date-time)required
paid_atstring | null (date-time)
refunded_atstring | null (date-time)
customerobject: Included only with the customers:read scope.Returned with customers:readRead customer contact details
idstring | null: The customer's account ID in the store, or null for a guest order.
namestring | null: The customer's name as entered.
phonestring | null: Phone number in E.164 format, such as +966512345678, or null if it is not a valid number.
emailstring | null (email)
shipping_addressobject | null: Shipping address as entered by the customer, or null when the order has no address. Included only with customers:read.Returned with customers:readRead customer contact details
namestring | null
phonestring | null: E.164 format, or null.
countrystring | null: Always SA.
citystring | null
districtstring | null
streetstring | null
postal_codestring | null
short_address_codestring | null
building_numberstring | null
secondary_numberstring | null
notesstring | null
resource_versioninteger: Always 0 for orders. Order the events of one order by resource.version in the webhook envelope.
metaobjectrequired
next_cursorstring | null: Cursor for the next page, or null on the last page.
request_idstring (uuid)

Errors

HTTP	Code	Meaning
400	`INVALID_FILTER`	Unknown filter or invalid value.
400	`CURSOR_MISMATCH`	The cursor was issued for different filters.
403	`SCOPE_REQUIRED`	The token does not carry the required scope.
503	`APPS_SCOPE_RUNTIME_NOT_READY`	The resource is not enabled on this merchant's store yet.

Shared codes are listed in Errors.