Fare calculation adapters

Roles: Super Admin

In the Fare calculation adapters section in the management settings of a product, you can configure the product’s pricing.

Fare calculation is handled with adapters. First, the selected booking price adapter calculates the base price of a ride. Personal discounts are then applied, and the booking price is presented to the passenger before they book the ride. The final price adapter, which can, for example, apply a discount for each pooling event, is applied after drop-off.

The price shown to the user during booking is price from the fare adapter minus personal discounts.

There are a few standard adapters, but because ride pricing is often highly specific, many providers use a custom adapter in ioki Platform.

For example, you can set fixed prices per ride, calculate fares based on direct routing distance, or use pricing zones. You can also take into account whether a passenger has a public transport ticket.

There are four types of fare calculation adapters in total.

Fare calculation adapters

Booking price calculation

This adapter calculates the basic fare for a ride. While default options are available, ioki Platform also includes various custom adapters for different providers and products. The following are the default options available.

The booking price adapter set here is used only when the product does not use self-service faring. When the product feature fare adapter configurations is active, the booking price adapter comes from the active fare adapter configuration instead—one of the Configurable with … adapters—and the choice made here is ignored for the booking price.

External pricing (apps show custom message)

This adapter is used when pricing is managed externally, meaning no fare or pricing is provided by ioki Platform. ioki Passenger App should display appropriate custom messages, such as “The PT tariff applies.”

Fixed price per passenger

The adapter returns fixed prices for adults, children, and infants. These prices are specified directly in the product settings.

Fixed price per passenger with comfort surcharge, public transport ticket and blue badge discounts

This option works similarly to the Fixed price per passenger adapter but allows for an additional comfort surcharge that can be configured separately for adults, children, and infants in the product settings. Passengers with a public transport ticket or a blue badge/disability ID card are only charged the comfort surcharge.

Adults pay the fixed price for adult/regular passenger + fixed adult comfort surcharge
Children pay fixed price for child + fixed child comfort surcharge
Infants pay fixed price for infant + fixed infant comfort surcharge
Public transport ticket (passenger option slug public_transport_ticket) gives 100% discount on the base price.
Blue Badge (passenger option slug blue_badge) gives 100% discount on the base price.
Disability ID card (passenger option slug disabled_pass) gives 100% discount on the base price.

Free of charge

This option indicates that the ride incurs no cost.

Ticket price per passenger with comfort surcharge

If ticketing is activated, this adapter uses the ticket price as the base fare and adds a comfort surcharge, which can also be specified for adults, children, and infants.

Custom booking price adapters

Because ride pricing is often highly specific, many providers use a custom booking price adapter instead of one of the default options above. Custom adapters are product-specific pricing rules used when the default options aren’t enough. The exact logic depends on the adapter; the patterns below are available in current custom logic.

Examples include pricing based on:

routed distance, including thresholds, bands, and per-kilometer steps
pickup time, for example different daytime and overnight prices
number and type of passengers, including ride-level pricing where children count differently from adults
price levels or rule codes from relation matrices, where the matrix value can be the fare itself or decide which pricing rule applies
passenger options or ticketing, for example reducing the fare to zero or to a lower target price
public transport alternatives, where the DRT fare is compared with a relevant public transport alternative and can switch to a different fare if that alternative meets defined thresholds
minimum prices, capped fare levels, surcharges, and additional-passenger or companion discounts

Distance-based pricing

Distance-based pricing is not just one model. Verified examples in current custom logic include:

distance bands or threshold-based surcharges
per-kilometer pricing, sometimes only after an included base distance
minimum fares per passenger or per ride
prices that also change by passenger count or time window

ioki Platform passes distances to fare adapters in meters. Custom logic can use the routed distance from the product’s routing setup and apply bands, thresholds, surcharges, or per-kilometer pricing on top.

Zone codes and relation matrices

A current fare matrix can be station-based, station-category-based, or zone-based. ioki Platform looks up the origin and destination pair and passes the stored cell value to the fare adapter as the zone code.

That value can be used in different ways:

as the final fare
as a price level
as a rule code that tells the adapter which pricing logic to apply

For zone-based matrices, ioki Platform uses the calculated pickup and drop-off points for the lookup. This matters because the reference stations may be in different zones from the calculated ride points. A zone-based fare matrix also does not have to cover every zone in the product.

In current custom logic, matrix values are used both for direct adult and child fare tables and as inputs that trigger different pricing formulas or discounts.

