public-api-docs

Operations API Pricing Guide

Overview

Pricing configuration controls how bookings, on-demand rentals, additions, packages, and discounts are priced. Use the Operations API pricing endpoints when building administrative tools for pricing setup, pricing review, simulation, or branch/category pricing assignments.

Pricing is configuration-heavy and can directly affect customer invoices. Treat pricing writes as administrative changes and test pricing behavior before publishing or assigning it broadly.

Related reference: Operations API

Operations API Guide

Rental Guide

Vehicle Category Guide

Error Codes

Core Concepts

Rental Phase Pricing

A rental price is built from rental phases. A phase is a time segment in a specific rental state:

Phase	Meaning
`RESERVATION_FREE`	Reservation time that is still inside the configured free window.
`RESERVATION_PAID`	Reservation time after the free window.
`DRIVING`	Active rental time while the vehicle is in driving mode.
`PARKING`	Active rental time while the vehicle is in parking mode.

When a rental changes state, a new phase can be opened. The final price is the sum of the priced phases plus additions, deposits, rebates, surcharges, and other applicable effects.

Pricing Bundles

A pricing bundle is a reusable pricing configuration. It contains metadata such as name, type, currency, distance unit, and one or more versions.

Public bundle types include:

Type	Use it for
`BOOKING`	Pricing configuration for booking-based rentals.
`ON_DEMAND_LEGACY`	Legacy on-demand/free-floating pricing configuration.

The bundle type matters because booking and on-demand pricing do not support the same pricing features. Use the bundle type and the endpoint family to decide which model applies before interpreting the pricing fields.

Bundle Versions

Pricing bundle versions preserve historical correctness. Existing rentals and bookings must keep using the bundle version that was active when they were created or committed, even if the operator later edits the pricing bundle.

Version statuses include:

Status	Meaning
`DRAFT`	Version is editable and not yet active.
`PUBLISHED`	Version is available for use from its effective date.
`SUPERSEDED`	Version has been replaced by a newer published version.
`ARCHIVED`	Version is no longer active for normal use.
`EXPIRED`	Version is no longer effective.

Do not update historical pricing by mutating an existing published version. Create a new version and publish it with the intended effective date.

Pricing Data Versions

There are two different version concepts that are easy to confuse:

Concept	Where you see it	What it means
Pricing bundle version	`pricingBundleVersion`, `pricingBundleVersionId`, `/pricing-bundles/{id}/versions`	The configured pricing rules that were selected for a booking or rental.
Price data version	`priceV3`, `priceV4`, and later price response shapes	The JSON structure used to store or return the calculated price breakdown.

When looking at rental or booking data, first check pricingBundleVersion. That tells you which configured pricing rules were applied. Then inspect the available price data fields to understand the calculated result.

Current response fields can include:

Field	How to use it
`price`	Simplified embedded rental price used for totals and legacy compatibility.
`priceV3`	Detailed price breakdown grouped by price types, additions, rebates, surcharges, penalties, and one tax percentage/default tax view.
`priceV4`	Detailed price breakdown with tax split support. Use this when tax-split detail is relevant.
`pricingBundleVersion`	Embedded reference to the bundle version that was applied to the booking or rental.

As a general rule, use the newest price data version present in the response for detailed price inspection. Use priceV4 when available because it preserves tax-split detail. Use priceV3 when working with older data, older integrations, or fields that only expose the V3 shape.

If later price data versions are added, treat them the same way: the highest available price data version is the most complete representation for new data, while older fields remain useful for historical data and backwards compatibility.

Do not infer the configured pricing rules from priceV3 or priceV4 alone. The relevant configured pricing rule is identified by pricingBundleVersion or, for older/fallback flows, by the branch/category pricing settings used when the rental was created.

Booking vs On-Demand Pricing Models

Booking pricing and on-demand pricing solve different product problems and expose different configuration concepts.

Pricing area	Applies to	Technical model	Typical use	API surface
Booking pricing bundle	Booking-based rentals	`PricingBundleType: "BOOKING"` with booking rates, additions, penalties, and optional adaptive rates.	Scheduled bookings with known start/end time.	`/pricing-bundles`, `/pricing-simulator/booking`
On-demand pricing bundle	Free-floating/on-demand rentals	`PricingBundleType: "ON_DEMAND_LEGACY"` with free-floating pricing settings.	Rentals that start now and end whenever the user ends them.	`/pricing-bundles`, `/pricing-simulator/free-floating`
On-demand pricing assignment	On-demand rentals	Branch + vehicle category assignment to an on-demand pricing option.	Selecting the applicable on-demand price for a category in a branch.	`/on-demand-pricing-options`, `/on-demand-pricing-assignments`
Package	User purchase product	Package/voucherable configuration.	Selling credit, benefits, or prepaid products.	`/packages`

