POST
Bulk update status
Update the custom status for multiple orders in a single request.
POST
/v1/orders/status-bulkAuthentication
This endpoint requires a valid API key with
canChangeOrderStatus permission. The API key must be passed in the X-API-Key header.X-API-Key: ucos_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXRequest body
| Parameter | Description |
|---|---|
| order_idsstring[] · Required | Array of 1 to 100 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'). |
| use_shopify_order_idboolean · Optional, default 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. |
| status_idstring · Required | The UUID of the custom status |
| sub_status_option_idstring · Optional | The UUID of the sub-status option. Required if the status has sub-status options. |
| fulfillment_selectionsobject · Optional | Optional (v1.5+) answer to a fulfillment_readiness block: { [shopOrderId]: { [fulfillmentOrderId]: locationId } }. |
Response
Returns confirmation with count of updated orders:
{
"success": true,
"data": {
"message": "string",
"updated_count": 0,
"notifications": {
"total_sent": 0,
"total_failed": 0,
"by_channel": {
"email": {
"sent": 0,
"failed": 0
},
"sms": {
"sent": 0,
"failed": 0
},
"whatsapp": {
"sent": 0,
"failed": 0
}
}
},
"orders_fulfilled": 0,
"fulfillment_errors": [
{
"channel": "string",
"code": "string",
"message": "string"
}
]
}
}Response fields
Root response object
| Field | Description |
|---|---|
| successboolean | Always true on a successful response. |
| dataobject | The endpoint's payload. Its fields are listed in the tables below. |
| messagestring | Confirmation message |
| updated_countnumber | Number of orders successfully updated |
| notificationsobject | Notification delivery summary. |
| orders_fulfillednumber | Number of orders whose fulfilment was applied. |
| fulfillment_errorsarray | Fulfilment errors; a blocked fulfilment never half-applies. |
| fulfillment_readinessobject | null | Present when fulfilment was refused; the choice block to resolve it (v1.5+ only). |
| fulfillment_move_resultsarray | Outcome of a requested move (v1.5+ only). |
Notifications object fields
| Field | Description |
|---|---|
| total_sentnumber | Number of notifications sent. |
| total_failednumber | Number of notifications that failed. |
| by_channelobject | Per-channel counts: always email, sms and whatsapp, each { sent, failed } |
By channel object fields
| Field | Description |
|---|---|
| emailobject | Email notification counts |
| smsobject | SMS notification counts |
| whatsappobject | WhatsApp notification counts |
Channel stats object fields
| Field | Description |
|---|---|
| sentnumber | Number of notifications sent successfully for this channel |
| failednumber | Number of notifications that failed for this channel |
Fulfillment error object fields
| Field | Description |
|---|---|
| channelstring | Fulfilment channel that failed. |
| codestring | Machine-readable error code. |
| messagestring | Human-readable error message. |
Fulfillment readiness object fields
| Field | Description |
|---|---|
| requiredboolean | Whether a location choice is needed. |
| codestring | Machine-readable refusal code. |
| causestring | Underlying cause. |
| messagestring | Message to show the operator. |
| orders_to_fulfillment_orders_mapobject | Order id → fulfilment order ids map. |
| moveable_fulfillment_order_idsarray | Fulfilment orders that can be moved. |
| location_choicesarray | Candidate destination locations. |
| submit_withstring | Request field to send the answer in — fulfillment_selections. |
Examples
Basic request (UUIDs)
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 -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 minuteX-RateLimit-Remaining-Minute: Remaining requests in current minuteX-RateLimit-Reset-Minute: Unix timestamp when minute window resetsX-RateLimit-Limit-Day: Maximum requests per dayX-RateLimit-Remaining-Day: Remaining requests in current dayX-RateLimit-Reset-Day: Unix timestamp when day window resetsRetry-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
{
"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
{
"success": false,
"error": "Missing API key. Include it in the X-API-Key header"
}403 Forbidden
API key lacks required permissions
{
"success": false,
"error": "Insufficient permissions. Required: canChangeOrderStatus"
}404 Not Found
No valid orders found, or status/sub-status not found
{
"success": false,
"error": "Order not found"
}500 Internal Server Error
Server error occurred
{
"success": false,
"error": "Internal server error",
"details": {
"message": "An unexpected error occurred"
}
}