public-api-docs

User API Subscriptions And Rate Plans Guide

Overview

Subscriptions are recurring user benefits. They can grant recurring value, free minutes, discounts, rental rebates, rental-count entitlements, or access to a commercial tier. User subscriptions are the user’s concrete purchased instances.

Rate plans are pricing configurations used to calculate rental or booking prices. In the API they are exposed as pricing bundles and pricing calculators. They are not the same as subscriptions: a subscription is something a user buys or owns; a rate plan is the pricing logic used to estimate or calculate trip cost.

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

Subscription Catalog

Use GET /subscriptions?branchId={branchId} to show subscription products available for a branch. The response contains subscription voucherables with pricing and plan metadata.

Important catalog fields:

Field Meaning
code Stable subscription code used for detail and purchase actions.
name, description, iconUrl Catalog display fields.
price, currency, invoiceDescription User-facing billing information.
interval Renewal interval such as daily, weekly, monthly, or yearly.
initialPrice, initialIterations Introductory pricing, when configured.
highlight, showInUserApp Catalog presentation hints.
value, rentalRebate, discount, numberOfRentals Benefits the subscription can grant.
applicableBranchIds, applicableVehicleCategoryIds Where benefits apply.

Use GET /subscriptions/{subscriptionCode} to load a specific subscription detail page.

User Subscriptions

Use GET /subscriptions without branchId or GET /user-subscriptions to show subscriptions owned by the authenticated user.

Important owned-subscription fields:

Field Meaning
id User-subscription ID for user-subscription management endpoints.
subscription The underlying subscription product.
boughtAt, validUntil Purchase and validity window.
autoRenewal Renewal status: active, inactive, or failed.
state Lifecycle state such as renewing, expired, switching, switched, or cancelled.
remainingNumberOfRentals, remainingValueGross, remainingValueNet Remaining benefit counters where available.
latestInvoiceId Latest related invoice, useful for invoice detail or unpaid invoice flows.
switchingTarget Pending target plan when a delayed switch is active.

Subscription Actions

Task Endpoint
Buy subscription POST /subscriptions/buy/{subscriptionCode}
Cancel auto-renewal by code POST /subscriptions/cancel/{subscriptionCode}
Reactivate auto-renewal POST /subscriptions/reactivate/{subscriptionCode}
Renew now POST /subscriptions/renew/{subscriptionCode}
Get owned subscription GET /user-subscriptions/{id}
Cancel or revert switch by ID DELETE /user-subscriptions/{id}
Switch tier POST /user-subscriptions/{id}/switch

Switching supports two product behaviors:

After every subscription action, re-fetch user subscriptions, balances, vouchers, and invoices if the UI displays them.

Rate Plans And Pricing Calculators

Rate plans are represented by pricing bundles and pricing bundle versions. User apps normally do not manage rate-plan configuration; they use calculators to preview price.

Use:

Treat calculator responses as estimates. The final charged price comes from the created rental, booking, invoice, and applied benefits.

Most Relevant APIs

Area Endpoints
Subscription catalog GET /subscriptions?branchId={branchId}, GET /subscriptions/{subscriptionCode}
Owned subscriptions GET /subscriptions, GET /user-subscriptions, GET /user-subscriptions/{id}
Subscription actions POST /subscriptions/buy/{subscriptionCode}, POST /subscriptions/cancel/{subscriptionCode}, POST /subscriptions/reactivate/{subscriptionCode}, POST /subscriptions/renew/{subscriptionCode}, DELETE /user-subscriptions/{id}, POST /user-subscriptions/{id}/switch
Rate-plan estimates GET /pricing-bundles/pricing-calculator, GET /pricing-bundles/pricing-simulator, GET /booking-price-calculator
Payments and invoices Payment setup and invoice endpoints in the Payments And Invoices Guide

Implementation Notes