Skip to main content
A service fee is an additional charge — a booking fee, an admin fee, a convenience surcharge — that rides along with a sale without being folded into the price of any single line. This page covers where fees live, how they’re charged, and the three behaviours around currency, tax, and resolution that you can’t infer from the schema alone.

Fees are configured on a business model, not an offering

fees is a top-level array on a ServiceBusinessModel (POST / PUT /v1/projects/{projectId}/services/{serviceId}/business-models), not on the offering or the package being sold:
A business model is the commercial definition behind how a service is sold (SINGLE_BOOKING, PACKAGE, SCHEDULED_PACKAGE, SCHEDULED_SUBSCRIPTION, FLEXIBLE_SUBSCRIPTION) — every offering under that service inherits whichever business model governs the order line’s skuType. Configure the fee once on the business model, and every offering sold under it picks the fee up automatically. You will not find fees anywhere on an offering or package resource; it does not exist there.

Fees apply once per order, not once per line

If a business model’s fee governs three order lines, the fee is still charged once — not three times. Fees are grouped by (businessModelId, feeId): every line on the order that resolved to the same business model contributes to the same fee instance, and that instance appears once in the order summary, however many lines it governs. This also means a PERCENT fee’s basis is not “this one line’s total” — it’s the pre-tax total of every line on the order sold under that same business model. Add a second line under the same business model and the fee’s basis (and therefore its amount) grows to include it; add a line under a different business model and it has no effect on this fee at all.

Fees sit outside subtotal

A fee is not baked into any line’s price and is not tax. It’s a third, parallel component of the order total:
Fee tax is included in taxTotal (not folded into feeTotal), but the fee itself is never folded into subtotal. The order summary surfaces this as discrete data rather than requiring you to infer it:
Each entry in summary.fees carries basis — the amount the fee was calculated against — even for a FLAT fee, where it isn’t used in the calculation. It’s reported anyway so the figure is auditable: you can see exactly which lines the fee grouped with, without recomputing the grouping yourself.
fees and feeTotal appear on every response shape that carries an order summary — order create, the items endpoints, and the aggregate GET. They are never absent from a summary; an order with no applicable fees simply returns fees: [] and feeTotal: { amount: 0, ... }.
You set no figure in this equation yourself. The platform computes taxTotal, including the tax on taxable fees, and PATCH .../orders/{orderId} refuses a tax that would change it with 400 TAX_MISMATCH. See Updating an order.

Three things the schema won’t tell you

A FLAT fee has no currency of its own

amount on a FLAT fee is a bare integer in the currency’s minor unit — it carries no currency field. It is charged in whatever currency the order is placed in, whatever that turns out to be:
2500 is CA$25.00** on an order placed in CAD, and **US$25.00 on an order placed in USD — same configured value, different real-world cost to the buyer depending on which currency the order resolved to (see Regional pricing for how that’s decided). If a fee needs to represent the same buyer-facing cost regardless of currency, that’s not what FLAT does. Use calculation: "PERCENT" instead — a percentage scales correctly with whatever the order’s lines already priced at in that currency.

A taxable fee borrows the rate of a taxed line

Setting taxable: true makes a fee inherit a tax rate from its governing lines — it does not carry a rate of its own. The fee takes the rate of the first governing line that is taxed at a positive rate. Lines that are not taxable, or are taxed at 0%, lend no rate, so the order of the lines never changes the fee’s tax. When none of the governing lines is taxed, the fee comes back with tax: { amount: 0, ... }. The fee itself is still charged. Each untaxed line says why in its taxExemptReason — see How tax is computed. PACKAGE lines are taxed like any other line, so a taxable fee on a package-only order is taxed at the package’s rate.

No matching active business model means the line is refused

An order line’s business model is resolved server-side, from the line’s skuType, against the service’s ServiceBusinessModel records — you never name a business model directly when creating an order or an order item. For a SINGLE_SESSION, PACKAGE or SUBSCRIPTION line, the service must have an active business model of a matching type (see the mapping table). If it has none, or every matching one has active: false, the service isn’t sold that way. The line is refused with 422 SERVICE_NOT_SOLD_AS, and nothing is written — not the order on POST .../orders, not the item on POST .../orders/{orderId}/items:
Activate a matching business model on the service, or sell the line under a skuType the service has an active model for. Only MEMBERSHIP and DEPOSIT lines resolve to no business model. They are created normally, carry no businessModelId, never carry a fee, and don’t contribute to any other line’s fee basis.

Configuring fees

Which business model to put the fee on

You never name a business model when creating an order. The server picks it from the line’s skuType, so the model type you configure the fee on determines which sales the fee applies to: “Falling back” means the exact match wins when it is active, and the fallback is used only when no exact match is active. So a PACKAGE line prefers your PACKAGE model and drops to SCHEDULED_PACKAGE if that is the only active one. When neither is active, the line is refused with 422 SERVICE_NOT_SOLD_AS.
MEMBERSHIP and DEPOSIT have no business model counterpart at all, so fees can never be charged on those lines. There is no error and no warning — the line simply carries no fee. If you need a charge on a membership or a deposit, a service fee is the wrong mechanism.

Updating fees replaces the whole array

fees on PUT .../business-models/{businessModelId} is a whole-value replacement, matching paymentOptions and config on the same endpoint. It is not a merge and not an append.
To add a second fee, send both fees in one PUT. Sending only the new one deletes the existing one, with a 200 and no warning. Read the current array first (GET .../business-models), append to it, and send the whole thing back.

Validation rules

A malformed array is rejected with a 400 before anything is stored: Setting both amount and percentage, or neither, is the most common 400 here. The two fields are mutually exclusive and which one is required is decided entirely by calculation.

The model must be active

A fee on an inactive business model is stored but never charged. If no other matching model on the service is active, the lines it would govern are refused with 422 SERVICE_NOT_SOLD_AS. Activate with:
Toggling status never touches fees — deactivating preserves them, and reactivating restores the model with its fees intact.

Why isn’t my fee being charged?

If the order was refused with 422 SERVICE_NOT_SOLD_AS, the service has no active business model for the line’s skuType — see above. Once an order is created, a missing fee is silent: the order still succeeds, so a misconfiguration looks like nothing happening rather than like an error. Work through these in order:
  1. Is the business model active? An inactive model never charges its fees. If another matching model is active (a fallback type), that one governs the line instead. Check with GET .../business-models.
  2. Does the model’s type govern the skuType you are selling? See the mapping table above. A fee on a SINGLE_BOOKING model does nothing for a PACKAGE line.
  3. Is the line’s skuType MEMBERSHIP or DEPOSIT? Those never resolve a business model, so they can never carry a fee.
  4. Is the fee still there? A previous PUT that omitted it from the fees array will have deleted it. GET .../business-models to confirm.
  5. Is the fee on the right service? Business models are per-service, so a fee on service A never applies to a line selling service B — even if both sell the same business model type.
  6. Did you expect tax on it? A taxable fee is taxed only when at least one of its governing lines is taxed at a positive rate. Read taxExemptReason on those lines to see why they carry no tax. The fee itself is still charged.
To confirm what actually happened on a given order, read data.summary.fees from GET .../orders/{orderId}/aggregate. Each entry names the businessModelId that levied it, so you can see exactly which model applied and what basis it used.

Where to go next

Regional pricing

How the order’s currency is resolved in the first place — the input a FLAT fee’s amount depends on.

The booking engine model

How orders, order items, and bookings fit together — the lines a business model’s fees govern.