GET
List orders
Retrieve a paginated list of orders with filtering, sorting, and search capabilities.
GET
/v1/ordersAuthentication
This endpoint requires a valid API key with
canViewOrders permission. The API key must be passed in the X-API-Key header.X-API-Key: ucos_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXQuery parameters
| Parameter | Description |
|---|---|
| pageinteger · Optional, default 1 | Page number for pagination |
| limitinteger · Optional, default 25 | Results per page (max: 250) |
| statusstring · Optional | Filter by custom status ID |
| searchstring · Optional | Search in order name, customer name, company, or email |
| order_idsstring · Optional | Comma-separated list of order IDs; repeating order_ids (order_ids=a&order_ids=b) also works, at every version since the 1.6 release. By default, expects internal UUIDs. When use_shopify_order_id is true, provide the numeric portion of Shopify's order GID (e.g., for 'gid://shopify/Order/450789469', use '450789469') |
| use_shopify_order_idboolean · Optional, default false | Set to 'true' to use Shopify order IDs instead of internal UUIDs. Extract the number from Shopify's GID format (gid://shopify/Order/450789469 → 450789469) and pass it in order_ids |
| sort_bystring · Optional, default created_at | Field to sort by: 'created_at' or 'name' |
| sort_orderstring · Optional, default desc | Sort direction: 'asc' or 'desc' |
| order_typestring · Optional, default ALL | Filter by order type: REGULAR (standard orders), DRAFT (draft orders), or ALL (both types). Available in v1.2+ |
| workflow_idstring · Optional | Filter orders by workflow UUID. Only returns orders assigned to this workflow. Available in v1.3+ |
Response
Returns a JSON object with the following structure:
{
"success": true,
"data": {
"orders": [
{
"id": "string",
"shopify_order_id": "string",
"name": "string",
"created_at": "string",
"custom_status": {
"id": "string",
"name": "string",
"color": "string"
},
"custom_sub_status": {
"id": "string",
"name": "string"
},
"customer": {
"first_name": "string",
"last_name": "string",
"email": "string",
"phone": "string"
},
"shipping_address": {
"company": "string",
"address1": "string",
"address2": "string",
"city": "string",
"province": "string",
"zip": "string",
"country": "string",
"latitude": "string",
"longitude": "string"
},
"total_price": "string",
"currency": "string",
"line_items": [
{
"id": "string",
"shopify_line_item_id": "string",
"name": "string",
"quantity": 0,
"title": "string",
"variant_title": "string",
"sku": "string",
"shopify_product_id": null,
"shopify_variant_id": null,
"custom_status": {
"id": "string",
"name": "string",
"color": "string"
},
"custom_sub_status": {
"id": "string",
"name": "string"
}
}
],
"note": "string",
"cancelled": true,
"cancelled_at": null,
"addon_statuses": [
{
"id": "string",
"name": "string",
"display_name": "string",
"color": "string",
"sub_status": {
"id": "string",
"name": "string"
},
"assigned_at": "string"
}
],
"workflow_id": null,
"workflow_name": null
}
],
"pagination": {
"page": 0,
"limit": 0,
"total_count": 0,
"total_pages": 0,
"has_next_page": true,
"has_previous_page": true
}
}
}Response fields
Root response object
| Field | Description |
|---|---|
| successboolean | Always true on a successful response. |
| dataobject | The endpoint's payload. Its fields are listed in the tables below. |
| ordersarray | Array of order objects |
| paginationobject | Pagination information |
Order object
| Field | Description |
|---|---|
| idstring | Unique identifier for the order (UUID) |
| shopify_order_idstring | Shopify's global ID for the order |
| namestring | Order number (e.g., #1001) |
| created_atstring | null | ISO 8601 timestamp when order was created in Shopify |
| custom_statusobject | Custom status information |
| custom_sub_statusobject | Custom sub-status information |
| customerobject | Customer information |
| shipping_addressobject | Shipping address information |
| total_pricestring | null | Total order price |
| currencystring | null | Currency code (e.g., USD, CAD) |
| line_itemsarray | Array of line item objects |
| notestring | null | Order note/comments |
| cancelledboolean | Whether the order is cancelled |
| cancelled_atstring | null | ISO 8601 timestamp when order was cancelled |
| addon_statusesarray | Array of addon status objects (v1.1+ only) |
| workflow_idstring | null | UUID of the workflow this order belongs to (v1.3+ only) |
| workflow_namestring | null | Name of the workflow this order belongs to (v1.3+ only) |
Status object fields
| Field | Description |
|---|---|
| idstring | Unique identifier for the custom status |
| namestring | Display name of the status (uses public name if configured) |
| colorstring | Hex color code for the status |
Sub-status object
| Field | Description |
|---|---|
| idstring | Unique identifier for the sub-status |
| namestring | Name of the sub-status |
Customer object fields
| Field | Description |
|---|---|
| first_namestring | null | Customer's first name |
| last_namestring | null | Customer's last name |
| emailstring | null | Customer's email address |
| phonestring | null | Customer's phone number |
Shipping address object fields
| Field | Description |
|---|---|
| companystring | null | Company name |
| address1string | null | Primary address line |
| address2string | null | Secondary address line |
| citystring | null | City name |
| provincestring | null | State/Province code |
| zipstring | null | Postal/ZIP code |
| countrystring | null | Country name |
| latitudestring | null | Latitude coordinate |
| longitudestring | null | Longitude coordinate |
Line item object fields
| Field | Description |
|---|---|
| idstring | Unique identifier for the line item |
| shopify_line_item_idstring | Shopify's global ID for the line item |
| namestring | Product name |
| quantitynumber | Quantity ordered |
| titlestring | null | Product title |
| variant_titlestring | null | Variant title, or null |
| skustring | null | SKU, or null |
| shopify_product_idstring | null | Shopify product GID, or null |
| shopify_variant_idstring | null | Shopify variant GID, or null |
| custom_statusobject | Current status object, or null. |
| custom_sub_statusobject | Current sub-status object, or null. |
Addon status object fields
| Field | Description |
|---|---|
| idstring | Unique identifier for the addon status |
| namestring | Internal name of the addon status |
| display_namestring | Public name of the addon status when it uses one, otherwise its name |
| colorstring | Hex color code for the addon status |
| sub_statusobject | Optional sub-status for the addon |
| assigned_atstring | Timestamp when the addon status was assigned to the order or line item |
Addon sub-status object
| Field | Description |
|---|---|
| idstring | Unique identifier for the addon sub-status |
| namestring | Name of the addon sub-status |
Pagination object fields
| Field | Description |
|---|---|
| pagenumber | Current page number |
| limitnumber | Results per page |
| total_countnumber | Total number of orders matching the query |
| total_pagesnumber | Total number of pages |
| has_next_pageboolean | Whether there is a next page |
| has_previous_pageboolean | Whether there is a previous page |
Examples
Basic request
curl -X GET "https://api.ultimate-custom-order-status.apps.msmtech.ca/api/v1/orders?page=1&limit=25&use_shopify_order_id=false&sort_by=created_at&sort_order=desc&order_type=ALL" \
-H "X-API-Key: ucos_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
-H "X-API-Version: 1.5"Filter by status
curl -X GET "https://api.ultimate-custom-order-status.apps.msmtech.ca/api/v1/orders?status=abc123&sort_by=created_at&sort_order=desc" \
-H "X-API-Key: ucos_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
-H "X-API-Version: 1.5"Get specific orders by UUID
curl -X GET "https://api.ultimate-custom-order-status.apps.msmtech.ca/api/v1/orders?order_ids=uuid1,uuid2,uuid3" \
-H "X-API-Key: ucos_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
-H "X-API-Version: 1.5"Get specific orders by Shopify order ID
curl -X GET "https://api.ultimate-custom-order-status.apps.msmtech.ca/api/v1/orders?order_ids=5460132438316,5460132438317&use_shopify_order_id=true" \
-H "X-API-Key: ucos_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
-H "X-API-Version: 1.5"Search orders
curl -X GET "https://api.ultimate-custom-order-status.apps.msmtech.ca/api/v1/orders?search=john@example.com&page=1&limit=50" \
-H "X-API-Key: ucos_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
-H "X-API-Version: 1.5"Get draft orders (v1.2+)
curl -X GET "https://api.ultimate-custom-order-status.apps.msmtech.ca/api/v1/orders?order_type=DRAFT&page=1&limit=25" \
-H "X-API-Key: ucos_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
-H "X-API-Version: 1.5"Get regular orders (v1.2+)
curl -X GET "https://api.ultimate-custom-order-status.apps.msmtech.ca/api/v1/orders?order_type=REGULAR&page=1&limit=25" \
-H "X-API-Key: ucos_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
-H "X-API-Version: 1.5"Get all orders (v1.2+)
curl -X GET "https://api.ultimate-custom-order-status.apps.msmtech.ca/api/v1/orders?order_type=ALL&page=1&limit=25" \
-H "X-API-Key: ucos_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
-H "X-API-Version: 1.5"Filter by workflow (v1.3+)
curl -X GET "https://api.ultimate-custom-order-status.apps.msmtech.ca/api/v1/orders?workflow_id=uuid-workflow-1&page=1&limit=25" \
-H "X-API-Key: ucos_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
-H "X-API-Version: 1.5"Rate limiting
This endpoint is subject to per-minute and per-day rate limits based on your API key. Rate limit information is returned in the response headers:
X-RateLimit-Limit-Minute: Maximum requests per minuteX-RateLimit-Remaining-Minute: Remaining requests in current minuteX-RateLimit-Reset-Minute: Unix timestamp when minute window resetsX-RateLimit-Limit-Day: Maximum requests per dayX-RateLimit-Remaining-Day: Remaining requests in current dayX-RateLimit-Reset-Day: Unix timestamp when day window resetsRetry-After: Seconds to wait before retrying (when rate limited)
Error responses
400 Bad Request
Invalid query parameters
{
"success": false,
"error": "Validation failed",
"details": {
"errors": [
{
"code": "invalid_type",
"expected": "string",
"received": "undefined",
"path": [
"status_id"
],
"message": "Required"
}
]
}
}401 Unauthorized
Missing or invalid API key
{
"success": false,
"error": "Missing API key. Include it in the X-API-Key header"
}403 Forbidden
API key lacks required permissions
{
"success": false,
"error": "Insufficient permissions. Required: canViewOrders"
}500 Internal Server Error
Server error occurred
{
"success": false,
"error": "Internal server error",
"details": {
"message": "An unexpected error occurred"
}
}