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.
Requires
read_orderaccess scope. More access scope
The Order Count API provides the total number of orders matching the specified query parameters. This enables users to retrieve aggregate order data for analytics or filtering purposes.
This API is especially useful for:
- Monitoring the total number of orders in a given time period.
- Filtering orders based on specific statuses like
opened,placed,finished, orcancelled. - Analyzing orders based on financial and fulfillment statuses.
Request Parameters
Public Request Parameters
Request Query Parameters
| Parameter Name | Type | Required | Description | Example Value |
|---|---|---|---|---|
| created_at_min | string | No | Filters orders created at or after the specified date and time. | 2016-01-18T23:41:00Z |
| created_at_max | string | No | Filters orders created at or before the specified date and time. | 2016-01-18T23:41:00Z |
| updated_at_min | string | No | Filters orders updated at or after the specified date and time. | 2016-01-18T23:41:00Z |
| updated_at_max | string | No | Filters orders updated at or before the specified date and time. | 2016-01-18T23:41:00Z |
| status | string | No | Filters orders by their current status. Possible values: opened (active), placed (not yet processed), finished (completed), cancelled (canceled). | opened |
| financial_status | string | No | Filters orders by their financial status. Possible values: waiting (awaiting payment), paying (in progress), paid (completed), cancelled (canceled), failed (payment failed), refunding (refund in progress), refund_failed (refund failed), refunded (completed), partially_refunded (partial refund issued). | paid |
| fulfillment_status | string | No | Filters orders by their fulfillment status. Possible values: initialled (initialized), waiting (awaiting fulfillment), partially_shipped (partially shipped), shipped (fully shipped), partially_finished (partially completed), finished (fully completed), cancelled (canceled), returning (in return process), returned (fully returned), partially_returned (partially returned). | shipped |
Response Explanation
Public Response Parameters
Successful Response
| Name | Type | Description | Example |
|---|---|---|---|
count | int | Total number of records in this query. | 7 |
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
| Status Code | Message | Possible Reason | Example Response |
|---|---|---|---|
| 400 | Bad Request | Invalid input format or request structure (e.g., missing required fields or incorrect data types). | Bad Request |
| Unauthorized | The request is missing valid authentication credentials or the credentials provided are invalid. | Unauthorized | |
| 422 | Unprocessable Entity | invalid time field input | "created_at_min time format error", "created_at_max time format error", "UpdatedAtMin time format error", "UpdatedAtMax time format error", |