GET

Get Order

Retrieve detailed information about a specific order by its ID.

Endpoint

HTTP Request

GET /v1/orders/:order_id

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

URL Parameters

Parameter	Type	Required	Description
`order_id`	string	Yes	Order identifier (UUID by default, or Shopify order ID numeric portion if use_shopify_order_id query parameter is true). For Shopify order IDs, extract the number from the GID format (e.g., for 'gid://shopify/Order/450789469', use '450789469').

Query Parameters

Parameter	Type	Required	Default	Description
`use_shopify_order_id`	boolean	No	false	Set to 'true' to look up order using Shopify order ID instead of UUID. Extract the number from Shopify's GID format (gid://shopify/Order/450789469 → 450789469) and use it in the order_id path parameter.

Response

Returns a JSON object with the order details:

200 OK - Success Response

{
  "order": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "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"
    },
    "addon_statuses": [
      {
        "id": "addon-uuid-1",
        "name": "Quality Check",
        "color": "#10b981",
        "sub_status": {
          "id": "addon-sub-uuid",
          "name": "Passed"
        }
      },
      {
        "id": "addon-uuid-2",
        "name": "Packaging",
        "color": "#f59e0b",
        "sub_status": null
      }
    ],
    "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,
    "workflow_id": "uuid-workflow-1",
    "workflow_name": "Fulfillment"
  }
}

Response Fields

Root Response Object

Field	Type	Description
`order`	object	The order object containing all order details

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	ISO 8601 timestamp when order was created in Shopify
`custom_status`	object	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	Total order price
`currency`	string	Currency code (e.g., USD, CAD)
`line_items`	array	Array of line item objects
`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	Customer's first name
`last_name`	string	Customer's last name
`email`	string	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	Primary address line
`address2`	string \| null	Secondary address line
`city`	string	City name
`province`	string	State/Province code
`zip`	string	Postal/ZIP code
`country`	string	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

Examples

Basic Request (UUID)

cURL Request

curl -X GET "https://api.ultimate-custom-order-status.apps.msmtech.ca/api/v1/orders/550e8400-e29b-41d4-a716-446655440000" \
  -H "X-API-Key: your_api_key_here" \
  -H "X-API-Version: 1.3"

Using Shopify Order ID

cURL Request

curl -X GET "https://api.ultimate-custom-order-status.apps.msmtech.ca/api/v1/orders/5460132438316?use_shopify_order_id=true" \
  -H "X-API-Key: your_api_key_here" \
  -H "X-API-Version: 1.3"

Get Draft Order (v1.2+)

cURL Request

curl -X GET "https://api.ultimate-custom-order-status.apps.msmtech.ca/api/v1/orders/1234567890?use_shopify_order_id=true" \
  -H "X-API-Key: your_api_key_here" \
  -H "X-API-Version: 1.3"

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 order ID format

400 Bad Request

{
  "error": "Invalid order ID format",
  "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"
}

404 Not Found

Order not found or doesn't belong to this shop

404 Not Found

{
  "error": "Order not found",
  "details": {
    "orderId": "550e8400-e29b-41d4-a716-446655440000"
  }
}

500 Internal Server Error

Server error occurred

500 Internal Server Error

{
  "error": "Internal server error",
  "details": {
    "message": "Error description"
  }
}