public-api-docs

Operations API Business Units And Billable Branches Guide

Overview

Business units are the business-facing representation of billable branches. They define the financial and commercial scope used for currency, tax, payment routing, wallet balances, invoices, promotions, signup/referral benefits, reporting, and some business-account defaults.

Branches define where operations happen. Business units define where money, billing configuration, and commercial ownership are anchored. In many tenants the same branch can be both an operational branch and a business unit. In larger tenant setups, several operational branches can point to the same billable branch/business unit so they share financial configuration.

Use this guide when building operator tools for business unit administration, billable branch setup, branch-to-billing-scope troubleshooting, finance configuration, signup/referral benefits, or business-account default assignment.

Related reference: Operations API

Operations API Guide

Branches And Stations Guide

Customers And Groups Guide

Payments And Invoices Guide

Promotions, Packages, Subscriptions, And Benefits Guide

Error Codes

Core Concepts

Branch Vs Business Unit

Concept	Use it for
Branch	Operational scope: vehicles, rentals, bookings, stations, business areas, settings, permissions, and availability.
Business unit	Financial/commercial scope: currency, tax, payment configuration, wallet balances, invoices, voucher catalog, signup/referral benefits, and reporting ownership.
Billable branch	Technical branch specialization behind a business unit.
Non-billable branch	Operational or organizational branch that points to a billable branch/business unit.

In API responses, fields such as isBillable, billableBranchId, homeBillableBranchId, and branchId can all be involved. Operator tools should label the concept clearly:

Use “branch” for operational location and access scope.
Use “business unit” for commercial and billing scope.
Use “billable branch” only when explaining technical API fields.

Why Business Units Exist

Business units allow operators to run multiple locations or operational branches while sharing one commercial setup, or to split commercial setup when needed.

They control or influence:

Area	Why it matters
Currency and rounding	Balances, packages, invoices, and payment amounts must use the correct currency and scale.
Tax percentage	Invoices and billing reports depend on the business unit tax setup.
Payment routing	Merchant account override and payment gateway configuration belong to the billable scope.
Wallet balances	Balances are scoped per account and business unit. A user can have separate balances across business units.
Invoices	Invoice numbering, payment collection, and finance reporting follow the billable scope.
Promotions and benefits	Promotion/package/subscription templates are created on a business unit and can be scoped to applicable branches/categories.
Signup and referral benefits	Signup, referrer, and referee benefit templates can be configured on the business unit.
Terms and contact data	Commercial terms and business contact data can be attached to the business unit.

Permission Scope: Branch Or Business Unit

Operations API permissions are not always checked against the branch that appears in the request. Some workflows are operational and use branch permissions. Other workflows are commercial or financial and use the business unit behind the branch.

For example, a voucher can be linked to a branch, but that branch resolves to a business unit. To view, create, or update that voucher, the operator needs the required voucher permission on the business unit, not only operational access to the branch where the voucher can apply.

Workflow area	Permission scope to expect
Vehicles, rentals, bookings, tasks, damages, stations, POIs, fleet actions	Operational branch.
Branch/station administration	Operational branch, with elevated administrative permission.
Business unit setup, billable branch setup, currency, tax, merchant account, signup/referral benefits	Business unit/billable branch.
Vouchers, promotions, packages, subscriptions, ride passes, customer-care templates	Business unit that owns the catalog/template.
Issued vouchers and redeemable codes	Business unit that owns the voucher or voucher template.
Balances, invoices, payments, payment sources, refunds, settlements	Business unit/billable branch.
Settings	Depends on the setting area and feature; check whether the setting is branch-operational or business-unit/commercial.

When building tooling, resolve and display both scopes when they differ:

The operational branch where the vehicle, rental, booking, station, or customer workflow happens.
The business unit/billable branch that owns the financial or commercial resource.

This avoids confusing “insufficient permission” errors where an operator can see an operational branch but cannot view or edit vouchers, balances, invoices, or payment configuration owned by the linked business unit.

Relationship To Customers And Groups

Customers and business accounts can have business-unit context:

Field/concept	Meaning
`homeBillableBranchId`	Customer’s home business unit/billable branch.
Business account default business unit	Default commercial scope for a business account/group.
Balance branch filter	`GET /balances?branchId=...` limits balances to the billable branch of the provided branch.
Business rentals/bookings	Business-account billing and reporting can use business-unit context.

At the moment, user groups are mostly used for business accounts, and one user can be a member of only one business account. Business units should therefore be documented as billing/reporting scope, not as a replacement for group membership.

Business Unit Fields

The BusinessUnit schema contains branch-like and billing-specific fields:

