POST

Bulk Change Line Item Statuses

Change the status of multiple line items to the same target status in a single batch. Maximum 100 line items per request.

Endpoint

HTTP Request

POST /v1/line-items/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
`line_item_ids`	string[]	Yes	-	Array of internal line item IDs (1–100)
`status_id`	string (UUID)	Yes	-	Target status ID
`sub_status_option_id`	string (UUID)	Conditional	-	Required when the target status has sub-status options

Response

Returns confirmation with count of updated line items:

200 OK - Success Response

{
  "success": true,
  "data": {
    "message": "string",
    "affected_count": 0,
    "requested_count": 0,
    "notifications": {
      "total_sent": 0,
      "total_failed": 0,
      "errors": [
        {
          "channel": "string",
          "code": "string",
          "message": "string"
        }
      ]
    },
    "metafield_errors": []
  }
}

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
`affected_count`	number	Number of line items successfully updated
`requested_count`	number	Total number of line items requested
`invalid_line_items`	array	Array of line items that failed validation (only present on partial success)
`notifications`	object	Notification delivery summary.
`metafield_errors`	array	Declared as { orderId, message }[]; the metafield rebuild never rejects, so this array is always empty in practice.

Invalid Line Item Object Fields

Field	Type	Description
`lineItemId`	string	ID of the line item that failed
`error`	string	Error message for this line item.
`code`	string	Machine-readable error code, when available.

Notifications Object Fields

Field	Type	Description
`total_sent`	number	Number of notifications sent.
`total_failed`	number	Number of notifications that failed.
`errors`	array	Per-channel notification errors.

Notification Error Object Fields

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

Metafield Error Object Fields

Field	Type	Description
`orderId`	string	Order id whose metafield failed.
`message`	string	Human-readable error message.

Notes

•Maximum 100 line items per request.
•Does not trigger notifications (unlike single line item change).
•Metafields are rebuilt for all affected parent orders.

Examples

Basic Request

cURL Request

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

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

Line item status not enabled, validation failed, or all line items failed

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

Status not found

404 Not Found

{
  "success": false,
  "error": "Line item 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"
  }
}