Enhanced Driver Rates Visibility in Trips Endpoint

What’s New?

We’ve introduced the new RatesV2 structure for drivers and owner-operators in the Trips Public API. This structure provides a detailed breakdown of how each driver’s pay was calculated based on applied rate rules and policies.

What Changed?

Previously, driver payment data under Driver1, Driver2, and OwnerOperator included only simple Rates[] arrays with limited fields (e.g., rate, rateType, source).

Now, the response includes a RatesV2 array, containing all applied rules, their types, amounts, and computed line items.

Each RatesV2[] entry contains a unique PolicyId, PolicyName, and one or more detailed rate components such as:

 "RatesV2": [
                    {
                        "PolicyId": "c00fda1001ec4a11100affdb0234de00",
                        "PolicyName": "Custom Rate",
                        "PerTripRate": {
                            "Rate": 250.0,
                            "RateId": "1",
                            "RateName": "Per Trip",
                            "LineItems": [
                                {
                                    "Description": "1 trip @ $250",
                                    "Amount": {
                                        "Amount": 250.0,
                                        "Currency": 840
                                    }
                                }
                            ]
                        }
                    },
                    {
                        "PolicyId": "a00fba1001ec4a11100aaddff0234de00",
                        "PolicyName": "Public API",
                        "TripValuePercentageRate": {
                            "Percentage": 25.0,
                            "RateId": "2",
                            "RateName": "% of Trip Value",
                            "LineItems": [
                                {
                                    "Description": "25% of $3,800",
                                    "Amount": {
                                        "Amount": 950.0,
                                        "Currency": 840
                                    }
                                }
                            ]
                        }
                    }
                ]

Endpoints Affected

• GET /api/p/{version}/trips
• POST /api/p/{version}/trips/search

Why?

This change exposes driver rate calculation logic used in the Alvys UI, allowing integrators to:

• Understand which rules and policies were applied to determine each payout.
• Align backend integrations with the new internal pay policy engine for consistent reporting and reconciliation.

⚠️

Important Note

This update is partially backward compatible:

• The legacy Rates[] field still exists and is returned in API responses.
• For new trips created after migration to Driver Settlement (DS), the Rates[] array will always be empty.
• For trips created before migration, Rates[] may still contain historical data, but it can be out of sync with RatesV2[] if new rates were added after migration.
• All current and future rate data is now provided exclusively in the RatesV2[] array.
• Integrations should update their logic to use RatesV2[] as the source of truth for driver and owner-operator pay details.
• The legacy Rates[] field will remain available temporarily for backward compatibility but will be fully deprecated later.

Each rate type (e.g., TripValuePercentageRate, PerTripRate, MinimumPayRate, etc.) is now provided as a structured object with additional LineItems[] for detailed breakdowns.