Ultimate Custom Order Status API

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

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

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.5 are accepted; 1.5 is current and default. A request without X-API-Version is served 1.5, 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.5"

Default Behavior

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

Response Headers for a Request Without X-API-Version

X-API-Version: 1.5
X-API-Version-Current: 1.5
X-API-Version-Default: 1.5

View Full Changelog

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.

GET/v1/orders/:order_id

Retrieve detailed information about a specific order by its ID.

GET/v1/statuses

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

GET/v1/statuses/:status_id

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

POST/v1/orders/:order_id/notify

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

POST/v1/orders/:order_id/status

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

POST/v1/orders/notify-bulk

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

POST/v1/orders/status-bulk

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

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.

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.5"

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.