public-api-docs

User API Packages Guide

Overview

Packages are purchasable benefit products. A user buys a package once, and the package can grant wallet value, free minutes, rental rebates, discounts, rental-count entitlements, or addition entitlements depending on how the operator configured the package.

Packages are not rate plans. Rate plans define how rentals or bookings are priced. Packages define something the customer buys that can later affect the user’s wallet, voucher entitlements, or rental price calculation.

Related reference: User API User API Guide Payments And Invoices Guide Wallet And Balances Guide Vouchers And Promotions Guide

Core Concepts

Package Catalog

Use GET /packages?branchId={branchId} to show packages available in a branch. Packages are branch-scoped and can also be limited to specific vehicle categories.

Important fields:

Field Meaning
code Stable package code used for pricing and purchase.
name, description, iconUrl Catalog display fields.
value Package value when the package grants monetary wallet value.
rentalRebate, discount Rental price benefits granted by the package.
numberOfRentals Rental-count entitlement.
validityPeriod, validityTimeUnit, validityDateUntil Validity rules for the issued benefit.
applicableBranchIds, applicableVehicleCategoryIds Where the package benefit can be used.
applicablePriceType Price component targeted by the benefit, such as driving, parking, reservation, distance, or unlock fee.

Use hasValue=true when the app is building a wallet top-up style catalog and only wants packages with monetary value.

Package Pricing

Before purchase, call GET /packages/{packageCode}/pricing. This resolves the package price with any applicable automatic discount or optional promotionCode.

Use this endpoint for the final confirmation screen, not only the catalog list, because package price can depend on promotions and tenant configuration.

Purchase Flow

Typical flow:

  1. Resolve branch context.
  2. List packages with GET /packages?branchId={branchId}.
  3. User selects a package.
  4. Resolve final price with GET /packages/{packageCode}/pricing.
  5. Confirm payment method if required.
  6. Buy the package with POST /packages/buy.
  7. Re-fetch balances, vouchers, and package-related wallet history.

POST /packages/buy can return:

Response Meaning
204 No Content Package purchase completed directly.
200 OK Additional payment authentication or redirect information is required.

When the app uses push-based payment redirects, pass push=true and use the push request body variant.

Most Relevant APIs

Area Endpoints
Package catalog GET /packages
Package price GET /packages/{packageCode}/pricing
Package purchase POST /packages/buy
Payment methods GET /payment-sources, payment setup endpoints in the Payments And Invoices Guide
Wallet refresh GET /balances, GET /vouchers, GET /balances/{balanceId}/history

Implementation Notes