POST

Update Status

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

Endpoint

HTTP Request

POST /v1/orders/:order_id/status

Authentication

This endpoint requires a valid API key with canChangeOrderStatus permission. The API key must be passed in the X-API-Key header.

Required Header

X-API-Key: your_api_key_here

Path Parameters

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

Request Body

Parameter	Type	Required	Default	Description
`status_id`	string	Yes	-	The UUID of the custom status
`sub_status_option_id`	string	Conditional	-	The UUID of the sub-status option. Required if the status has sub-status options.
`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 confirmation with updated order details:

200 OK - Success Response

{
  "message": "Order status updated successfully",
  "order": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "shopify_order_id": "gid://shopify/Order/123456789",
    "name": "#1001",
    "status": {
      "id": "status-uuid-abc123",
      "name": "Processing",
      "color": "#2948ff"
    },
    "sub_status": {
      "id": "sub-status-uuid-def456",
      "name": "Awaiting Parts"
    }
  },
  "notifications": {
    "total_sent": 2,
    "total_failed": 0,
    "by_channel": {
      "email": {
        "sent": 1,
        "failed": 0
      },
      "sms": {
        "sent": 1,
        "failed": 0
      }
    }
  }
}

Response Fields

Root Response Object

Field	Type	Description
`message`	string	Confirmation message
`order`	object	Object containing updated order details
`notifications`	object	Object containing notification delivery statistics

Order Object

Field	Type	Description
`id`	string	Order UUID
`shopify_order_id`	string	Shopify order ID
`name`	string	Shopify order name/number
`status`	object \| null	Status object with id, name, and color
`sub_status`	object \| null	Sub-status object with id and name (if applicable)

Status Object Fields

Field	Type	Description
`id`	string	UUID of the status
`name`	string	Display name of the status
`color`	string	Hex color code of the status

Sub-Status Object

Field	Type	Description
`id`	string	UUID of the sub-status
`name`	string	Name of the sub-status

Notifications Object Fields

Field	Type	Description
`total_sent`	number	Total number of notifications sent
`total_failed`	number	Total number of notifications that failed
`by_channel`	object	Breakdown of notifications by channel (email, SMS, WhatsApp)

common.responseTables.channelStatsObject

Field	Type	Description
`sent`	number	Number of notifications sent for this channel
`failed`	number	Number of notifications failed for this channel

Examples

Basic Request (UUID)

cURL Request

curl -X POST "https://api.ultimate-custom-order-status.apps.msmtech.ca/api/v1/orders/550e8400-e29b-41d4-a716-446655440000/status" \
  -H "X-API-Key: your_api_key_here" \
  -H "X-API-Version: 1.2" \
  -H "Content-Type: application/json" \
  -d '{
    "status_id": "status-uuid-abc123",
    "sub_status_option_id": "sub-status-uuid-def456"
  }'

Using Shopify Order ID

cURL Request

curl -X POST "https://api.ultimate-custom-order-status.apps.msmtech.ca/api/v1/orders/5460132438316/status" \
  -H "X-API-Key: your_api_key_here" \
  -H "X-API-Version: 1.2" \
  -H "Content-Type: application/json" \
  -d '{
    "status_id": "status-uuid-abc123",
    "sub_status_option_id": "sub-status-uuid-def456",
    "use_shopify_order_id": true
  }'

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 request body, validation failed, or status requires a sub-status

400 Bad Request

{
  "error": "Validation failed",
  "details": {
    "errors": [...]
  }
}

401 Unauthorized

Missing or invalid API key

401 Unauthorized

{
  "error": "Unauthorized"
}

403 Forbidden

API key lacks required permissions or product chain enforcement prevents this status change

403 Forbidden

{
  "error": "Insufficient permissions"
}

404 Not Found

Order, status, or sub-status not found

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"
  }
}