GET

Get Status

Retrieve detailed information about a specific custom order status by its ID.

Endpoint

HTTP Request

GET /v1/statuses/:status_id

Authentication

This endpoint requires a valid API key with canViewStatuses permission. The API key must be passed in the X-API-Key header.

Required Header

X-API-Key: ucos_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Path Parameters

Parameter	Type	Description
`status_id`	string	UUID of the status to retrieve

Response

Returns detailed status information including notification settings, duration limits, and sub-status options:

200 OK - Success Response

{
  "success": true,
  "data": {
    "status": {
      "id": "string",
      "name": "string",
      "public_name": null,
      "use_public_name": true,
      "display_name": "string",
      "color": "string",
      "order": 0,
      "is_independent": true,
      "is_addon": true,
      "workflow_id": "string",
      "workflow_name": "string",
      "notifications": {
        "email": true,
        "sms": true,
        "whatsapp": true
      },
      "shopify_order_effect": "string",
      "max_duration": {
        "enabled": true,
        "seconds": 0,
        "skip_weekends": true,
        "skip_holidays": true,
        "show_public_overdue_date": true
      },
      "sub_status_group": null
    }
  }
}

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.
`status`	object	Status object containing all details

Status Object Fields

Field	Type	Description
`id`	string	UUID of the status
`name`	string	Internal name of the status
`public_name`	string \| null	Customer-facing name
`use_public_name`	boolean	Whether to use public name for customers
`display_name`	string	Computed display name (public_name if use_public_name is true, otherwise name)
`color`	string	Hex color code for the status
`order`	number	Display order in workflow
`is_independent`	boolean	Whether status can be used independently of workflow
`is_addon`	boolean	Whether this is an addon status (v1.1+ only)
`workflow_id`	string	UUID of the workflow this status belongs to (v1.3+ only)
`workflow_name`	string	Name of the workflow this status belongs to (v1.3+ only)
`notifications`	object	Object containing notification settings
`shopify_order_effect`	string	Effect on Shopify order (e.g., NONE, MARKS_ORDER_FULFILLED)
`max_duration`	object	Object containing duration limit settings
`sub_status_group`	object \| null	Object containing sub-status group details, or null

Notifications Object Fields

Field	Type	Description
`email`	boolean	Whether email notifications are enabled
`sms`	boolean	Whether SMS notifications are enabled
`whatsapp`	boolean	Whether WhatsApp notifications are enabled

Max Duration Object Fields

Field	Type	Description
`enabled`	boolean	Whether max duration is enabled
`seconds`	number	Maximum duration in seconds
`skip_weekends`	boolean	Whether to skip weekends in duration calculation
`skip_holidays`	boolean	Whether to skip holidays in duration calculation (v1.2+)
`show_public_overdue_date`	boolean	Whether to show overdue date to customers

Sub-Status Group Object Fields

Field	Type	Description
`id`	string	UUID of the sub-status group
`name`	string	Name of the sub-status group
`options`	array	Array of sub-status options

Sub-Status Option Fields

Field	Type	Description
`id`	string	UUID of the sub-status option
`name`	string	Name of the sub-status option
`order`	number	Display order of the sub-status option

Examples

Basic Request

cURL Request

curl -X GET "https://api.ultimate-custom-order-status.apps.msmtech.ca/api/v1/statuses/8c1d4e2f-0a53-49b7-b6e4-7f2d9c3a5e10" \
  -H "X-API-Key: ucos_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
  -H "X-API-Version: 1.5"

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

Invalid status ID format

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: canViewStatuses"
}

404 Not Found

Status not found

404 Not Found

{
  "success": false,
  "error": "Status 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"
  }
}