Booking pricing can include booking-specific rate structures such as base rates, unlock fees, distance rates, night or weekend rates, adaptive rates, additions, cancellation behavior, and late-return behavior. These concepts are tied to a planned booking window and are not the same as on-demand time-slot pricing.

On-demand pricing can include driving and parking prices, unlock/base price, distance pricing, included kilometers, maximum prices, and the on-demand time-slot mode described below.

Do not try to build one generic pricing editor that exposes every field for every pricing type. A good operator tool should first branch by the pricing bundle type, then show only the fields and workflows that apply to that type.

Paid Reservation Pricing

Paid reservation time is priced as reservation phase time in the on-demand/free-floating pricing model. When a user purchases more reservation time through the User API, Core creates a RESERVATION_PAID phase and extends the rental reservation end time. The final rental price then includes the configured reservation price for that paid phase.

Configure paid reservation pricing in the ON_DEMAND_LEGACY pricing bundle used by the branch and vehicle category. In pricing data and simulator input this appears as the reservation part of the free-floating model, for example the reservation entries in FreeFloatingData and reservation pricing in PricingInformation.

Use this Operations API flow:

Find or create the relevant on-demand pricing bundle with GET /pricing-bundles or POST /pricing-bundles using type: "ON_DEMAND_LEGACY".
Create or update a draft pricing bundle version with /pricing-bundles/{pricingBundleId}/versions.
Configure the reservation price for paid reservation minutes in that version.
Test the result with POST /pricing-simulator/free-floating or GET /pricing-bundles/pricing-simulator, including reservation time in the simulated data.
Publish the version with POST /pricing-bundles/{pricingBundleId}/versions/{pricingBundleVersionId}/publish.
Assign the resulting pricing option to the correct branch and vehicle category with /on-demand-pricing-assignments.

The User API endpoint accepts minutes, not a pricing package ID. If an app sells fixed extension choices such as 5, 10, or 15 minutes, those choices should be derived from product configuration and priced by the active reservation pricing. Use the package/voucherable model only when the operator is selling a separate prepaid benefit product, not for the normal paid-reservation extension button.

On-Demand Rate Selector vs Staircase Pricing

On-demand/free-floating pricing supports two mutually exclusive time-slot modes. They cannot coexist in one on-demand pricing definition because freeFloatingPricingMode selects one calculation strategy.

Mode	Technical value	How it works	When to use
Rate selector	`ENDING_TIMESLOT`	Selects one applicable time slot based on the final billable rental duration, then prices the billable rental time with that selected rate.	When the whole on-demand rental should use the rate tier reached by the final duration.
Staircase pricing	`CUMULATIVE_TIMESLOTS`	Splits the rental across elapsed time periods and prices each period with its configured rate.	When the on-demand price should change as the rental crosses time thresholds.

Both modes are on-demand concepts. Do not apply them to booking pricing bundles. Booking pricing has its own rate model for booked time, distance, additions, penalties, and adaptive rates.

The most important technical difference is how time thresholds are interpreted:

With rate selector pricing, the final rental duration selects one tier.
With staircase pricing, each elapsed time segment can use a different tier.

For example, if an on-demand rental has thresholds at 0 minutes and 30 minutes, rate selector pricing can price the whole billable duration with the tier selected by the final duration. Staircase pricing can price the first segment with the first tier and the later segment with the second tier.

For API usage:

Use GET /on-demand-pricing-options and /on-demand-pricing-assignments to understand which on-demand pricing option applies to a branch/category.
Use POST /pricing-simulator/free-floating or GET /pricing-bundles/pricing-simulator to test on-demand pricing behavior.
Use POST /pricing-simulator/booking for booking pricing behavior.
When reading a pricing bundle, check its type before interpreting its rate fields.

Use this decision path when building pricing tooling:

Decide whether the workflow is for a booking, an on-demand rental, or a package.
For bookings, work with BOOKING pricing bundles and booking simulator endpoints.
For on-demand rentals, work with ON_DEMAND_LEGACY pricing bundles, on-demand pricing options, and on-demand pricing assignments.
For on-demand rentals, choose exactly one freeFloatingPricingMode: rate selector (ENDING_TIMESLOT) or staircase pricing (CUMULATIVE_TIMESLOTS).
For packages and paid benefits, use the promotions/benefits model; packages are purchasable products and are not rental price-calculation rules.

