> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gomarketbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Service fees

> How fees configured on a business model become discrete order-level charges, outside subtotal and outside tax.

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:

```json theme={null}
// POST .../business-models
{
  "type": "SINGLE_BOOKING",
  "paymentOptions": ["PAY_WHILE_BOOKING"],
  "fees": [
    {
      "feeId": "fee_booking",
      "name": { "en": "Booking fee" },
      "calculation": "FLAT",
      "amount": 2500,
      "taxable": false
    },
    {
      "feeId": "fee_admin",
      "name": { "en": "Admin fee" },
      "calculation": "PERCENT",
      "percentage": 5,
      "taxable": true
    }
  ]
}
```

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:

```
total = subtotal + feeTotal + taxTotal
```

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:

```json theme={null}
// GET .../orders/{orderId}/aggregate → data.summary (abridged)
{
  "subtotal": { "amount": 20000, "currency": "CAD" },
  "fees": [
    {
      "feeId": "fee_booking",
      "businessModelId": "bm_01k8p2q7f3g5h9j2k4m6n8p0q2",
      "name": { "en": "Booking fee" },
      "calculation": "FLAT",
      "basis": { "amount": 20000, "currency": "CAD" },
      "amount": { "amount": 2500, "currency": "CAD" },
      "tax": { "amount": 0, "currency": "CAD" },
      "taxable": false
    }
  ],
  "feeTotal": { "amount": 2500, "currency": "CAD" },
  "taxTotal": { "amount": 0, "currency": "CAD" },
  "total": { "amount": 22500, "currency": "CAD" }
}
```

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.

> [!NOTE]
>
> `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](https://docs.gomarketbox.com/resources/orders.md#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:

```json theme={null}
{ "feeId": "fee_booking", "calculation": "FLAT", "amount": 2500 }
```

`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](https://docs.gomarketbox.com/concepts/regional-pricing.md) 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](https://docs.gomarketbox.com/resources/orders.md#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](#which-business-model-to-put-the-fee-on)). 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`:

```json theme={null}
{
  "code": "SERVICE_NOT_SOLD_AS",
  "message": "Service srv_01kx16ej8wfp0b4v3x1q7m2d5c is not sold as a single booking; it has no active SINGLE_BOOKING rate",
  "statusCode": 422,
  "requestId": "2b7e9c41-6d3a-4f85-a0c2-8e1f5b3d7a96"
}
```

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**:

| Order line `skuType` | Business model that governs it |
| - | - |
| `SINGLE_SESSION` | `SINGLE_BOOKING` |
| `PACKAGE` | `PACKAGE`, falling back to `SCHEDULED_PACKAGE` |
| `SUBSCRIPTION` | `SCHEDULED_SUBSCRIPTION`, falling back to `FLEXIBLE_SUBSCRIPTION` |
| `MEMBERSHIP` | none — a fee can never apply |
| `DEPOSIT` | none — a fee can never apply |

"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`.

> [!WARNING]
>
> `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.

| You send | Result |
| - | - |
| `fees` omitted entirely | stored fees are left untouched |
| `fees: [feeA]` | the model now has **only** `feeA`; anything else is deleted |
| `fees: []` | all fees cleared |

> [!WARNING]
>
> 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:

| Rule | Detail |
| - | - |
| Maximum fees per business model | 20 |
| `feeId` | required, non-empty, and **unique within the business model** |
| `name` | required, localized — at minimum `{ "en": "..." }` |
| `calculation` | required, `FLAT` or `PERCENT` |
| `FLAT` | **requires** `amount`; must **not** set `percentage` |
| `PERCENT` | **requires** `percentage` (0-100); must **not** set `amount` |
| `amount` | integer, non-negative, in the currency's minor unit (`2500` = \$25.00) |
| `taxable` | optional boolean, defaults to `false` |

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:

```json theme={null}
// POST .../business-models/{businessModelId}/status
{ "active": true }
```

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](#no-matching-active-business-model-means-the-line-is-refused). 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

> [card] [Regional pricing](https://docs.gomarketbox.com/concepts/regional-pricing.md)
>
> How the order's currency is resolved in the first place — the input a FLAT fee's amount depends on.

> [card] [The booking engine model](https://docs.gomarketbox.com/concepts/booking-engine-model.md)
>
> How orders, order items, and bookings fit together — the lines a business model's fees govern.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.