API Changelog

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 with notification support
• 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

• Single line item status changes trigger notifications when configured on the target status. Bulk and clear endpoints do not trigger notifications.
• 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 by default in v1.4
• 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: your_api_key_here" \
  -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: your_api_key_here" \
  -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: your_api_key_here" \
  -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: your_api_key_here" \
  -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: your_api_key_here" \
  -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: your_api_key_here" \
  -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 automatically use the latest version
• 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 'Authorization: Bearer ucos_live_your_api_key' \
  -H 'X-API-Version: 1.1'

Breaking Changes

None - this is a backward-compatible release.