When reading existing rental or booking data, use the pricing bundle version and the rental or booking type to determine which pricing model was used. Booking-only concepts such as adaptive booking rates or cancellation penalties should not be expected on on-demand pricing. On-demand-only concepts such as driving/parking time-slot modes and on-demand default/alternative assignments should not be expected on booking pricing.

Vehicle Category Pricing References

Vehicle categories can reference pricing configuration. Important category-level pricing fields include:

Field	Purpose
`priceCalcKey`	Connects a vehicle category to a pricing calculation setting.
`rentalAdditionPriceCalcs`	Maps rental addition codes to price calculation keys.

For category configuration, see the Operations API Vehicle Category Guide.

Packages

Packages are paid benefit products that users can buy, usually to receive balance, credit, minutes, discounts, or another configured benefit. Package management belongs next to pricing because package price, validity, applicability, and discount behavior affect what customers pay and what credit or benefits they receive.

Packages are different from pricing bundles. Pricing bundles define rental price calculation. Packages are products purchased by users and applied through the voucher/wallet/benefit system.

Use the Operations API Promotions, Packages, Subscriptions, And Benefits Guide for package, subscription, promotion, ride-pass, customer-care, and benefit catalog workflows. The legacy /packages endpoints are deprecated.

Common Operator Workflows

List Pricing Bundles

Use GET /pricing-bundles.

Useful filters:

searchText to search by bundle text.
includeVersions=true when the list view needs version summaries.
vehicleCategoryId when reviewing bundles related to one category.
branchId when reviewing pricing relevant to a branch.

The response is paginated.

Manage Pricing Bundles

Use the pricing bundle endpoints for administrative bundle configuration:

Task	Endpoint
List bundles	`GET /pricing-bundles`
Create bundle	`POST /pricing-bundles`
Get one bundle	`GET /pricing-bundles/{pricingBundleId}`
Update bundle metadata	`PUT /pricing-bundles/{pricingBundleId}`
Delete bundle	`DELETE /pricing-bundles/{pricingBundleId}`

Bundle metadata identifies the pricing product. Actual price behavior is controlled by versions.

Manage Bundle Versions

Use version endpoints when creating, reviewing, publishing, or replacing pricing behavior:

Task	Endpoint
List versions	`GET /pricing-bundles/{pricingBundleId}/versions`
Create version	`POST /pricing-bundles/{pricingBundleId}/versions`
Get one version	`GET /pricing-bundles/{pricingBundleId}/versions/{pricingBundleVersionId}`
Update version	`PUT /pricing-bundles/{pricingBundleId}/versions/{pricingBundleVersionId}`
Publish version	`POST /pricing-bundles/{pricingBundleId}/versions/{pricingBundleVersionId}/publish`

Recommended workflow:

Create or select a pricing bundle.
Create a draft version.
Simulate prices for representative rentals or bookings.
Publish the version with the intended effective date.
Verify branch/category assignment or related configuration.

Simulate Pricing

Use pricing simulators before publishing or assigning pricing changes.

Task	Endpoint
Simulate booking price with provided settings	`POST /pricing-simulator/booking`
Simulate free-floating price with provided settings	`POST /pricing-simulator/free-floating`
Simulate price by pricing bundle	`GET /pricing-bundles/pricing-simulator`
Calculate price by pricing bundle or assignment	`GET /pricing-bundles/pricing-calculator`

Use simulator endpoints for “what would this cost?” tools, pricing preview screens, and QA before publishing. Use calculator endpoints when the tool needs pricing output based on a concrete bundle or assignment reference.

Manage On-Demand Pricing Assignments

On-demand pricing assignments connect pricing options to a branch and vehicle category.

Use these endpoints:

Task	Endpoint
List pricing options	`GET /on-demand-pricing-options`
List assignments	`GET /on-demand-pricing-assignments`
Assignment overview for a branch	`GET /on-demand-pricing-assignments/overview`
Create assignment	`POST /on-demand-pricing-assignments`
Get one assignment	`GET /on-demand-pricing-assignments/{id}`
Mark assignment as default	`POST /on-demand-pricing-assignments/{id}/mark-as-default`
Replace default assignment	`PUT /on-demand-pricing-assignments/replace-default`
Replace alternative assignments	`PUT /on-demand-pricing-assignments/replace-alternatives`
Delete assignment	`DELETE /on-demand-pricing-assignments/{id}`

Use GET /on-demand-pricing-options?categoryId={vehicleCategoryId} to discover pricing options for a category before creating or replacing assignments.

Manage Packages

For new paid package tooling, use /voucherables with type=Package. The legacy package endpoints still exist but are deprecated:

