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

URL Parameters

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

Request Body

Parameter	Type	Required	Default	Description
`status_id`	string	Yes	-	Target status ID. An addon status is added to the line item when it is missing and removed when the line item already carries it; its sub-status is updated when one is given.
`sub_status_option_id`	string	No	-	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": "string",
    "line_item": {
      "id": "string",
      "shopify_line_item_id": "string",
      "name": "string",
      "quantity": 0,
      "title": null,
      "variant_title": null,
      "sku": null,
      "custom_status": {
        "id": "string",
        "name": "string",
        "color": "string"
      },
      "custom_sub_status": null
    },
    "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
`line_item`	object	Updated line item object
`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.

Line Item Object Fields

Field	Type	Description
`id`	string	Unique identifier for the line item
`shopify_line_item_id`	string	Shopify's global ID for the line item
`name`	string	Product name
`quantity`	number	Quantity ordered
`title`	string \| null	Product title
`variant_title`	string \| null	Variant title, or null
`sku`	string \| null	SKU, or null
`custom_status`	object	Current status object, or null.
`custom_sub_status`	object \| null	Current sub-status object, or null.

Status Object Fields

Field	Type	Description
`id`	string	Unique identifier for the custom status
`name`	string	Display name of the status (uses public name if configured)
`color`	string	Hex color code for the status

Sub-Status Object

Field	Type	Description
`id`	string	Unique identifier for the sub-status
`name`	string	Name of the sub-status

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.

Examples

Basic Request

cURL Request

curl -X POST "https://api.ultimate-custom-order-status.apps.msmtech.ca/api/v1/line-items/8c1d4e2f-0a53-49b7-b6e4-7f2d9c3a5e10/status" \
  -H "X-API-Key: ucos_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
  -H "X-API-Version: 1.4" \
  -H "Content-Type: application/json" \
  -d '{"line_item_id":"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 product chain enforcement violation

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

Line item, status, or sub-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"
  }
}