Custom booking price adapter example
A fictitious custom booking price adapter could use this 2x2 station-category-based fare matrix:
From \ To airport city_center
airport B2 A1
city_center A1 B2
In this setup, A1 means 6.00 € base fare + 2.00 € per routed kilometer, while B2 means 4.00 € flat fare.
If Fynn books a ride from the airport to the city center and the routed distance is 5 km, ioki Platform returns A1 from the matrix. The custom adapter then calculates 6.00 € + (5 × 2.00 €) = 16.00 €.
If Fynn instead books a ride within the city center, ioki Platform returns B2, so the final fare is 4.00 €.
This means the fare matrix decides which pricing rule applies, while the adapter calculates the final fare.

From \ To	airport	city_center
airport	`B2`	`A1`
city_center	`A1`	`B2`

Cancellation fee calculation

If a passenger cancels a ride, a cancellation fee can be applied.

The following section details the default options for the cancellation fee calculation. If more complex logic is required, a custom adapter could be developed.

The cancellation fee settings that apply to a ride are the ones that were in effect when the ride was booked, not the ones in effect when the ride is canceled.

When a passenger books a ride, the product’s cancellation fee settings are saved with that ride. If the product’s cancellation fee settings are later changed, the change applies only to rides booked after the change. Rides that were already booked keep the settings they were booked with.

For example, if a product has no cancellation fee and a passenger books a ride, that ride can still be canceled without a fee even if a cancellation fee is added to the product afterward. A passenger is always charged based on the conditions that were shown to them when they booked.

No cancellation fee

When this is selected, there is no fee for cancellation.

Cancellation fee with margins around booking and pickup

If this adapter is selected, you can enable and configure the following fields. This adapter can consider three different types of cancellations in the cancellation fee calculation: quick cancellations, early cancellations, and late cancellations.

Charge full booking price on cancellation. If this option is enabled, the full booking price is charged on cancellation.
Limit cancellation fee on booking price (default = false). If enabled, the cancellation fee cannot exceed the booking price. If disabled, the cancellation fee is uncapped.
Use discounted booking price for cancellation fee calculation (default = false). If enabled, the discounted booking price (considering personal discounts) is used instead of the non-discounted booking price when applying a fee limit.
Consume personal discount for free cancellation fee (default = false). If enabled, a personal discount is consumed when the fee is greater than 0, and the fee is then set to 0.
Consume personal discount on cancellation (default = false). If enabled, a personal discount is consumed if the fee calculation was affected by using the discounted booking price for the calculation.
Cancellation fee. This defines the fixed cancellation fee.
Use a special cancellation fee when the user cancels quickly after booking. Enable this option to consider quick cancellations in the cancellation fee calculation. This fee is applied if a user cancels quickly after booking.
- Time after booking during which the quick cancellation fee is charged. Select the threshold from zero to 60 minutes in one-minute increments. If the cancellation happens before a booking was created (in the ride state passenger accepted), it’s always handled as free and the adapter is never called. Otherwise, if the cancellation is within this threshold, the quick cancellation fee is charged.
- Quick cancellation fee. Specify the monetary value of the quick cancellation fee.
Use a special cancellation fee when the user cancels long before the pickup. Enable this option to consider early cancellations in the cancellation fee calculation. This fee is applied if a user cancels a “long” time before the pickup.
- Time before pickup until when the early cancellation fee is charged. Select the threshold from zero to ten hours in five-minute increments. If the time between cancellation and pickup time is greater than this threshold, the early cancellation fee is charged.
- Early cancellation fee. Specify the monetary value of the early cancellation fee.
Use a special cancellation fee when the user cancels shortly before the pickup. Enable this option to consider late cancellations in the cancellation fee calculation. This fee is applied if a user cancels shortly before the pickup. The threshold is configurable.
- Charge full booking price on late cancellation. If this option is enabled, the full booking price is charged on late cancellation.
- Time before pickup after which the late cancellation fee is charged. Select the threshold from zero to ten hours in five-minute increments. If the time between cancellation and pickup time is smaller than this threshold, the late cancellation fee is charged.
- Late cancellation fee. Specify the monetary value of the late cancellation fee.

When a ride is canceled, this adapter determines the cancellation fee in the following order.

It first checks if the cancellation is a quick cancellation (if enabled).
It then checks if the cancellation is an early cancellation (if enabled).
Lastly, it checks if the cancellation is a late cancellation (if enabled).
If all previous checks fail, either the full booking price is charged for the cancellation (if enabled) or the standard cancellation fee is applied.

These settings enable you to configure a number of different cancellation fee setups. For example, the following can be configured.

Always charge a cancellation fee, but allow free cancellation until X minutes after booking.
Allow free cancellation until 2 hours before pickup.
Charge a fee of 1€ if passenger cancels at least an hour before pickup, charge 2€ afterwards.

If the estimated or recorded pickup or dropoff falls outside the initially negotiated time window, the ride can be canceled without a cancellation fee. See Free cancellations.

