Fare adapter configurations

The product feature fare adapter configurations lets a product define how ride fares are calculated as versioned, time-bounded configurations that are built from reusable pricing elements—base prices, discounts, and surcharges—rather than from a fixed set of product fare fields.

A product can keep several configurations side by side, each valid for a different period, so a price change can be prepared in advance and take effect automatically on a chosen date while older configurations stay intact for historical fares.

Overview

A fare adapter configuration belongs to a product and describes the pricing that applies during a validity period. Each configuration has:

• a name,
• a fare adapter—the pricing engine (booking price adapter) that turns the configuration and a ride into a booking price,
• a price version—the version of the pricing logic the configuration uses,
• a validity window, From and Until (Until must be after From),
• an Enabled flag,
• and a set of elements that define the actual prices.

Only one configuration applies to a given ride. For the ride’s pickup time, ioki Platform selects the configuration that is enabled, whose From is at or before that time, and whose Until is after it (or is empty). When several configurations match, the one with the latest From wins—so validity windows may overlap and a configuration with a later start automatically replaces an earlier one. The configuration that currently applies is shown as Active now.

Before a ride has a calculated pickup time—while it is still being created or searched for a vehicle—ioki Platform uses the passenger’s requested travel time to select the configuration and to check which passenger types are valid. This means an advance booking is validated against the configuration that will apply on the requested travel date, not the one active today. A booking requested now for a date inside a future configuration’s window is therefore checked against that future configuration.

The fare adapter is chosen when the configuration is created, and only in the Management Area—see there for how a product is switched onto self-service faring and how the adapter type is changed.

Elements

Each configuration is made up of elements. Every element has a price type:

• Base price. The starting fare for a single passenger type. It is an absolute amount (a whole number in the smallest currency unit, for example cents). A base-price element applies to exactly one passenger type.
• Zone code base price mapping. A base price whose amount depends on the fare-matrix zone code. It is used when the selected fare adapter prices by zones (see relation matrices): instead of a single amount, it maps each zone code to an amount.
• Distance base price mapping. A base price whose amount depends on the ride’s travel distance. It is used when the selected fare adapter prices by distance. Instead of a single amount, it defines a set of distance tiers, each with an upper distance limit and an amount. See distance-based base prices.
• Discount. Reduces the fare. Its discount type is one of:
  • Absolute discount. A fixed amount off.
  • Relative discount (%). A percentage off, between 1 and 100.
  • Target price. Sets the fare to a fixed target amount.
  • Target price mapping. Sets the fare to a target amount that varies by fare-matrix zone code. This discount type is available only when the selected fare adapter prices by zones.
• Surcharge. Adds a fixed absolute amount to the fare.
• Ride option surcharge. Adds a fixed absolute amount for each unit of a ride option the passenger selects, for example a per-bicycle transport fee. See ride option surcharges.

Each element also has a localized name, shown to passengers in each supported language, and an internal description used to tell elements apart in the configuration.

Passenger types and passenger options

• Base prices are defined per passenger type—exactly one passenger type per base-price element (for example, one base price for Adult and another for Child).
• Discounts and surcharges can apply to several passenger types at once. If no passenger type is set, they apply to all passengers.
• Any element can be tied to a passenger option. This is how option-dependent pricing is expressed—for example a base price for “Adult with a regional pass”, a discount that only applies when a passenger selects a specific option, or a “Bicycle” surcharge.

Free companion

A discount that is tied to a qualifying passenger option (a disabled-pass option) can grant a free companion. When it does, the configured companion passenger types travel free together with the eligible passenger.

Ride option surcharges

A ride option surcharge adds a fixed amount for each unit of a ride option a passenger selects when booking. A typical use is a per-bicycle transport fee: if the fee is €1.00 and the passenger brings two bicycles, €2.00 is added.

• The surcharge is applied once per unit of the ride option. A yes/no ride option counts as zero or one unit, and a numeric ride option counts as its value.
• It is a whole-ride charge, not a per-passenger one. The amount is added to the ride’s fare rather than to an individual passenger’s price.
• The surcharge applies on top of the base price, discounts, and other surcharges.

When you add a ride option surcharge element, you set the surcharge amount and select the Ride Option it applies to. Only yes/no and numeric ride options can be used for a ride option surcharge, and the ride option must belong to the same product as the configuration.

Distance-based base prices