Task	Endpoint
List packages	`GET /packages`
Create package	`POST /packages`
Get one package	`GET /packages/{id}`
Patch package	`PATCH /packages/{id}`

Packages can be scoped by branch and applicable vehicle categories. They can also have benefits, validity, redeem limits, state, visibility in the user app, and invoice/payment-related fields.

Most Relevant APIs

Task	Endpoint
List pricing bundles	`GET /pricing-bundles`
Create pricing bundle	`POST /pricing-bundles`
Get pricing bundle	`GET /pricing-bundles/{pricingBundleId}`
Update pricing bundle	`PUT /pricing-bundles/{pricingBundleId}`
Delete pricing bundle	`DELETE /pricing-bundles/{pricingBundleId}`
List bundle versions	`GET /pricing-bundles/{pricingBundleId}/versions`
Create bundle version	`POST /pricing-bundles/{pricingBundleId}/versions`
Get bundle version	`GET /pricing-bundles/{pricingBundleId}/versions/{pricingBundleVersionId}`
Update bundle version	`PUT /pricing-bundles/{pricingBundleId}/versions/{pricingBundleVersionId}`
Publish bundle version	`POST /pricing-bundles/{pricingBundleId}/versions/{pricingBundleVersionId}/publish`
Simulate booking pricing	`POST /pricing-simulator/booking`
Simulate free-floating pricing	`POST /pricing-simulator/free-floating`
Simulate bundle pricing	`GET /pricing-bundles/pricing-simulator`
Calculate bundle or assignment price	`GET /pricing-bundles/pricing-calculator`
List on-demand pricing options	`GET /on-demand-pricing-options`
Manage on-demand pricing assignments	`GET/POST/PUT/DELETE /on-demand-pricing-assignments`
Manage packages	`GET/POST/PATCH /packages`

Permissions And Settings

Pricing configuration is administrative. Operators may be able to view pricing but not create, publish, assign, or delete pricing configuration.

Common permission areas:

Workflow	Permission consideration
View pricing bundles and versions	Pricing read/admin visibility.
Create/update/delete bundles	Pricing administration permissions.
Publish bundle versions	Pricing administration permissions; this can affect customer prices.
Manage on-demand pricing assignments	Branch/category pricing administration.
Manage packages	Package/voucherable administration.
Simulate pricing	Pricing read/admin visibility, depending on simulator input.

Pricing behavior can also depend on settings and category configuration:

Area	Why it matters
Vehicle category `priceCalcKey`	Connects a category to pricing calculation behavior.
Vehicle category `rentalAdditionPriceCalcs`	Prices additions attached to rentals.
Branch/payment settings	Can affect currency, deposits, payment methods, and invoice behavior.
Rental requirements	Can trigger payment pre-authorization or deposits before start.

Implementation Notes For Custom Tools

Never assume the latest bundle version applies to an existing rental or booking; use the version associated with that rental or booking.
Do not confuse price data versions such as priceV3 and priceV4 with pricing bundle versions. priceV3/priceV4 describe calculated price data shape; pricingBundleVersion describes the configured pricing rules that were applied.
Prefer the newest price data version available in the response for detailed inspection, especially priceV4 when tax split matters.
Check whether a pricing bundle is BOOKING or ON_DEMAND_LEGACY before interpreting its rate fields.
Do not combine on-demand rate selector and staircase pricing in one pricing definition; they are alternative freeFloatingPricingMode strategies.
Create a new bundle version for changed pricing behavior instead of mutating historical pricing.
Simulate representative scenarios before publishing pricing changes.
Make the branch, vehicle category, currency, and effective date visible in pricing admin tools.
Treat publishing, assignment replacement, package activation, and package price changes as high-impact actions.
Use package endpoints for purchasable credit/benefit products, not for rental price calculation.
Use pricing bundle and assignment endpoints for rental pricing behavior.

Review Notes

The following product decisions are reflected in this guide:

Pricing bundles and versions are documented as the main reusable rental-pricing configuration surface.
Bundle versioning is documented as required for historical rental correctness.
Price data versions such as priceV3 and priceV4 are documented separately from pricing bundle versions.
Booking and on-demand pricing models are documented as separate concepts with different supported pricing options.
On-demand rate selector and staircase pricing are documented as mutually exclusive on-demand modes.
On-demand pricing assignments are documented as branch/category assignment workflows.
Packages are included because they are pricing-adjacent paid products, but they are not the same as pricing bundles.
Pricing bundle assignment endpoints that are not present in the public Operations API specification are intentionally not documented here.