API Changelog (v1.6)

New Features

Line Item Addon Statuses on Order Reads

Since November 2026 a line item can carry addon statuses of its own. Through 1.5 the order reads did not show them; from 1.6, every entry in line_items carries addon_statuses, in the same shape as the order's own addon_statuses.

Affected Endpoints:

• GET /v1/orders - Each order's line items carry addon_statuses
• GET /v1/orders/:order_id - The order's line items carry addon_statuses

Each entry of a line item's addon_statuses has these fields:

• id - The addon status's ID.
• name - Its internal name.
• display_name - The public name when the status uses one, otherwise name.
• color - Its color.
• sub_status - The selected sub-status, or null.
• assigned_at - When the addon was put on this line item.

• Entries are oldest first. A line item without addons, including every line item of a shop that does not track statuses per line item, has addon_statuses: [].
• The order's own addon_statuses is unchanged: it lists the order's addons and never repeats its line items'.
• Line item addons are set through the existing line item endpoints, at any version from 1.4.

{
  "id": "0d3c6f8e-5b1a-4e2c-9f7d-2a8b4c6e1f30",
  "shopify_line_item_id": "gid://shopify/LineItem/14587654321",
  "name": "Custom frame - 8x10",
  "quantity": 1,
  "custom_status": {
    "id": "8c1d4e2f-0a53-49b7-b6e4-7f2d9c3a5e10",
    "name": "In production",
    "color": "#2c6ecb"
  },
  "custom_sub_status": null,
  "addon_statuses": [
    {
      "id": "5e7a1c3b-9d24-4f60-8b1e-3c5a7d9f2b46",
      "name": "Rush",
      "display_name": "Rush order",
      "color": "#d72c0d",
      "sub_status": {
        "id": "a4b6c8d0-1e3f-4a5b-9c7d-2e4f6a8b0c12",
        "name": "Same day"
      },
      "assigned_at": "2026-11-12T15:04:05.000Z"
    }
  ]
}

Corrections That Apply to Every Version

These shipped with 1.6 but are not gated on the requested version. They fix behavior that did not match this documentation, or that let a request reach rows it should not.

• Deleted orders are never served or changed. An order removed from the app (a draft deleted in Shopify, drafts dropped when draft tracking is turned off, or a duplicate merged away) is now a 404 on every order endpoint. Before, GET /orders/:orderId still returned it, and a lookup by Shopify ID could land on a deleted duplicate instead of the live order.
• A Shopify ID finds draft orders on every write. With use_shopify_order_id, the status change, bulk status change, notify and bulk notify endpoints now find a draft order by its Shopify ID as well, as the reads have since 1.2.
• Bulk order requests take 1 to 100 IDs. POST /orders/status-bulk and POST /orders/notify-bulk refuse an empty list or more than 100 order_ids with a 400 validation error. An empty list used to be a 404, and there was no upper bound.
• use_shopify_order_id takes true, false, "true" or "false". The string "false" used to be read as true. Any other value is a validation error.
• Deleted and archived statuses are refused clearly. A deleted status_id is a 404 (Status not found), an archived one a 400 (Status is archived and cannot be applied). Both used to pass the API's check and come back as a 400 from the status engine that named the shop's internal setting ID.
• notifications.by_channel lists every channel. Status change responses (single and bulk) always carry email, sms and whatsapp, each { sent, failed }. It used to list only failing channels, with sent: 0 whatever was sent, or a single total entry when nothing failed. On the single status change, total_sent also read 0 whenever any channel failed.
• Repeated order_ids work on GET /orders. ?order_ids=a&order_ids=b returns both orders; only the first was used before. Comma-separated values work as before.
• Unsupported versions name the supported set on every endpoint. The error is "Unsupported API version. This endpoint supports: …" with details.supported_versions; ten endpoints used to return a bare "Unsupported API version: <value>".

Migration Guide

• No breaking changes — addon_statuses on line items is a new field, and 1.5 and earlier keep their line item shape.
• A headerless request is now served 1.6, so 1.6 is the default. Send X-API-Version: 1.5 to keep the previous default.
• Every endpoint accepts 1.6. Only the order list and order detail differ from 1.5; every other endpoint returns its 1.5 response.

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

Breaking Changes

None. The field is new, and 1.5 and earlier keep their line item shape. The corrections change responses only where they contradicted this documentation or exposed deleted rows.

New Features

Workflow Reassignment

A new endpoint moves an order to another workflow explicitly. Workflows are status-driven, so the move is completed by applying a starting status from the target workflow.

New Endpoint:

POST /v1/orders/:order_id/workflow - Move an order to another workflow