When the selected fare adapter prices by distance, base prices are defined as distance tiers rather than as a single amount. Each tier has an upper distance limit (in kilometers) and an amount, and the tiers are listed in ascending order of their limit. The last tier is open-ended, with no upper limit, so that every distance is covered.

A ride is priced by the first tier whose upper limit is greater than the ride’s travel distance. The limit is exclusive: a distance exactly equal to a tier’s limit falls into the next tier. The open-ended last tier applies to every distance at or above the highest limit.

A configuration prices by distance with these tiers: up to 5 km costs €2.00, up to 10 km costs €3.00, and anything from 10 km costs €4.00. A 5 km ride is priced at €3.00, because 5 km is not below the 5 km limit and falls into the next tier. A 4.9 km ride is priced at €2.00, and a 12 km ride is priced at €4.00.

Element order

Discounts and surcharges carry an order. ioki Platform applies them from the lowest order to the highest, and within a single order at most one applies to each passenger—the first whose conditions that passenger meets. Elements that share an order are therefore mutually exclusive; elements in different orders stack. Base prices are always applied first, before any discount or surcharge.

This is how “one discount or another, whichever applies” is expressed: give the competing discounts the same order, and a passenger who qualifies for several receives only the first. Give elements different orders when they should apply on top of one another.

A regional-pass discount and a disabled-pass discount are both set to order 0, and a bicycle surcharge to order 1. A passenger who happens to hold both passes still receives only one of the two discounts—the first one. The bicycle surcharge is in a later order, so it still applies on top.

Validity and completeness

A configuration must first be valid before it can be saved: it needs a name, a fare adapter, a price version, and a From date, its Until (if set) must be after its From, and its base-price elements must match the chosen adapter (plain base prices for a per-passenger adapter, zone code base price mappings for a zone-based adapter, or distance base price mappings for a distance-based adapter).

A saved, valid configuration can still be incomplete—valid enough to store, but missing pieces it needs to price every ride correctly. A configuration is only complete when all of the following are true:

• every element has at least one localized name,
• every bookable passenger type is covered by a base-price element that has no passenger option, and
• for a zone-based fare adapter, every zone code in the product’s current fare matrix has a mapped base price.

An incomplete configuration that is currently active raises a product validation warning, prompting someone to add the missing elements or translations. If a product supports the feature but has no configuration at all, a separate validation warns that one still needs to be created.

While the feature is active, base-price coverage also decides bookability: a passenger type is only bookable if the active configuration has a base price for it. A passenger type that is bookable on the product but not covered by the active configuration cannot be booked until a base price is added.

Locked configurations

As soon as a configuration has been used to calculate a real fare, it is locked to protect historical prices:

• On a configuration, only the name can still be changed.
• On an element, only the description and its localized names can still be changed, and elements can no longer be added or removed.

This lock applies in production. On non-production environments the restriction is lifted so that pricing can be tried out freely before it goes live.

Fare adapters

The fare adapter (booking price adapter) is the engine that combines a configuration’s elements with a ride to produce its booking price. The available adapters are provided by ioki’s faring engine, and each adapter declares the inputs it needs—for example a zone-based adapter requires the fare-matrix zone codes described above, while others price by distance or a fixed amount per passenger.

The booking price adapter is separate from the cancellation fee, no-show fee, and final price adapters, which are configured as product fare settings (see fare calculation adapters in the Management Area).

A product wants this pricing:

• adults pay a €2.50 base fare,
• children pay a €1.50 base fare,
• anyone who brings a bicycle pays a €1.00 surcharge,
• holders of a regional pass get 50% off.

The configuration would contain four elements (amounts are whole numbers in cents):

Element	Price type	Passenger type	Passenger option	Amount
Adult base fare	Base price	Adult	—	250
Child base fare	Base price	Child	—	150
Bicycle	Surcharge	all	Bicycle	100
Regional pass	Discount (relative)	all	Regional pass	50 (%)

An adult who brings a bicycle and holds a regional pass is priced from the adult base fare of €2.50, plus the €1.00 bicycle surcharge, then the 50% regional-pass discount is applied—€3.50 reduced by half, giving a €1.75 booking price. A child with no options pays the €1.50 base fare.

Activate this feature

Roles: Super Admin

1. Navigate to the management settings of the product.
2. Within the Product features section, select the checkbox Fare adapter configurations.
3. Select Save.

Once the feature is active, a Product Admin manages the configurations and their elements in Control Center—see Fare adapter configurations in Control Center.