Field	Meaning
`id`	Business unit identifier.
`code` / `name`	Business unit code and display name.
`timeZoneId`	Time zone used for business context.
`contactInfo`	Public, billing, address, email, phone, and location guideline information.
`uiSettings`	Dashboard or UI display configuration.
`currency`	Currency used for balances, packages, and invoices.
`taxPercentage`	Tax rate for billing.
`scale`	Rounding scale.
`termsAndConditionsId`	Terms and conditions attached to this business unit.
`merchantAccountOverride`	Payment provider merchant account override.
`reserveAmountOnCc`	Credit-card reserve amount where applicable.
`sepaHandlingFeeNet`	SEPA handling fee configuration.
`signupVoucherableId`	Benefit template for signup.
`referrerVoucherableId`	Benefit template for referrers.
`refereeVoucherableId`	Benefit template for referred users.
`appProperties` / `dashboardProperties`	Tenant-specific metadata.

Common Operator Workflows

List And Search Business Units

Use GET /business-units.

Useful parameters:

Parameter	Use it for
`searchText`	Search business units by text.

Use this endpoint when an operator tool needs to let the user choose a commercial scope, review configured business units, or resolve which business unit a branch points to.

Create Or Update A Business Unit

Use:

Task	Endpoint
Create business unit	`POST /business-units`
Get business unit	`GET /business-units/{id}`
Update business unit	`PUT /business-units/{id}`
Delete unused business unit	`DELETE /business-units/{id}`

Only delete a business unit if it has not been referenced anywhere yet. After a business unit has balances, invoices, packages, vouchers, customer/group references, branch references, or other business data, tools should treat it as historical configuration and avoid deletion.

Update Billable Branch Configuration

Some billing-scope configuration is also exposed through branch endpoints:

Task	Endpoint
Update billable branch	`PUT /branches/billable/{id}`

Use this only for administrative workflows. Updating billable branch fields can affect payment routing, tax, invoice output, signup/referral benefits, balances, package purchases, and promotion behavior.

Migrate Away From Revenue Centers

Revenue center endpoints are deprecated and replaced by business units.

Deprecated	Use instead
`GET /revenue-centers`	`GET /business-units`
`POST /revenue-centers`	`POST /business-units`
`GET /revenue-centers/{id}`	`GET /business-units/{id}`
`PUT /revenue-centers/{id}`	`PUT /business-units/{id}`
`DELETE /revenue-centers/{id}`	`DELETE /business-units/{id}`

New tools should not use revenue-center endpoints.

Troubleshoot Balance Or Voucher Scope

When a customer says credit, minutes, a package, or a promotion is missing, check the business unit context:

Identify the operational branch of the rental, booking, or vehicle.
Resolve the billable branch/business unit behind that branch.
Check the customer’s balance for that business unit.
Check whether the promotion/package/subscription applies to that business unit, branch, and vehicle category.
Check whether the customer has an issued voucher and whether it is active, expired, used up, canceled, or not redeemed.

Balances and benefits can be valid in one business unit but not another.

Business units can reference signup, referrer, and referee benefit templates. These templates are managed through the promotions and benefits model and referenced by ID on the business unit.

Use the Promotions, Packages, Subscriptions, And Benefits Guide to understand the benefit templates before assigning them to a business unit.

Most Relevant APIs

Area	Endpoint
Business units	`GET /business-units`, `POST /business-units`
Business unit detail	`GET /business-units/{id}`
Business unit update	`PUT /business-units/{id}`
Delete unused business unit	`DELETE /business-units/{id}`
Billable branch update	`PUT /branches/billable/{id}`
Deprecated revenue centers	`/revenue-centers`, `/revenue-centers/{id}`
Balances by business unit context	`GET /balances?branchId={branchId}`
Benefit templates	`/voucherables`

Permissions And Settings

Business unit and billable branch configuration is administrative. It should not be exposed to normal support or fleet roles unless the operator explicitly wants them to manage commercial setup.

Access to commercial resources is usually checked on the business unit. A user with branch-level fleet permissions may still be blocked from voucher, balance, invoice, payment, package, subscription, or business-unit configuration endpoints if they do not have the matching permission on the business unit.

For custom tools:

Require business-unit administration permission before showing create/update/delete actions.
Check business-unit permissions before showing voucher, package, subscription, balance, invoice, payment, or settlement actions.
If a request uses a branchId filter but returns commercial data, treat the branch as a way to resolve the business unit permission scope.
Treat payment routing, currency, tax, and merchant account changes as high-impact changes.
Do not allow deletion unless the business unit is unused.
Prefer /business-units over deprecated /revenue-centers.
Root permissions are reserved for Wunder Mobility and can only be accessed by Wunder Mobility.

Implementation Notes

Label the public concept as “business unit”; mention “billable branch” only where it maps to API fields.
Do not assume branchId always means the same thing across workflows. In some finance endpoints it is used to resolve the billable branch behind the provided branch.
When showing balances, invoices, packages, or promotions, include the business unit/currency context.
When showing rentals or bookings, include both operational branch and business unit where finance context matters.
For permission errors, show both the operational branch and business unit so administrators know which role assignment to review.
Keep business unit writes separate from ordinary branch/station operational tooling.

Review Notes

Confirm whether tenant-specific terminology uses “business unit”, “market”, “legal entity”, or another operator-facing term before building UI labels. The API concept remains the same, but operator teams may recognize it by a local business name.