The replacement is the new failure_options object on the same stop payloads (for example on Show Booking): failure_options.outcomes.skip_recovery.allowed carries the same signal, and the object additionally indicates the availability of every other recovery outcome together with a localized reason when one is not available.

Until removal, completion_requirements.fail continues to work unchanged. Migrate by reading failure_options.outcomes.skip_recovery.allowed instead — note that failure_options renders on tour stops in failable states (approaching or arrived), so treat an absent object the same as fail: false.

The replacement is the new top-level places flag, which reflects access for every role that can use places — not just administrators. The detailed (per-action) shape is identical, so existing per-action checks map over directly.

Until removal, admin.places continues to work unchanged. Migrate by reading permissions.places instead of permissions.admin.places.

This wraps up a phased retirement that already removed Fleet management from our web dashboard and mobile apps earlier this year. The capability covered vehicle inventory, operational status tracking, damage reports, and lock and unlock interactions through integrations with vehicle telematics providers such as Invers, NIU, MapTex and others. After removal, calls to the corresponding API endpoints respond with 404 Not Found.

Going forward, the MotionTools platform focuses on the booking, tour and package delivery flows that power day-to-day operations for our customers.

The replacement is the new Tour Compensation API: a single source of truth for what a driver is paid out for a tour, exposed as a structured, auto-totalled view across base earnings, bonuses, and tips, with a dedicated webhook for change notifications. The new surface covers everything the legacy earnings attribute did and adds the structure 3PL operations need — kept efficient on the wire by the new webhook’s quiet-window debounce, which collapses bursts of edits into a single delivery.

Until removal, the legacy endpoint, webhook, and field continue to fire unchanged. Migrate at your own pace within the deprecation window.

What’s deprecated:

• ⚠️ Update driver earnings — replaced by Set tour base earnings / Set tour bonus / Delete tour base earnings / Delete tour bonus.
• The ⚠️ tour.earnings_updated webhook — replaced by tour.compensation_updated, which carries the full structured breakdown and is debounced over a 120s quiet window so bursts of edits collapse into a single delivery reflecting the final state.
• The earnings field on tour / booking responses — read the structured breakdown via Get tour compensation instead. The compensation breakdown is intentionally not embedded in the list/detail tour responses to keep those payloads focused — fetch it on-demand from the dedicated endpoint.

What stays unchanged for the deprecation window:

• The legacy endpoint, webhook, and field continue to behave exactly as before — same payload shape, same firing conditions, same persistence. No data migration runs and no values are mirrored across the two surfaces. Pick whichever surface fits your integration today and switch over before the deadline.

Migration:

Replace single-value writes against the legacy endpoint with structured component writes against the compensation API. Each component is addressed and updated independently:

// Before — PUT /api/hailing/bookings/<tour_id>/earnings
{
  "earnings": {
    "amount": 4200,
    "currency": "EUR"
  }
}

// After — PUT /api/tours/<tour_id>/compensation/base
{
  "amount": 4000,
  "currency": "EUR",
  "label": "Base rate"
}

// After (incentive) — PUT /api/tours/<tour_id>/compensation/bonus/peak_hours
{
  "amount": 200,
  "currency": "EUR",
  "label": "Peak-hour multiplier"
}

The total_amount is recomputed automatically as components change — no need to maintain a running total client-side.

Webhook subscribers swap from a single amount/currency payload to the full structured breakdown:

// Before — tour.earnings_updated
{
  "data": {
    "tour_id": "…",
    "service_area_id": "…",
    "amount": 4200,
    "currency": "EUR"
  }
}

// After — tour.compensation_updated
{
  "data": {
    "tour_id": "…",
    "service_area_id": "…",
    "currency": "EUR",
    "total_amount": 4200,
    "breakdown": {
      "base_earnings": { "amount": 4000 },
      "bonuses": [ { "key": "peak_hours", "amount": 200 } ],
      "tips":    { "amount": 0 }
    },
    "compensation_updated_at": "2026-05-07T10:23:45Z"
  }
}

The new webhook payload excludes labels and metadata so subscribers can act on amounts without round-tripping to our backend.

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
      }
    }
  ]
}

As part of the ongoing transition from booking to tour terminology, this field has been replaced by active_tour_id, which returns the ID of the driver’s currently active tour as a single value (or null when idle).

Changes:

• A new active_tour_id field is now available on the User resource when the resource is a driver
• The existing active_hailing_booking_ids array field continues to work but is deprecated
• active_tour_id returns a single UUID or null, replacing the array which only ever contained zero or one element

Migration: Replace usage of active_hailing_booking_ids with active_tour_id:

// Before (active_hailing_booking_ids — array, always 0 or 1 elements)
{ "active_hailing_booking_ids": ["550e8400-e29b-41d4-a716-446655440000"] }

// After (active_tour_id — single value or null)
{ "active_tour_id": "550e8400-e29b-41d4-a716-446655440000" }

As part of the ongoing split between bookings and tours as distinct concepts, this filter has been replaced by on_active_tour, which provides the same functionality with naming that better reflects the underlying domain model.

Changes:

• A new on_active_tour boolean filter is now available on the List Users endpoint
• The existing on_active_hailing_booking filter continues to work but is deprecated
• Both filters behave identically — filtering drivers by whether they currently have an active tour

Migration: Replace on_active_hailing_booking with on_active_tour in your API calls:

# Before
GET /api/users?filters[on_active_hailing_booking]=true

# After
GET /api/users?filters[on_active_tour]=true

This field was previously used to configure the frequency at which the next driver would be looked up for marking as preferred during gradual rollout. With the removal of the per_tour gradual rollout mode, this configuration is no longer used - the frequency is now controlled by an environment variable.

Changes:

• The field now always returns null regardless of the stored value
• Providing this field in create/update requests is still accepted but has no effect

Migration: No action is required. The field will continue to be returned in API responses (with the value null) until it is removed.

Instead, you should switch to the dedicated endpoint for tours or bookings.

This property has become obsolete in early 2024 with the introduction of our flexible package tours product, allowing any tour to have arbitrary stops as desired, and hasn’t been used for some time. We are now fully removing it from our API responses.

This change became necessary since depending on the configuration a forced delivery now requires additional data for proofs to be provided, which wasn’t possible with the generic transition.

We normally indicate granular permissions for specific interactions in the permissions object on responses. While the permission to remove a certain package was already indicated, it doesn’t only apply to dropoff tours, and wasn’t in the right namespace to ease API consumption, therefore we are replacing it with this new standardized property.

In early 2024 we have changed the behaviour of our platform to make the distinction between bookings and tours clearer - bookings represent customer demand, while tours are responsible for the (optionally optimized) execution of such bookings by drivers. As a consequence of this, since then drivers cannot directly accept regular bookings anymore, with wide-ranging consequences to the events and flow a booking and a tour can have.

So far, many of our webhook events were shared between bookings and tours however, in the hailing_booking.* namespace. We are replacing these with dedicated events that more closely reflect the actual possibilities and lifecycles of their corresponding data models.

Please update all your webhook receiving endpoints and configurations accordingly to utilize the new events instead:

Booking events

Tour events

Historically, to update a stop’s information you had to also supply the corresponding booking ID, for example at /api/hailing/bookings/:booking_id/stops/:stop_id/metadata. Due to the ongoing split between bookings and tours you would also in the future have needed to call different endpoints depending on whether it’s a tour or booking stop.

To simplify this, we have removed the booking and tour namespacing from endpoints related to editing stop data, linked below. All of the endpoints now follow the route schema /api/stops/:id/[endpoint].

The old routes remain supported for the time being but will be removed in the future.