get https://{shopdomain}.myshoplaza.com/openapi/2022-01/orders
Requires
read_orderaccess scope. More access scope
The data returned by the list interface may not necessarily be consistent with the order data displayed by the store admin. The store admin will filter out orders with a status of canceled and those without a shipping address and more filters.
Request Parameters
Public Request Parameters
Query Parameters
| Parameter Name | Type | Required | Parameter Value | Description |
|---|---|---|---|---|
| ids | string | N | Order's IDs, please use comma as separator, for example: 183211-00000005,183211-00000006 | |
| limit | string | Limit per page, maximum: 250,Defaults to 10 | ||
| page | string | Page number,Defaults to 1 | ||
| created_at_min | string | Filter orders created at or after date, for example: 2016-01-18T23:41:00Z | ||
| created_at_max | string | Filter orders created at or before date, for example: 2016-01-18T23:41:00Z | ||
| updated_at_min | string | Filter orders created at or before date, for example: 2016-01-18T23:41:00Z | ||
| updated_at_max | string | Filter orders last updated at or before date, for example: 2016-01-18T23:41:00Z | ||
| placed_at_min | string | Filter orders placed at or after date, for example: 2016-01-18T23:41:00Z | ||
| placed_at_max | string | Filter orders placed at or before date, for example: 2016-01-18T23:41:00Z | ||
| status | string | Filter orders by status: opened, placed, finished, cancelled | ||
| fulfillment_status | string | Filter orders by fulfillment status: initialled, waiting, partially_shipped, shipped, partially_finished, finished, cancelled, returning, returned, partially_returned | ||
| financial_status | string | Filter orders by financial status: waiting, paying, paid, cancelled, failed, refunding, refund_failed, refunded, partially_refunded | ||
| location_id | string | If the current store is associated with a physical outlet, then by passing the location ID through it , you can retrieve the list of offline orders specific to that outlet. If no location_id is provided, it will query all orders for the current store, including both online and offline orders | ||
| keyword | string | Search keyword, takes effect when keyword_scope_fields has a value. | ||
| keyword_scope_fields | string | Attribute range of keyword action, optional: name, number, tag_list, id, sku, spu, product_tags, product_title, credit_card_number, browser_ip, source, source_name, shipping_email, shipping_phone, tracking_number, shipping_line_name, line_item_vendor, discount_code, shipping_address_extra_info, transaction_id, last_landing_url, last_referrer_show, country. eg: name,shipping_phone | ||
| sort_by | string | you can sort the result of order list by created_at or placed_at or updated_at | ||
| sort_direction | string | Sorting method, which value only desc or asc , "desc" for descending order, "asc" for ascending order. | ||
| page_token | string | Page cursor, listing the data after the cursor. When both page_token and page exist, the page_token is preferred. This parameter is obtained from the next_token of the response. Note: With page_token, the count in the response represents the number of orders that were responded to for this request, not the number of eligible orders | ||
| customer_id | string | Filter orders by customer‘s id |
Response Explanation
Public Response Parameters
Successful Response
| Fields | Fields of object | Type | Desc |
|---|---|---|---|
| count | int | Total number of records in this query. | |
| next_token | string | The next positioning of the cursor (requires submission of the previous query conditions). | |
| Array of Order | id | string | Unique identifier for the order. |
| number | string | Order number, intended to simplify merchant references. | |
| note | string | A custom note input by the merchant regarding the order. | |
| status | string | The current Order status | |
| financial_status | string | Indicates the payment status of the order | |
| fulfillment_status | string | Represents the shipping or fulfillment progress of the order | |
| email_status | string | The status of recall emails for the order.waiting means “pending to send”send means “sent” | |
| cancel_reason | string | Reason for order cancellation, if applicable. | |
| recovery_status | string | The recovery_status field tracks the progress of an order recall processwaiting means “Waiting to be recalled”sending means “Recall notification in progress”recalling means “Recall in progress)”failed means “Recall failed)”success means “Recall successful)” | |
| payment_method | string | The payment method used for the order (e.g., apple_pay, credit_card, online). | |
| string | @Deprecated. | ||
| discount_applications | string | Details of discounts | |
| customer_note | string | A note provided by the customer during checkout. | |
| string | @Deprecated. | ||
| buyer_accepts_marketing | bool | Indicates whether the customer has agreed to receive marketing promotions. | |
| currency | string | Currency code for the order | |
| total_price | string | The final price paid by the customer, including taxes, discounts, tips, additional fee and shipping fees. | |
| sub_total | string | The sum of the prices for all line items in the order. - If order.config.product_tax_included is true, the amount includes total_tax (excluding shipping_tax_total); otherwise, it excludes tax. - Formula: sub_total = sum(line_item.price * line_item.quantity). | |
| total_discount | string | Total amount of discounts applied to the order, including product, shipping, and payment discounts. | |
| total_tax | string | Total tax amount applied to the products in the order， excluding shipping tax. | |
| total_shipping | string | Total shipping fee for the order. | |
| code_discount_total | string | Total discount from discount codes applied to the order. | |
| string | @Deprecated.total Product discount, numeric string, for example: "9.99",includes code_discount_total | ||
| gift_card_total | string | Gift card discount amount, numeric string, for example: "9.99" | |
| total_refund_price | string | Total refund amount has been successfully processed, numeric string, for example: "9.99" | |
| string | @Deprecated.Total discount refunded, numeric string, for example: "9.99" | ||
| additional_total | string | Total amount of additional charges, numeric string, for example: "9.99" | |
| addtional_prices | array of object | the detail list of additional charges | |
| addtional_prices.name | string | Name of the additional charge. | |
| addtional_prices.price | string | Amount of the additional charge. | |
| string | @Deprecated. | ||
| shipping_tax_total | string | Total shipping tax amount of the order. | |
| customer_deleted_at | string | Timestamp indicating when the customer associated with the order was deleted. | |
| created_at | string | Timestamp indicating when the order was created. | |
| updated_at | string | Timestamp indicating when the order was updated. | |
| deleted_at | string | Timestamp indicating when the order was deleted. | |
| canceled_at | string | Timestamp indicating when the order was canceled. | |
| placed_at | string | Timestamp indicating when the order was paid. | |
| total_tip_received | string | Total amount of tips received for the order. | |
| tags | string | Custom tags added to the order by merchants or the system. | |
| string | @Deprecated. IP address of the customer who placed the order. | ||
| string | @Deprecated. URL of the last page visited by the customer before checkout. | ||
| total_paid | string | Total amount paid by the customer for the order. | |
| string | @Deprecated.Product source url | ||
| object | @Deprecated. Product source | ||
| string | @Deprecated. Product source | ||
| string | @Deprecated. Timestamp of the creation | ||
| object | @Deprecated. Last interaction source | ||
| string | @Deprecated. Interaction source data. | ||
| string | @Deprecated. Timestamp of the last interaction. | ||
| shipping_line | object | Information about the shipping plan selected for the order. | |
| shipping_line.name | string | Name of the shipping plan. | |
| customer | Customer | Customer details | |
| shipping_address | Address | Delivery address | |
| billing_address | Address | Billing address | |
| payment_line | PaymentLine | Payment details | |
| line_items | array of LineItem | List of purchased products | |
| fulfillments | array of Fulfillment | List of fulfillments | |
| logistics_code | string | Logistics code | |
| refer_info | string | Visit information | |
| config | OrderConfig | Order configuration information | |
| string | @Deprecated. Platform where the order was placed | ||
| checkout_url | string | The checkout page url for the order with storeDomain | |
| location_line | LocationLine | Merchant's warehouse address. | |
| invoice_url | string | The checkout page url for the order without storeDomain |
Error Response
Error responses in the API can be represented using two different fields: errors and error. Both fields provide details about issues encountered during request processing. Below is an explanation of the fields with their respective examples and descriptions.
| Field | Type | Example | Description |
|---|---|---|---|
errors | Array | [ "file number error"] | A list of errors encountered during the request processing. |
| Field | Type | Example | Description |
|---|---|---|---|
error | String | "store is not active" | Indicates an error encountered during the process |
Error Detail
| ErrorCode | Description | Possible reasons |
|---|---|---|
| 406 | 1:per_page too large 2:deep pagination not allowed | |
| 500 | StatusInternalServerError | Aborted/NotFound/Unimplemented/Unauthenticated/DeadlineExceeded |
| 400 | 1:invalid sort_by param 2:invalid sort_direction param |