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:
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: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:
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, ... }.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
Settingtaxable: 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’sskuType, 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:
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’sskuType, 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.
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.
Validation rules
A malformed array is rejected with a400 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 with422 SERVICE_NOT_SOLD_AS. Activate with:
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 with422 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:
- 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 withGET .../business-models. - Does the model’s
typegovern theskuTypeyou are selling? See the mapping table above. A fee on aSINGLE_BOOKINGmodel does nothing for aPACKAGEline. - Is the line’s
skuTypeMEMBERSHIPorDEPOSIT? Those never resolve a business model, so they can never carry a fee. - Is the fee still there? A previous
PUTthat omitted it from thefeesarray will have deleted it.GET .../business-modelsto confirm. - 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.
- Did you expect tax on it? A
taxablefee is taxed only when at least one of its governing lines is taxed at a positive rate. ReadtaxExemptReasonon those lines to see why they carry no tax. The fee itself is still charged.
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.