GET
Get status
Retrieve detailed information about a specific custom order status by its ID.
GET
/v1/statuses/:status_idAuthentication
This endpoint requires a valid API key with
canViewStatuses permission. The API key must be passed in the X-API-Key header.X-API-Key: ucos_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXPath parameters
| Parameter | Description |
|---|---|
| status_idstring | UUID of the status to retrieve |
Response
Returns detailed status information including notification settings, duration limits, and sub-status options:
{
"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 | Description |
|---|---|
| successboolean | Always true on a successful response. |
| dataobject | The endpoint's payload. Its fields are listed in the tables below. |
| statusobject | Status object containing all details |
Status object fields
| Field | Description |
|---|---|
| idstring | UUID of the status |
| namestring | Internal name of the status |
| public_namestring | null | Customer-facing name |
| use_public_nameboolean | Whether to use public name for customers |
| display_namestring | Computed display name (public_name if use_public_name is true, otherwise name) |
| colorstring | Hex color code for the status |
| ordernumber | Display order in workflow |
| is_independentboolean | Whether status can be used independently of workflow |
| is_addonboolean | Whether this status is an addon status |
| workflow_idstring | UUID of the workflow this status belongs to (v1.3+ only) |
| workflow_namestring | Name of the workflow this status belongs to (v1.3+ only) |
| notificationsobject | Object containing notification settings |
| shopify_order_effectstring | Effect on Shopify order (e.g., NONE, MARKS_ORDER_FULFILLED) |
| max_durationobject | Object containing duration limit settings |
| sub_status_groupobject | null | Object containing sub-status group details, or null |
Notifications object fields
| Field | Description |
|---|---|
| emailboolean | Whether email notifications are enabled |
| smsboolean | Whether SMS notifications are enabled |
| whatsappboolean | Whether WhatsApp notifications are enabled |
Max duration object fields
| Field | Description |
|---|---|
| enabledboolean | Whether max duration is enabled |
| secondsnumber | Maximum duration in seconds |
| skip_weekendsboolean | Whether to skip weekends in duration calculation |
| skip_holidaysboolean | Whether to skip holidays in duration calculation (v1.2+) |
| show_public_overdue_dateboolean | Whether to show overdue date to customers |
Sub-status group object fields
| Field | Description |
|---|---|
| idstring | UUID of the sub-status group |
| namestring | Name of the sub-status group |
| optionsarray | Array of sub-status options |
Sub-status option fields
| Field | Description |
|---|---|
| idstring | UUID of the sub-status option |
| namestring | Name of the sub-status option |
| ordernumber | Display order of the sub-status option |
Examples
Basic 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.4"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 minuteX-RateLimit-Remaining-Minute: Remaining requests in current minuteX-RateLimit-Reset-Minute: Unix timestamp when minute window resetsX-RateLimit-Limit-Day: Maximum requests per dayX-RateLimit-Remaining-Day: Remaining requests in current dayX-RateLimit-Reset-Day: Unix timestamp when day window resetsRetry-After: Seconds to wait before retrying (when rate limited)
Error responses
400 Bad Request
Invalid status ID format
{
"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
{
"success": false,
"error": "Missing API key. Include it in the X-API-Key header"
}403 Forbidden
API key lacks required permissions
{
"success": false,
"error": "Insufficient permissions. Required: canViewStatuses"
}404 Not Found
Status not found
{
"success": false,
"error": "Status not found"
}500 Internal Server Error
Server error occurred
{
"success": false,
"error": "Internal server error",
"details": {
"message": "An unexpected error occurred"
}
}