Fare adapter configurations
Roles: Super Admin Permissions:
manage_products
In the Management Area, a Super Admin manages a product’s fare adapter configurations. Two things can be done here that a Product Admin cannot do in Control Center:
- create a configuration from scratch, and
- choose which fare adapter a configuration uses.
(A Product Admin can duplicate an existing configuration in Control Center, but that inherits the original’s adapter—it doesn’t create one from scratch or let a different adapter be chosen.)
Everything else—viewing, duplicating, editing details, managing elements, and deleting unused configurations—a Product Admin also does in Control Center; those procedures are documented once, in Fare adapter configurations in Control Center. For what a configuration is, its elements, completeness, and locking, see Fare adapter configurations in Platform.
This is a separate area from the fare calculation adapters section of the product settings. That settings section picks the product’s booking price adapter for products that do not use self-service faring; the configurations and their adapter are managed here.
Self-service faring vs. custom adapters
A product’s booking price is produced by a booking price adapter. There are two ways a product can get one:
- Custom (or standard) adapter. The booking price adapter is set directly in fare calculation adapters. Its pricing is fixed logic or logic built for one product, and changing it needs a code or settings change by ioki.
- Self-service faring. The product supports fare adapter configurations, and the booking price adapter is a configurable one whose prices are defined by a configuration. A Product Admin can then prepare and schedule price changes themselves.
“Self-service faring” is not a separate toggle. It is the combination of the Fare adapter configurations product feature being active and the active configuration using a Configurable with … adapter. When the feature is active, the booking price adapter set in fare calculation adapters is ignored—the adapter and the prices both come from the configuration that applies to the ride.
The configurable adapters are the ones whose name begins with Configurable with:
| Adapter | Prices by |
|---|---|
| Configurable with fixed base price | a fixed base price per passenger type |
| Configurable with zone code-based base price | base prices depend on the passenger type and the fare-matrix zone code (see relation matrices) |
| Configurable with distance-based base price | base prices depend on the passenger type and the ride’s travel distance, using distance tiers |
Create a configuration
Creating a configuration is only possible here, in the Management Area. You choose its fare adapter—only the Configurable with … adapters are offered, so a configuration can never point at a custom adapter—along with its name, price version, From/Until validity window, and whether it is Enabled.
Once a configuration has been used to calculate a ride’s fare it is locked: only its name, description, and the localized titles of its elements can still be changed. The fare adapter can no longer be changed. On non-production environments this restriction is lifted so pricing can be tried out. To change the adapter of a locked configuration, create a new one—see the workflows below.
The configuration that applies to a ride is the enabled one whose validity window covers the ride’s pickup time, with the latest From winning when several overlap (see which configuration applies in Platform).
Leave Until empty on almost every configuration. Because the enabled configuration with the latest From at or before the ride wins, a newer configuration automatically supersedes an older one—you don’t end the old one, you just start a new one. Set Until only when pricing should genuinely stop with no replacement. Keeping the earliest configuration’s From in the past with no Until guarantees there is always an active configuration for any pickup time, so a live product is never left without one.
Switch a product from a custom adapter to self-service faring
Prepare the configuration before activating the feature, and activate the feature last. On a live product the feature takes effect the moment it is switched on; if no enabled, complete configuration already covers the current time, the product is left without a booking price until one does.
- Create a configuration (above) and choose a Configurable with … adapter that matches how the product should price rides. Set its From to today (or earlier) and leave Until empty.
- Add its elements—base prices for every bookable passenger type, plus any discounts and surcharges—with localized names, until the configuration is complete.
- Mark the configuration Enabled.
- In the product’s management settings, under Product features, activate Fare adapter configurations, then select Save.
Because the configuration’s From is at or before now and it has no Until, it applies the instant the feature is switched on and keeps applying. The booking price then comes from the configuration; the custom adapter previously set in fare calculation adapters is no longer used. To move back to a custom adapter, deactivate the feature and set the desired booking price adapter in fare calculation adapters.
Until an enabled, complete configuration covers the current time, the product raises a faring setup error—either that no configuration is configured, or that the active one is incomplete. This is why the configuration is created, completed, and enabled first, and the feature is activated last.
Switch the adapter type within self-service faring
Because a configuration’s adapter is fixed once it has been used for a fare, you switch adapter type—for example from Configurable with fixed base price to Configurable with zone code-based base price—by adding a new configuration rather than editing the old one:
- Create a new configuration and choose the new Configurable with … adapter.
- Add the elements the new adapter needs. A zone-code-based adapter needs a zone code base price mapping covering every zone code in the product’s current fare matrix; a fixed-base-price adapter needs a plain base price per passenger type; a distance-based adapter needs a distance base price mapping per passenger type. The configuration is only complete when its element price types match the chosen adapter.
- Set the new configuration’s From to the switch-over date, leave Until empty, and mark it Enabled. From that date it has the latest start and is selected automatically, while the old configuration keeps serving historical fares.
Duplicating a configuration keeps its adapter, so it fits a price change on the same adapter—not an adapter-type change. To change the adapter type, create a fresh configuration here so a new adapter can be selected.