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

Request Body

ParameterTypeRequiredDefaultDescription
line_item_idsstring[]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": "string",
    "affected_count": 0,
    "requested_count": 0
  }
}

Response Fields

FieldTypeDescription
successbooleanWhether the operation succeeded
dataobjectResponse data object
messagestringConfirmation message
affected_countnumberNumber of line items with status cleared
requested_countnumberTotal 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: ucos_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
  -H "X-API-Version: 1.5" \
  -H "Content-Type: application/json" \
  -d '{"line_item_ids":["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 clear operation 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"
}

500 Internal Server Error

Server error occurred

500 Internal Server Error
{
  "success": false,
  "error": "Internal server error",
  "details": {
    "message": "An unexpected error occurred"
  }
}