• starting_status_id is optional and defaults to the workflow's first status. It must be a main status of the target workflow — addon and independent statuses are rejected.
• The target workflow and starting status must belong to the shop and be active.
• The move carries the status change and the fulfilment it triggers; orders_fulfilled and fulfillment_errors report what happened.
• Requires the canOverrideProductChainEnforcement permission.

Example Request

{
  "workflow_id": "3f2a9c1e-7b64-4d21-9a3e-1c5d8f0b2a77",
  "starting_status_id": "8c1d4e2f-0a53-49b7-b6e4-7f2d9c3a5e10",
  "use_shopify_order_id": false
}

Example Response

{
  "success": true,
  "data": {
    "success": true,
    "order_id": "6b2da49e-84ef-439e-ad99-c3d7b2e6c64f",
    "shop_order_id": "gid://shopify/Order/5234567890",
    "workflow": {
      "id": "3f2a9c1e-7b64-4d21-9a3e-1c5d8f0b2a77",
      "name": "Pharmaceutical"
    },
    "status": {
      "id": "8c1d4e2f-0a53-49b7-b6e4-7f2d9c3a5e10",
      "name": "Approved"
    },
    "orders_fulfilled": 1,
    "fulfillment_errors": []
  }
}

Workflow Relationship Fields

GET /v1/workflows gains relationship fields that describe how the shop's workflows connect:

• relationship_type - sequential or isolated.
• relationship_configured - Whether the shop has an explicit relationship setting.
• previous_workflow_id / next_workflow_id - Derived chain neighbours; isolated workflows are skipped.
• workflow_transitions - Derived one-way handoffs: from_workflow_id, to_workflow_id, trigger: "on_final_status".
• enforce_workflow_order - At 1.5 it is derived from the relationship model; older versions keep the settings-backed value.

Requests with 1.3/1.4 keep the original response with no relationship fields.

{
  "id": "3f2a9c1e-7b64-4d21-9a3e-1c5d8f0b2a77",
  "name": "Pharmaceutical",
  "relationship_type": "sequential",
  "relationship_configured": true,
  "previous_workflow_id": null,
  "next_workflow_id": "a7732dfd-e636-4fe1-a66d-9fb43d2e92a8"
}

Fulfilment Selections on Status Changes

POST /v1/orders/:orderId/status and POST /v1/orders/status-bulk accept an optional fulfillment_selections map. It answers the one fulfilment cause a caller can resolve: an order whose fulfilment is assigned to a location that cannot fulfil it.

{
  "fulfillment_selections": {
    "gid://shopify/Order/5234567890": {
      "gid://shopify/FulfillmentOrder/987654321": "gid://shopify/Location/123456"
    }
  }
}

When fulfilment is refused, the response carries a fulfillment_readiness block so the caller can present the choice without discovery logic:

• required — whether a choice is needed.
• code, cause and message — why it was refused, and what to tell the user.
• orders_to_fulfillment_orders_map and moveable_fulfillment_order_ids — the orders and fulfilment orders involved.
• location_choices[] — fulfillment_order_id, movable, message and location per candidate destination.
• submit_with — the request field to send the answer in (fulfillment_selections).

{
  "fulfillment_readiness": {
    "required": true,
    "code": "FULFILLMENT_REQUIRES_LOCATION_SELECTION",
    "cause": "LOCATION_NOT_FULFILLABLE",
    "message": "The order's fulfilment is assigned to a location that cannot fulfil it.",
    "orders_to_fulfillment_orders_map": {
      "gid://shopify/Order/5234567890": ["gid://shopify/FulfillmentOrder/987654321"]
    },
    "moveable_fulfillment_order_ids": ["gid://shopify/FulfillmentOrder/987654321"],
    "location_choices": [
      {
        "fulfillment_order_id": "gid://shopify/FulfillmentOrder/987654321",
        "movable": true,
        "message": "Choose a location that can fulfil this order.",
        "location": {
          "id": "gid://shopify/Location/123456",
          "name": "Main warehouse"
        }
      }
    ],
    "submit_with": "fulfillment_selections"
  }
}

orders_fulfilled and fulfillment_errors report the outcome, and a refused move appears in fulfillment_move_results rather than being swallowed. A blocked fulfilment never half-applies: the status change stands and the fields say what happened.

Corrections That Apply to Every Version

• X-API-Version-Default reports the latest version on every endpoint, as X-API-Version-Current does (1.5 at this release), and a request without X-API-Version is served that version. The per-endpoint fallback remains only for a future endpoint whose first build is newer than the global current version.
• A 429 now carries details.retryAfter; it previously carried an undocumented message string.
• Validation errors on GET /orders now use the same details.errors array as every other endpoint.

Migration Guide

• No breaking changes — 1.5 became the default at this release, and the 1.4 payloads are unchanged.
• From this release a headerless request was served 1.5, so 1.5 was the default (it is now 1.6). Send X-API-Version: 1.4 to keep the unchanged 1.4 payload while migrating.
• A headerless request is served the default version on every endpoint (1.5 at this release); the workflow endpoint is no longer an exception.

