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

The legacy tour earnings surface — the PUT /api/hailing/bookings/:booking_id/earnings endpoint, the tour.earnings_updated webhook, and the earnings field on tour responses — is now deprecated and will be removed on 2026-11-06.

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.