POST

Change Line Item Status

Change the status of a single line item. Triggers notifications when configured on the target status.

Endpoint

HTTP Request

POST /v1/line-items/:lineItemId/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

URL Parameters

Parameter	Type	Required	Default	Description
`lineItemId`	string (UUID)	Yes	-	Internal line item ID (SyncedLineItem.id)

Request Body

Parameter	Type	Required	Default	Description
`status_id`	string (UUID)	Yes	-	Target status ID
`sub_status_option_id`	string (UUID)	Conditional	-	Required when the target status has a sub-status group with options

Response

Returns confirmation with updated line item status:

200 OK - Success Response

{
  "success": true,
  "data": {
    "message": "Line item status updated successfully",
    "line_item": {
      "id": "li-uuid-123",
      "status": {
        "id": "uuid-status-1",
        "name": "In Production",
        "color": "#FFA500"
      },
      "sub_status": {
        "id": "uuid-substatus-1",
        "name": "Cutting"
      }
    }
  }
}

Response Fields

Root Response Object

Field	Type	Description
`success`	boolean	Whether the operation succeeded
`data`	object	Response data object
`message`	string	Confirmation message
`line_item`	object	Updated line item object

line_item

Field	Type	Description
`id`	string	Internal line item ID
`status`	object	Current status object
`sub_status`	object \| null	Current sub-status object, or null

status / sub_status

Field	Type	Description
`id`	string	Status identifier
`name`	string	Status display name
`color`	string	Hex color code for the status

Examples

Basic Request

cURL Request

curl -X POST "https://api.ultimate-custom-order-status.apps.msmtech.ca/api/v1/line-items/li-uuid-123/status" \
  -H "X-API-Key: your_api_key_here" \
  -H "X-API-Version: 1.4" \
  -H "Content-Type: application/json" \
  -d '{
    "status_id": "uuid-status-1",
    "sub_status_option_id": "uuid-substatus-1"
  }'

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 product chain enforcement violation

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

Line item, status, or sub-status not found

404 Not Found

{
  "error": "Line item not found",
  "details": {
    "lineItemId": "li-uuid-123"
  }
}

500 Internal Server Error

Server error occurred

500 Internal Server Error

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