GET

List Orders

Retrieve a paginated list of orders with filtering, sorting, and search capabilities.

Endpoint

HTTP Request

GET /v1/orders

Authentication

This endpoint requires a valid API key with canViewOrders permission. The API key must be passed in the X-API-Key header.

Required Header

X-API-Key: ucos_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Query Parameters

Parameter	Type	Required	Default	Description
`page`	number	No	1	Page number for pagination
`limit`	number	No	25	Results per page (max: 250)
`status`	string	No	-	Filter by custom status ID
`order_ids`	string	No	-	Comma-separated list of order IDs. 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_id`	boolean	No	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
`search`	string	No	-	Search in order name, customer name, company, or email
`sort_by`	string	No	created_at	Field to sort by: 'created_at' or 'name'
`sort_order`	string	No	desc	Sort direction: 'asc' or 'desc'
`order_type`	string	No	ALL (v1.2), REGULAR (v1.0, v1.1)	Filter by order type: REGULAR (standard orders), DRAFT (draft orders), or ALL (both types). Available in v1.2+
`workflow_id`	string	No	-	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:

200 OK - Success Response

{
  "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	Type	Description
`success`	boolean	Always true on a successful response.
`data`	object	The endpoint's payload. Its fields are listed in the tables below.
`orders`	array	Array of order objects
`pagination`	object	Pagination information

Order Object

Field	Type	Description
`id`	string	Unique identifier for the order (UUID)
`shopify_order_id`	string	Shopify's global ID for the order
`name`	string	Order number (e.g., #1001)
`created_at`	string \| null	ISO 8601 timestamp when order was created in Shopify
`custom_status`	object	Custom status information
`custom_sub_status`	object	Custom sub-status information
`customer`	object	Customer information
`shipping_address`	object	Shipping address information
`total_price`	string \| null	Total order price
`currency`	string \| null	Currency code (e.g., USD, CAD)
`line_items`	array	Array of line item objects
`addon_statuses`	array	Array of addon status objects (v1.1+ only)
`note`	string \| null	Order note/comments
`cancelled`	boolean	Whether the order is cancelled
`cancelled_at`	string \| null	ISO 8601 timestamp when order was cancelled
`workflow_id`	string \| null	UUID of the workflow this order belongs to (v1.3+ only)
`workflow_name`	string \| null	Name of the workflow this order belongs to (v1.3+ only)

Status Object Fields

Field	Type	Description
`id`	string	Unique identifier for the custom status
`name`	string	Display name of the status (uses public name if configured)
`color`	string	Hex color code for the status

Sub-Status Object

Field	Type	Description
`id`	string	Unique identifier for the sub-status
`name`	string	Name of the sub-status

Customer Object Fields

Field	Type	Description
`first_name`	string \| null	Customer's first name
`last_name`	string \| null	Customer's last name
`email`	string \| null	Customer's email address
`phone`	string \| null	Customer's phone number

Shipping Address Object Fields

Field	Type	Description
`company`	string \| null	Company name
`address1`	string \| null	Primary address line
`address2`	string \| null	Secondary address line
`city`	string \| null	City name
`province`	string \| null	State/Province code
`zip`	string \| null	Postal/ZIP code
`country`	string \| null	Country name
`latitude`	string \| null	Latitude coordinate
`longitude`	string \| null	Longitude coordinate

Line Item Object Fields

Field	Type	Description
`id`	string	Unique identifier for the line item
`shopify_line_item_id`	string	Shopify's global ID for the line item
`name`	string	Product name
`quantity`	number	Quantity ordered
`title`	string \| null	Product title
`variant_title`	string \| null	Variant title, or null
`sku`	string \| null	SKU, or null
`shopify_product_id`	string \| null	Shopify product GID, or null
`shopify_variant_id`	string \| null	Shopify variant GID, or null

Addon Status Object Fields

Field	Type	Description
`id`	string	Unique identifier for the addon status
`name`	string	Display name of the addon status
`display_name`	string	Public display name of the addon status
`assigned_at`	string	Timestamp when the addon status was assigned to the order
`color`	string	Hex color code for the addon status
`sub_status`	object	Optional sub-status for the addon

Addon Sub-Status Object

Field	Type	Description
`id`	string	Unique identifier for the addon sub-status
`name`	string	Name of the addon sub-status

Pagination Object Fields

Field	Type	Description
`page`	number	Current page number
`limit`	number	Results per page
`total_count`	number	Total number of orders matching the query
`total_pages`	number	Total number of pages
`has_next_page`	boolean	Whether there is a next page
`has_previous_page`	boolean	Whether there is a previous page

Examples

Basic Request

cURL 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 Request

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 Request

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 Request

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 Request

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 Request

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 Request

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 Request

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 Request

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 minute
X-RateLimit-Remaining-Minute: Remaining requests in current minute
X-RateLimit-Reset-Minute: Unix timestamp when minute window resets
X-RateLimit-Limit-Day: Maximum requests per day
X-RateLimit-Remaining-Day: Remaining requests in current day
X-RateLimit-Reset-Day: Unix timestamp when day window resets
Retry-After: Seconds to wait before retrying (when rate limited)

Error Responses

400 Bad Request

Invalid query parameters

400 Bad Request

{
  "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

401 Unauthorized

{
  "success": false,
  "error": "Missing API key. Include it in the X-API-Key header"
}

403 Forbidden

API key lacks required permissions

403 Forbidden

{
  "success": false,
  "error": "Insufficient permissions. Required: canViewOrders"
}

500 Internal Server Error

Server error occurred

500 Internal Server Error

{
  "success": false,
  "error": "Internal server error",
  "details": {
    "message": "An unexpected error occurred"
  }
}