This is a deprecation notice - we are changing or removing support for the features described on this page on or after September 16, 2026. Please ensure to adjust your integrations accordingly before that date.

The public GET /api/hailing/failure_reasons endpoint is now deprecated and will be removed on 2026-09-16. Package failure reasons are now served through the unified reasons API at GET /api/reasons/package_failure, in the same shape used by the other reason categories such as stop failure reasons.

The unified API gives operators and integrators a single, consistent format for all configurable reasons across the platform, with localised labels and category-specific metadata kept neatly in a properties bag — so adding new categories in the future won’t require new response shapes on the client side.

Changes:

• A new GET /api/reasons/package_failure endpoint is available and returns the same tenant-configurable reasons the legacy endpoint did, in the unified reasons shape
• The legacy GET /api/hailing/failure_reasons endpoint continues to work but is deprecated
• The id → key rename and moving note_required / triggers_reattempt under a properties sub-object aligns this category with the rest of the unified reasons API

Field mapping:

Migration:

Replace calls to the legacy endpoint with the new one and adapt to the unified shape:

// Before — GET /api/hailing/failure_reasons
{
  "failure_reasons": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "title": "Recipient not at home",
      "applies_to": ["dropoff"],
      "note_required": false,
      "triggers_reattempt": true
    }
  ]
}

// After — GET /api/reasons/package_failure
{
  "reasons": [
    {
      "category": "package_failure",
      "key": "550e8400-e29b-41d4-a716-446655440000",
      "label": "Recipient not at home",
      "applies_to": {
        "stop_types": [],
        "package_interactions": ["dropoff"]
      },
      "properties": {
        "note_required": false,
        "triggers_reattempt": true
      }
    }
  ]
}