Ultimate Custom Order Status API

Programmatically manage order statuses, send notifications, and retrieve order data

Current and default version 1.6. Every endpoint accepts 1.0–1.6; send X-API-Version for 1.0–1.5.

Getting Started

The Ultimate Custom Order Status API allows you to programmatically interact with your order management system. You can retrieve orders, update statuses, send customer notifications, and more.

Base URL

API Base URL
https://api.ultimate-custom-order-status.apps.msmtech.ca/api

API Versioning

The API uses a two-tier versioning system with major versions in the URL and minor versions specified via the X-API-Version header.

Current Version

Versions 1.0–1.6 are accepted; 1.6 is current and default. A request without X-API-Version is served 1.6, and the X-API-Version response header reports which version served the request.

Using a Specific Version with the X-API-Version Header
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.6"

Default Behavior

A request without X-API-Version is served by 1.6. X-API-Version-Current and X-API-Version-Default both report 1.6; sending X-API-Version: 1.5 still returns the unchanged 1.5 payload.

Response Headers for a Request Without X-API-Version
X-API-Version: 1.6
X-API-Version-Current: 1.6
X-API-Version-Default: 1.6

Order ID Types

The API supports two types of order identifiers. You can choose which type to use based on your integration needs:

  • •Internal UUID: Unique identifier assigned by our system (e.g., 550e8400-e29b-41d4-a716-446655440000). This is the default.
  • •Shopify Order ID: Numeric ID from Shopify's GID format (e.g., extract 450789469 from gid://shopify/Order/450789469).
  • •Use the use_shopify_order_id parameter (query or body depending on endpoint) set to true to look up orders using Shopify IDs instead of internal UUIDs.

Available Endpoints

GET/v1/orders

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

Read more
GET/v1/orders/:order_id

Retrieve detailed information about a specific order by its ID.

Read more
GET/v1/statuses

Retrieve a list of all custom order statuses configured in your system.

Read more
GET/v1/statuses/:status_id

Retrieve detailed information about a specific custom order status by its ID.

Read more
POST/v1/orders/:order_id/notify

Forcibly send customer notifications (email, SMS, WhatsApp) for a specific order.

Read more
POST/v1/orders/:order_id/status

Update the custom status of a specific order. Automatically sends notifications based on status configuration.

Read more
POST/v1/orders/notify-bulk

Send notifications to customers for multiple orders in a single request.

Read more
POST/v1/orders/status-bulk

Update the custom status for multiple orders in a single request.

Read more
GET/v1/workflows

Retrieve all configured workflows with their associated statuses and settings.

Read more
POST/v1/line-items/:lineItemId/status

Change the status of a single line item. Triggers notifications when configured on the target status.

Read more
POST/v1/line-items/status-bulk

Change the status of multiple line items to the same target status in a single batch. Maximum 100 line items per request.

Read more
POST/v1/line-items/clear-status

Remove the current status (and sub-status) from one or more line items. Maximum 100 line items per request.

Read more
POST/v1/orders/:order_id/workflow

Reassign an order to a different workflow. The move applies a starting status from the target workflow and carries the status change and the fulfilment it triggers.

Read more

Quick Start

1. Generate an API key from your dashboard

Navigate to your app's Settings → API Keys section to generate a new API key. Make sure to save it securely as it will only be shown once.

Authentication Header

Include your API key in the X-API-Key header with every request:

Required Authentication Header
X-API-Key: ucos_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

2. Make your first API request with proper authentication

Example API 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.6"

3. Handle the Response

All responses use the same JSON envelope: { "success": true, "data": { ... } } on success, and { "success": false, "error": "..." } on failure. Check success before reading the payload.

Next Steps