Cancellation fee calculation
A product has Cancellation fee calculation = Cancellation fee with margins around booking and pickup with the following settings.
Cancellation fee = 2.50 €
Use a special cancellation fee when the user cancels quickly after booking is enabled.
Time after booking during which the quick cancellation fee is charged = 2 minutes
Quick cancellation fee = 1.00 €
Use a special cancellation fee when the user cancels long before the pickup is enabled.
Time before pickup until when the early cancellation fee is charged = 00:30
Early cancellation fee = 2.00 €
Use a special cancellation fee when the user cancels shortly before the pickup is enabled.
Time before pickup after which the late cancellation fee is charged = 00:15
Late cancellation fee = 3.00 €
Joshua books a ride with a pickup five hours from now. He then cancels the ride 17 minutes before pickup. He is charged the standard cancellation fee of 2.50 € because this time falls between the thresholds for early cancellation and late cancellation. The quick cancellation fee does not apply.
Sergio books a ride with a pickup two hours from now. He then cancels the ride 47 minutes before pickup. He is charged the early cancellation fee of 2.00 € because this is more than 30 minutes before pickup. The quick cancellation fee does not apply.
Alexia books a ride with a pickup of 10 minutes from now. She then cancels the ride one minute after booking. She is charged the quick cancellation fee of 1.00 € as this takes precedence over the late cancellation fee of 3.00 €.
The following timeline illustrates the configuration. A booking is made, and pickup is scheduled for one hour later.
gantt
dateFormat  HH:mm:ss
axisFormat  %H:%M

section Fee
⚡ Quick (€1.00) :a1, 00:00:00, 00:02:00
🌅 Early (€2.00) :a2, 00:02:00, 00:30:00
💶 Standard (€2.50) :a3, 00:30:00, 00:45:00
🌇 Late (€3.00) :a4, 00:45:00, 01:00:00

section Ride
Booking :e1, 00:00:00, 00:00:01
Pickup :e3, 01:00:00, 01:00:01

Relative cancellation fee with margins around booking and pickup

If this adapter is selected, you can enable and configure the following fields. This adapter can consider two different types of cancellations in the cancellation fee calculation: quick cancellations and early cancellations.

Use discounted booking price for cancellation fee calculation (default = false). If enabled, the discounted booking price (considering personal discounts) is used instead of the non-discounted booking price when calculating a relative fee.
Consume personal discount for free cancellation fee (default = false). If enabled, a personal discount is consumed when the fee is greater than 0, and the fee is then set to 0.
Consume personal discount on cancellation (default = false). If enabled, a personal discount is consumed if the fee calculation was affected by using the discounted booking price for the calculation.
Cancellation fee relative to booking price. This represents the standard cancellation fee and is defined as a percentage of the booking price.
Minimum cancellation fee. This sets the lowest possible cancellation fee that will be charged, even if the calculated fee is less than this value.
Use a special cancellation fee when the user cancels quickly after booking. Enable this option to consider quick cancellations in the cancellation fee calculation. This fee is applied if a user cancels quickly after booking.
- Time after booking during which the quick cancellation fee is charged. Select the threshold from zero to 60 minutes in one-minute increments. If the cancellation happens before a booking was created (in the ride state passenger accepted), it’s always handled as free and the adapter is never called. Otherwise, if the cancellation is within this threshold, the quick cancellation fee is charged.
- Quick cancellation relative to booking price. Specify the percentage of the booking price.
Use a special cancellation fee when the user cancels long before the pickup. Enable this option to consider early cancellations in the cancellation fee calculation. This fee is applied if a user cancels a “long” time before the pickup.
- Time before pickup until when the early cancellation fee is charged. Select the threshold from zero to ten hours in five-minute increments. If the time between cancellation and pickup time is greater than this threshold, the early cancellation fee is charged.
- Early cancellation relative to booking price. Specify the percentage of the booking price.

When a ride is canceled, this adapter determines the cancellation fee in the following order.

It first checks if the cancellation is a quick cancellation (if enabled).
It then checks if the cancellation is an early cancellation (if enabled).
If all previous checks fail, either the full booking price is charged for the cancellation (if enabled) or the standard cancellation fee is applied.

No-show fee calculation

If a passenger does not show up for the pickup, a no-show fee can be applied to the price of a ride.

No no-show fee

When this is selected, there is no fee for not showing up for a pickup.

Fixed no-show fee

Limit no-show fee on booking price (default = false). If enabled, the no-show fee cannot exceed the booking price. If disabled, the no-show fee is uncapped.
Use discounted booking price for no-show fee calculation (default = false). If enabled, the discounted booking price (considering personal discounts) is used instead of the non-discounted booking price when applying a fee limit.
Consume personal discount for free no-show fee (default = false). If enabled, a personal discount is consumed when the fee is greater than 0, and the fee is then set to 0.
Consume personal discount on no-show (default = false). If enabled, a personal discount is consumed if the fee calculation was affected by using the discounted booking price for the calculation.
No-show fee. This defines the fixed no-show fee.

