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

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": "3 line item(s) updated successfully",
    "affected_count": 3,
    "requested_count": 3
  }
}

200 OK - Partial Success Response

{
  "success": true,
  "data": {
    "message": "2 line item(s) updated successfully",
    "affected_count": 2,
    "requested_count": 3,
    "invalid_line_items": [
      {
        "lineItemId": "li-uuid-3",
        "reason": "Product chain enforcement: status must follow the configured order"
      }
    ]
  }
}

Response Fields

Root Response Object

Field	Type	Description
`success`	boolean	Whether the operation succeeded
`data`	object	Response data object
`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)

invalid_line_items[]

Field	Type	Description
`lineItemId`	string	ID of the line item that failed
`reason`	string	Reason for failure

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: your_api_key_here" \
  -H "X-API-Version: 1.4" \
  -H "Content-Type: application/json" \
  -d '{
    "line_item_ids": ["li-uuid-1", "li-uuid-2", "li-uuid-3"],
    "status_id": "uuid-status-2"
  }'

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": "Line item status changes are not enabled. Set status tracking level to \"line_item\" or \"combined\" in settings."
}

401 Unauthorized

Missing or invalid API key

401 Unauthorized

{
  "error": "Unauthorized"
}

403 Forbidden

API key lacks required permissions

403 Forbidden

{
  "error": "Insufficient permissions"
}

404 Not Found

Status not found

404 Not Found

{
  "error": "Status not found",
  "details": {
    "statusId": "uuid-status-2"
  }
}

500 Internal Server Error

Server error occurred

500 Internal Server Error

{
  "error": "Internal server error",
  "details": {
    "message": "Error description"
  }
}