API Reference

Complete reference for all Ultimate Custom Order Status API endpoints

Overview

The Ultimate Custom Order Status API provides programmatic access to manage order statuses, send notifications, and retrieve order information. All endpoints require authentication and follow RESTful conventions.

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

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/status

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

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

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

Read more
POST/v1/orders/status-bulk

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

Read more
POST/v1/orders/notify-bulk

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

Read more

Authentication

All API requests require authentication using API keys. To get started, you'll need to generate an API key from your app's settings:

  1. Navigate to your Ultimate Custom Order Status app
  2. Go to Settings → API Keys
  3. Click "Generate New API Key"
  4. Configure the appropriate permissions for your use case
  5. Save the API key securely (it will only be shown once)

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

Required Authentication Header
X-API-Key: your_api_key_here

Learn more in the Authentication Guide

Rate Limiting

All API endpoints are subject to rate limiting to ensure service stability. Rate limits are applied per API key with two separate windows:

  • Per-minute limit: Configurable per API key (default: 60 requests/minute)
  • Per-day limit: Configurable per API key (default: 10,000 requests/day)

Rate limit information is included in 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 (only present when rate limited)

Error Handling

The API uses standard HTTP status codes to indicate success or failure:

200 OK-Request succeeded
400 Bad Request-Invalid request parameters
401 Unauthorized-Missing or invalid authentication
403 Forbidden-Insufficient permissions
404 Not Found-Resource not found
500 Server Error-Internal server error