Relative no-show fee

Use discounted booking price for no-show fee calculation (default = false). If enabled, the discounted booking price (considering personal discounts) is used instead of the non-discounted booking price when calculating a relative fee.
Consume personal discount for free no-show fee (default = false). If enabled, a personal discount is consumed when the fee is greater than 0, and the fee is then set to 0.
Consume personal discount on no-show (default = false). If enabled, a personal discount is consumed if the fee calculation was affected by using the discounted booking price for the calculation.
Relative no-show fee of booking price. This represents the standard no-show fee and is defined as a percentage of the booking price.
Minimum no-show fee. This sets the lowest possible no-show fee that will be charged, even if the calculated fee is less than this value.

Ticket price no-show fee

If ticketing is activated, and for a given ride a passenger does not show up, the adapter checks if a ticket was initialized and is in the state issued or retrieved. If this is not the case, a fixed no-show fee, which is set up in the product settings is chosen as final price. Otherwise, the adapter returns the maximum of the fixed no-show fee and the ticket price as the final no-show fee.

Ticket price no-show fee is a ticketing-integration-specific adapter and only works together with an external ticketing system.

If the driver cancels a ride due to any other reason than Passenger did not show up, where the No Show Fee Calculation is activated, the fare is set to zero.

Final price calculation

When a ride has reached a final state (dropped off or cancelled), this adapter is called to set the final price of the fare. At this point, the VAT rate is copied from the product to the ride because the applicable tax rate reflects when the service is provided, which is when the ride ends, not when it is booked.

Same as booking price (no change). This does nothing to the final price but just copies the booking price from the booking price adapter.
Discount for each encountered pooling. If this price adapter is chosen, a relative discount for each encountered pooling and a minimum price can be set. Then, the final price is computed by selecting the higher value between the minimum price and the discounted price.

Pooling discount
The booking price of a ride is calculated as 1 Euro, and two other rides get matched into the vehicle at the same time. If the relative discount is set to 10%, this results in (1-2*0.1)*1 = 0.8 Euros as the discounted price. However, if the minimum price was set to 1 Euro, the final price is 1 Euro.

Free cancellations

In the following situations, users can cancel their ride for free without incurring any fees, even if cancellation fees are configured in the product settings.

Passenger canceled before driver accepted

If the passenger cancels the ride while waiting for the driver to accept it, the cancellation is free. This is because the passenger has not blocked any resources in the system, and it’s not their fault that the driver did not respond to the ride request.

Pickup is delayed outside of negotiated times

If the pickup is delayed beyond the negotiated window—for example, the user was told the pickup would be between 12:00 and 12:05, but at 12:10 the vehicle still hasn’t arrived—no cancellation fee is charged. This is because the provider did not meet their commitment, and the user is given the option to either wait or cancel for free. If the vehicle arrives no later than the end of the negotiated pickup window, the pickup does not count as delayed, and the standard cancellation fees still apply. This waiver depends on whether the pickup falls outside the negotiated time window, not on a fixed number of minutes of delay.

Dropoff is delayed outside of negotiated times

Similarly, if the dropoff is expected to be delayed beyond the negotiated time, the user can cancel for free. Even if the driver picks up the user at the negotiated time, but the system predicts a delayed dropoff, the user can choose to either proceed with the ride or cancel for free.

The delay is measured for both the pickup and the dropoff against their own negotiated windows, whether the ride was booked by departure time or by arrival time.

Free no show

A no-show fee applies only when the vehicle reached the pickup location and the driver ends the ride as a no-show after the start of the negotiated pickup window. In the following situations, the no-show fee is waived.

The delay-based free cancellations above apply when the ride is canceled from the passenger or operator side, not when the driver ends the ride as a no-show. A pickup or dropoff that runs past the negotiated window does not by itself waive a no-show fee.

Vehicle never reached the pickup location

If the driver was never at the pickup point, they cannot reliably determine whether the passenger failed to appear. In this case, no no-show fee is charged.

Driver cancels before the negotiated time

Even if the driver reached the pickup location, ending the ride as a no-show at or before the start of the negotiated pickup window means the passenger is not at fault. A no-show fee is therefore not charged.

Personal discount only applies to first passenger

If this option is enabled, personal discounts only apply to the first passenger, that is, the booking user. If this option is not enabled, it’s used for all passengers of the ride.

Current fare matrix

To set a relation matrix as the current fare matrix, select one from the dropdown menu and then select Save.