{
  "workflow_id": "3f2a9c1e-7b64-4d21-9a3e-1c5d8f0b2a77",
  "starting_status_id": "8c1d4e2f-0a53-49b7-b6e4-7f2d9c3a5e10",
  "use_shopify_order_id": false
}

Breaking Changes

None — at this release a headerless request began to get 1.5 (it now gets 1.6), but requesting X-API-Version: 1.4 returns the same 1.4 responses.

New Features

Line Item Status Tracking

Added line item-level status tracking to the external API. Merchants who track statuses at the individual line item level (rather than or in addition to the order level) can now manage those statuses via three new endpoints.

New Endpoints:

• POST /v1/line-items/:lineItemId/status - Change a single line item's status
• POST /v1/line-items/status-bulk - Bulk change statuses for multiple line items (up to 100)
• POST /v1/line-items/clear-status - Clear statuses for one or more line items (up to 100)

Line Item Status Change Response

{
  "success": true,
  "data": {
    "message": "Line item status updated successfully",
    "line_item": {
      "id": "li-uuid-123",
      "status": {
        "id": "uuid-status-1",
        "name": "In Production",
        "color": "#FFA500"
      },
      "sub_status": {
        "id": "uuid-substatus-1",
        "name": "Cutting"
      }
    }
  }
}

Status Specificity Mode

The shop's statusSpecificity setting determines which endpoints are available. Modes are: order (only order-level endpoints), line_item (only line item endpoints), or combined (both work independently).

Key Behaviors

• Line item status changes, single and bulk, trigger notifications when configured on the target status. Clearing a status does not notify; since November 2026 a clear also removes the line items' addon statuses, and each removal notifies only when that addon is set to notify on removal.
• After any line item status change, the parent order's metafield is automatically rebuilt to reflect aggregated line item state.
• Product chain enforcement applies per line item independently — each line item must follow the configured status progression order.

Migration Guide

• No breaking changes — all v1.3 endpoints and responses are unchanged
• Line item endpoints are available in v1.4; send X-API-Version: 1.4 to use them.
• Check the shop's status specificity mode before calling line item endpoints
• Line item IDs use internal UUIDs (SyncedLineItem.id), not Shopify line item GIDs
• Fully backward compatible — existing integrations continue to work

Example Request

curl -X POST "https://api.ultimate-custom-order-status.apps.msmtech.ca/api/v1/line-items/li-uuid-123/status" \
  -H "X-API-Key: ucos_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
  -H "X-API-Version: 1.4" \
  -H "Content-Type: application/json" \
  -d '{
    "status_id": "uuid-status-1",
    "sub_status_option_id": "uuid-substatus-1"
  }'

Breaking Changes

None — all v1.0–v1.3 endpoints are unchanged.

New Features

Draft Order Filtering

Added ability to filter orders by type (regular orders, draft orders, or all). Draft orders can now be managed alongside regular orders in the API.

Affected Endpoints:

• GET /api/v1/orders - Orders list now supports order_type query parameter (REGULAR, DRAFT, ALL)
• GET /api/v1/orders/:order_id - Order lookup now automatically detects draft vs regular orders when using Shopify IDs

List Orders Changes

New query parameter order_type allows filtering by order type:

• REGULAR - REGULAR - Returns only regular orders (default in v1.0/v1.1)
• DRAFT - DRAFT - Returns only draft orders
• ALL - ALL - Returns both regular and draft orders (default in v1.2)

Examples

# Get all orders (both regular and draft) - v1.2 default
curl -X GET "https://api.ultimate-custom-order-status.apps.msmtech.ca/api/v1/orders?order_type=ALL" \
  -H "X-API-Key: ucos_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
  -H "X-API-Version: 1.2"

# Get only regular orders
curl -X GET "https://api.ultimate-custom-order-status.apps.msmtech.ca/api/v1/orders?order_type=REGULAR" \
  -H "X-API-Key: ucos_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
  -H "X-API-Version: 1.2"

# Get only draft orders
curl -X GET "https://api.ultimate-custom-order-status.apps.msmtech.ca/api/v1/orders?order_type=DRAFT" \
  -H "X-API-Key: ucos_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
  -H "X-API-Version: 1.2"

Get Order Changes

When using use_shopify_order_id=true, the API now automatically tries both regular and draft order ID formats, making integration easier.

# Look up a draft order by Shopify ID - v1.2 automatically tries both formats
curl -X GET "https://api.ultimate-custom-order-status.apps.msmtech.ca/api/v1/orders/1234567890?use_shopify_order_id=true" \
  -H "X-API-Key: ucos_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
  -H "X-API-Version: 1.2"

