Neu bei der Tour-Vergütung? Lies zuerst den Artikel Einführung in die Tour-Vergütung, um einen konzeptionellen Überblick über Grundverdienst, Boni und Trinkgelder zu erhalten.
Einführung
Das Vergütungsobjekt stellt für jede Tour eine strukturierte Aufschlüsselung von Grundverdienst, Boni und Trinkgeldern bereit. Dieser Artikel richtet sich an Entwickler, die eine Integration mit MotionTools aufbauen oder pflegen.
Er behandelt, wie du Vergütungswerte über die API liest und schreibst, wie du Änderungsbenachrichtigungen über den tour.compensation_updated-Webhook erhältst und wie du vom veralteten Legacy-Earnings-Attribut migrierst.
Die Vergütungs-Endpunkte
Das Vergütungsobjekt ist über einen dedizierten API-Endpunkt auf jeder Tour verfügbar.
Vergütung lesen:
GET /api/tours/:id/compensation
Grundverdienst festlegen:
PUT /api/tours/:id/compensation/base
Einen Bonus hinzufügen oder aktualisieren:
PUT /api/tours/:id/compensation/bonus/:key
Einen Bonus entfernen:
DELETE /api/tours/:id/compensation/bonus/:key
Bei jedem Schreibvorgang muss die Währung explizit übergeben werden. Die Währung stammt aus dem Servicegebiet der Tour und muss bei allen Komponenten derselben Tour übereinstimmen.
Die vollständige API-Dokumentation sowie Beispiele für Anfragen und Antworten findest du in der Tour Compensation API-Referenz.
Webhook: tour.compensation_updated
Der tour.compensation_updated-Webhook wird ausgelöst, sobald sich eine Komponente der Vergütung einer Tour ändert.
Um Rauschen durch schnell aufeinanderfolgende Aktualisierungen zu reduzieren, ist der Webhook entprellt (debounced): Er wird einmal ausgelöst, 120 Sekunden nach der letzten Änderung an einer bestimmten Tour. Wenn mehrere Komponenten in kurzer Folge aktualisiert werden, wird ein einziger Webhook mit dem endgültigen Zustand gesendet.
Abonniere diesen Webhook in deinen Integrationseinstellungen, um Vergütungsaktualisierungen automatisch zu erhalten, ohne die API abzufragen.
Der veraltete tour.earnings_updated-Webhook ist abgekündigt. Er wird während des Übergangszeitraums unverändert weiter ausgelöst, wird aber am 6. November 2026 entfernt. Migriere vor diesem Datum zu tour.compensation_updated.
Abkündigung des Legacy-Earnings-Attributs
Die folgenden Schnittstellen sind seit dem 7. Mai 2026 veraltet und werden am 6. November 2026 entfernt:
das Feld
earningsin Tour-Antwortender Endpunkt
PUT /api/hailing/bookings/:id/earningsder Webhook
tour.earnings_updated
Alle drei funktionieren während des Übergangszeitraums unverändert weiter. Zwischen den alten und neuen Schnittstellen werden keine Daten gespiegelt.
So migrierst du deine Integration:
Ersetze Schreibvorgänge an
PUT /api/hailing/bookings/:id/earningsdurchPUT /api/tours/:id/compensation/base. Wenn du derzeit Boni in einem einzigen Earnings-Wert bündelst, teile sie mithilfe vonPUT /api/tours/:id/compensation/bonus/:keyin einzelne Bonus-Schreibvorgänge auf.Ersetze Abonnements von
tour.earnings_updateddurchtour.compensation_updated.
Die vollständige API-Gegenüberstellung (vorher/nachher) findest du im Migrationsleitfaden.