POST

Bulk Update Status

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

Endpoint

HTTP Request

POST /v1/orders/status-bulk

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: ucos_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Request Body

Parameter	Type	Required	Default	Description
`order_ids`	string[]	Yes	-	Array of order identifiers (UUIDs by default, or Shopify order IDs if use_shopify_order_id is true). For Shopify order IDs, provide the numeric portion of Shopify's order GID (e.g., for 'gid://shopify/Order/450789469', use '450789469').
`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 orders using Shopify order IDs instead of UUIDs. Extract the number from Shopify's GID format (gid://shopify/Order/450789469 → 450789469) and use it in the order_ids array.
`fulfillment_selections`	object	No	-	Optional (v1.5) answer to a fulfillment_readiness block: { [shopOrderId]: { [fulfillmentOrderId]: locationId } }.

Response

Returns confirmation with count of updated orders:

200 OK - Success Response

{
  "success": true,
  "data": {
    "message": "string",
    "updated_count": 0,
    "notifications": {
      "total_sent": 0,
      "total_failed": 0,
      "by_channel": {}
    },
    "orders_fulfilled": 0,
    "fulfillment_errors": [
      {
        "channel": "string",
        "code": "string",
        "message": "string"
      }
    ]
  }
}

Response Fields

Root Response Object

Field	Type	Description
`success`	boolean	Always true on a successful response.
`data`	object	The endpoint's payload. Its fields are listed in the tables below.
`message`	string	Confirmation message
`updated_count`	number	Number of orders successfully updated
`notifications`	object	Object containing notification statistics
`orders_fulfilled`	number	Number of orders whose fulfilment was applied.
`fulfillment_errors`	array	Fulfilment errors; a blocked fulfilment never half-applies.
`fulfillment_readiness`	object \| null	Present when fulfilment was refused; the choice block to resolve it (v1.5 only).
`fulfillment_move_results`	array	Outcome of a requested move (v1.5 only).

Notifications Object Fields

Field	Type	Description
`total_sent`	number	Total number of notifications sent successfully across all orders
`total_failed`	number	Total number of notifications that failed across all orders
`by_channel`	object	Object with per-channel stats (e.g., email, sms)

Channel Stats Object Fields

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

Fulfillment Error Object Fields

Field	Type	Description
`channel`	string	Fulfilment channel that failed.
`code`	string	Machine-readable error code.
`message`	string	Human-readable error message.

Fulfillment Readiness Object Fields

Field	Type	Description
`required`	boolean	Whether a location choice is needed.
`code`	string	Machine-readable refusal code.
`cause`	string	Underlying cause.
`message`	string	Message to show the operator.
`orders_to_fulfillment_orders_map`	object	Order id → fulfilment order ids map.
`moveable_fulfillment_order_ids`	array	Fulfilment orders that can be moved.
`location_choices`	array	Candidate destination locations.
`submit_with`	string	Request field to send the answer in — fulfillment_selections.

Examples

Basic Request (UUIDs)

cURL Request

curl -X POST "https://api.ultimate-custom-order-status.apps.msmtech.ca/api/v1/orders/status-bulk" \
  -H "X-API-Key: ucos_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
  -H "X-API-Version: 1.5" \
  -H "Content-Type: application/json" \
  -d '{"order_ids":["8c1d4e2f-0a53-49b7-b6e4-7f2d9c3a5e10"],"use_shopify_order_id":false,"status_id":"8c1d4e2f-0a53-49b7-b6e4-7f2d9c3a5e10","sub_status_option_id":"8c1d4e2f-0a53-49b7-b6e4-7f2d9c3a5e10","fulfillment_selections":{}}'

Using Shopify Order IDs

cURL Request

curl -X POST "https://api.ultimate-custom-order-status.apps.msmtech.ca/api/v1/orders/status-bulk" \
  -H "X-API-Key: ucos_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
  -H "X-API-Version: 1.5" \
  -H "Content-Type: application/json" \
  -d '{
    "order_ids": ["5460132438316", "5460132438317", "5460132438318"],
    "use_shopify_order_id": true,
    "status_id": "status-uuid",
    "sub_status_option_id": "sub-status-option-uuid"
  }'

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

{
  "success": false,
  "error": "Validation failed",
  "details": {
    "errors": [
      {
        "code": "invalid_type",
        "expected": "string",
        "received": "undefined",
        "path": [
          "status_id"
        ],
        "message": "Required"
      }
    ]
  }
}

401 Unauthorized

Missing or invalid API key

401 Unauthorized

{
  "success": false,
  "error": "Missing API key. Include it in the X-API-Key header"
}

403 Forbidden

API key lacks required permissions

403 Forbidden

{
  "success": false,
  "error": "Insufficient permissions. Required: canChangeOrderStatus"
}

404 Not Found

No valid orders found, or status/sub-status not found

404 Not Found

{
  "success": false,
  "error": "Order not found"
}

500 Internal Server Error

Server error occurred

500 Internal Server Error

{
  "success": false,
  "error": "Internal server error",
  "details": {
    "message": "An unexpected error occurred"
  }
}