Holiday Skipping

Added skip_holidays flag to status max_duration configuration. When enabled, holidays will be excluded when calculating status duration deadlines, similar to the existing skip_weekends feature.

Affected Endpoints:

• GET /api/v1/statuses - Statuses list now includes skip_holidays in max_duration object
• GET /api/v1/statuses/:status_id - Status detail now includes skip_holidays in max_duration object

Response Changes

Status responses now include the skip_holidays field in the max_duration object:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Fulfillment",
  "color": "#2948ff",
  "is_independent": false,
  "is_addon": false,
  "max_duration": {
    "enabled": true,
    "seconds": 432000,
    "skip_weekends": true,
    "skip_holidays": true,
    "show_public_overdue_date": true
  }
}

Bulk Response Format Improvements

Updated bulk operation response format with clearer success/failure reporting and detailed error information for failed entries.

Affected Endpoints:

• POST /api/v1/orders/status-bulk - Bulk status update with improved response format
• POST /api/v1/orders/notify-bulk - Bulk notification with improved response format

Status Bulk Changes:

• updated_count - Total number of orders successfully updated
• failed - Number of orders that failed to update
• success - Boolean indicating if all updates succeeded
• failed_entries - Array of objects with order_id and error details for each failure

Notify Bulk Changes:

• total_orders - Total number of orders in the notification request
• failed - Number of orders that failed to notify
• success - Boolean indicating if all notifications succeeded
• failed_entries - Array of objects with order_id and error details for each failure

Bulk Response Examples

# Old format (before v1.2 update)
{
  "message": "Statuses updated successfully",
  "updated_count": 2,
  "results": [
    {
      "order_id": "uuid1",
      "status_id": "status-uuid",
      "status_name": "Processing"
    }
  ]
}

# New format (v1.2 update)
{
  "message": "Statuses updated successfully",
  "updated": 2,
  "failed": 1,
  "results": [
    {
      "order_id": "uuid1",
      "success": true,
      "status_id": "status-uuid",
      "status_name": "Processing"
    },
    {
      "order_id": "uuid2",
      "success": true,
      "status_id": "status-uuid",
      "status_name": "Processing"
    },
    {
      "order_id": "invalid-uuid",
      "success": false,
      "error": "Order not found"
    }
  ]
}

Migration Guide

• Add X-API-Version: 1.2 header to use this version explicitly
• The order_type parameter is optional - defaults to ALL in v1.2
• Shopify ID lookups now work for both regular and draft orders without changes
• The skip_holidays field is now available in status max_duration configurations
• Update bulk operation response handling to use the new success, failed, and failed_entries fields
• Check the success boolean for quick pass/fail determination instead of parsing individual results
• Fully backward compatible - existing integrations continue to work

Example Request

curl -X GET "https://api.ultimate-custom-order-status.apps.msmtech.ca/api/v1/orders?order_type=DRAFT" \
  -H "X-API-Key: ucos_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
  -H "X-API-Version: 1.2"

Breaking Changes

None - this is a backward-compatible release. The default behavior of order_type changed from REGULAR to ALL, but this is additive (returns more data, not less).

New Features

Addon Status Support

Added support for addon statuses across all order-related endpoints. Addon statuses can be assigned alongside primary statuses.

Affected Endpoints:

• GET /api/v1/orders - Orders list now includes addon_statuses array when X-API-Version: 1.1 header is present
• GET /api/v1/orders/:order_id - Order detail now includes addon_statuses array when X-API-Version: 1.1 header is present
• GET /api/v1/statuses - Statuses list now includes is_addon flag when X-API-Version: 1.1 header is present

Response Changes

Orders now include an addon_statuses field with optional sub-status support:

{
  "id": "uuid",
  "status": {
    "id": "status-uuid",
    "name": "Processing",
    "color": "#2948ff"
  },
  "addon_statuses": [
    {
      "id": "addon-uuid-1",
      "name": "Quality Check",
      "color": "#10b981",
      "sub_status": {
        "id": "addon-sub-uuid",
        "name": "Passed"
      }
    },
    {
      "id": "addon-uuid-2",
      "name": "Packaging",
      "color": "#f59e0b",
      "sub_status": null
    }
  ]
}

Statuses now include classification flags:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Processing",
  "is_independent": false,
  "is_addon": false
}

Migration Guide

• No code changes required - fully backward compatible
• Requests without a version header use the default version (1.6)
• To use an older version, explicitly specify it with the X-API-Version header
• No changes required to authentication or rate limiting

Example Request:

curl -X GET 'https://api.ultimate-custom-order-status.apps.msmtech.ca/api/v1/orders' \
  -H "X-API-Key: ucos_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
  -H "X-API-Version: 1.1"

Breaking Changes

None - this is a backward-compatible release.