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: your_api_key_here

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'

Response

Returns a JSON object with the following structure:

200 OK - Success Response

{
  "orders": [
    {
      "id": "uuid",
      "shopify_order_id": "gid://shopify/Order/123456789",
      "name": "#1001",
      "created_at": "2024-10-30T12:00:00Z",
      "custom_status": {
        "id": "status-uuid",
        "name": "Processing",
        "color": "#2948ff"
      },
      "custom_sub_status": {
        "id": "sub-status-uuid",
        "name": "Awaiting Parts"
      },
      "customer": {
        "first_name": "John",
        "last_name": "Doe",
        "email": "john@example.com",
        "phone": "+1234567890"
      },
      "shipping_address": {
        "company": "Acme Corp",
        "address1": "123 Main St",
        "address2": "Suite 100",
        "city": "New York",
        "province": "NY",
        "zip": "10001",
        "country": "United States",
        "latitude": "40.7128",
        "longitude": "-74.0060"
      },
      "total_price": "150.00",
      "currency": "USD",
      "line_items": [
        {
          "id": "line-item-uuid",
          "shopify_line_item_id": "gid://shopify/LineItem/123456789",
          "name": "Product Name",
          "quantity": 2
        }
      ],
      "note": "Please ship carefully",
      "cancelled": false,
      "cancelled_at": null
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 25,
    "total_count": 100,
    "total_pages": 4,
    "has_next_page": true,
    "has_previous_page": false
  }
}

Response Fields

Root Response Object

Field	Type	Description
`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 \| null	Custom status information
`custom_sub_status`	object \| null	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
`note`	string \| null	Order note/comments
`cancelled`	boolean \| null	Whether the order is cancelled
`cancelled_at`	string \| null	ISO 8601 timestamp when order was cancelled

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

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" \
  -H "X-API-Key: your_api_key_here"

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: your_api_key_here"

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: your_api_key_here"

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: your_api_key_here"

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: your_api_key_here"

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

{
  "error": "Invalid query parameters",
  "details": {
    "errors": { ... }
  }
}

401 Unauthorized

Missing or invalid API key

401 Unauthorized

{
  "error": "Unauthorized"
}

403 Forbidden

API key lacks required permissions

403 Forbidden

{
  "error": "Insufficient permissions"
}

500 Internal Server Error

Server error occurred

500 Internal Server Error

{
  "error": "Failed to fetch orders",
  "details": {
    "message": "Error details..."
  }
}