The compensation object gives every tour a structured breakdown of base earnings, bonuses, and tips. This article is aimed at developers building or maintaining an integration with MotionTools.

It covers how to read and write compensation values through the API, how to receive change notifications through the tour.compensation_updated webhook, and how to migrate away from the deprecated legacy earnings attribute.

The compensation object is available via a dedicated API endpoint on every tour.

Read compensation:

GET /api/tours/:id/compensation

Set base earnings:

PUT /api/tours/:id/compensation/base

Add or update a bonus:

PUT /api/tours/:id/compensation/bonus/:key

Remove a bonus:

DELETE /api/tours/:id/compensation/bonus/:key

Each write requires the currency to be passed explicitly. The currency is sourced from the tour's service area and must match across all components on the same tour.

For full API documentation and request/response examples, see the Tour Compensation API reference.

The tour.compensation_updated webhook fires whenever any component of a tour's compensation changes.

To reduce noise from rapid successive updates, the webhook is debounced: it fires once, 120 seconds after the last change on a given tour. If multiple components are updated in quick succession, a single webhook is sent with the final state.

Subscribe to this webhook in your integration settings to receive compensation updates automatically without polling the API.

The following are deprecated as of May 7, 2026 and will be removed on November 6, 2026:

All three continue to work unchanged during the transition window. No data is mirrored between the old and new surfaces.

To migrate your integration:

See the migration guide for the full API before/after comparison.