POST

Clear Line Item Statuses

Remove the current status (and sub-status) from one or more line items. Maximum 100 line items per request.

Endpoint

HTTP Request

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

Request Body

Parameter	Type	Required	Default	Description
`line_item_ids`	string[]	Yes	-	Array of internal line item IDs (1–100)

Response

Returns confirmation with count of cleared line items:

200 OK - Success Response

{
  "success": true,
  "data": {
    "message": "2 line item(s) status cleared",
    "affected_count": 2,
    "requested_count": 2
  }
}

Response Fields

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 with status cleared
`requested_count`	number	Total number of line items requested

Notes

•Maximum 100 line items per request.
•Does not trigger notifications.
•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/clear-status" \
  -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"]
  }'

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 clear operation 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"
}

500 Internal Server Error

Server error occurred

500 Internal Server Error

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