> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tilta.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Fee configuration
> Configure buyer and merchant fees on Tilta – flat and risk-based modes, worked calculation examples with VAT, and the calculate-fees endpoint.
Tilta gives you full flexibility to charge fees on financed transactions. You can pass fees to the buyer, deduct fees from the merchant payout, or do both – and you can vary fees by payment term length or by the buyer's credit risk tier. This guide explains how each fee type works, the two configuration modes available, and how to calculate fees programmatically before capturing an invoice.
## Buyer fees vs. merchant fees
Tilta supports two distinct fee directions. Each operates independently, and you can configure one, both, or neither depending on your business model.
A premium charged to the buyer on top of the gross invoice value. It increases the total amount the buyer must repay. Useful when you want buyers to bear the cost of deferred payment terms.
A discount deducted from the gross invoice value before paying out to the merchant. It reduces the net amount the merchant receives. Useful when you want sellers to fund the cost of offering payment terms.
Both fee types are expressed as a **percentage of the gross invoice value** (i.e., the invoice amount including VAT). All fees are themselves subject to VAT, which Tilta calculates and handles on your behalf.
***
## Fee configuration modes
### Flat fee
In Flat Fee mode, you define a single fee percentage for each payment term, applied uniformly to all buyers regardless of their credit profile.
| Payment term | Merchant fee | Buyer fee |
| --------------------- | ------------ | --------- |
| 30 days (`DEFER_30D`) | 0% | 0% |
| 60 days (`DEFER_60D`) | 0.5% | 1.5% |
| 90 days (`DEFER_90D`) | 0.5% | 3.0% |
Flat fees are the simplest configuration to operate and communicate to your merchants and buyers. Use them when you want a consistent, predictable fee structure across your platform.
### Risk-based fee
In Risk-Based Fee mode, fees vary by the buyer's **risk tier** – assigned by Tilta's underwriting engine based on the buyer's creditworthiness. Higher-risk buyers pay higher buyer fees, while merchant fees remain consistent across tiers.
Risk tiers range from `A1` (lowest risk) to `B2` (higher risk). The example below shows how fees scale across tiers for 30-, 60-, and 90-day terms:
| Risk tier | Merchant fee (30/60/90 days) | Buyer fee (30/60/90 days) |
| ---------------- | ---------------------------- | ------------------------- |
| A1 (lowest risk) | 0% / 0.5% / 0.5% | 0% / 0.5% / 1.0% |
| A2 | 0% / 0.5% / 0.5% | 0% / 1.0% / 2.0% |
| B1 | 0% / 0.5% / 0.5% | 0% / 1.5% / 3.0% |
| B2 (higher risk) | 0% / 0.5% / 0.5% | 0% / 2.0% / 4.0% |
Risk-based fees let you price risk accurately: lower-risk buyers receive more competitive terms, which can increase conversion among your best buyers, while higher-risk buyers pay a premium that reflects the additional credit exposure.
Note that merchant fees are identical across all risk tiers in the example above. This is a common configuration – merchants care about predictable payout amounts and are typically not asked to absorb buyer credit risk directly.
***
## Fee calculation: Worked examples
### Buyer fee calculation
Consider an order with the following parameters:
* Order net value: **€1,000.00**
* VAT rate: **19%**
* Gross invoice value: €1,000.00 × 1.19 = **€1,190.00**
* Buyer Fee rate: **2%** (applied to gross)
**Step 1: Calculate the net fee**
> €1,190.00 × 2% = **€23.80**
**Step 2: Calculate VAT on the fee**
> €23.80 × 19% = **€4.52**
**Step 3: Calculate the total buyer repayment obligation**
> €1,190.00 (invoice gross) + €23.80 (net fee) + €4.52 (fee VAT) = **€1,218.32**
The buyer repays **€1,218.32** in total on the due date.
***
### Merchant fee calculation
Using the same base invoice:
* Gross invoice value: **€1,190.00**
* Merchant Fee rate: **3%** (applied to gross)
**Step 1: Calculate the net fee**
> €1,190.00 × 3% = **€35.70**
**Step 2: Calculate VAT on the fee**
> €35.70 × 19% = **€6.78**
**Step 3: Calculate the merchant payout**
> €1,190.00 − €35.70 (net fee) − €6.78 (fee VAT) = **€1,147.52**
The merchant receives **€1,147.52** in their payout.
VAT on fees is handled by Tilta in accordance with applicable tax regulations. The VAT rates shown above use 19% (Germany) for illustration. The actual rate applied to the fee will match the VAT rate applicable to the invoice's jurisdiction.
***
## Calculating fees before invoice capture
Use the `POST /v1/invoices/calculate_fees` endpoint to retrieve an exact fee breakdown before creating an invoice. This is useful for displaying the total repayment amount to the buyer at checkout or the net payout amount in merchant dashboards.
```http theme={null}
POST /v1/invoices/calculate_fees
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
```
```json theme={null}
{
"amount": {
"net": 100000,
"gross": 119000,
"tax": 19000,
"currency": "EUR"
},
"due_at": 1725148800,
"buyer_external_id": "buyer_de_001",
"merchant_external_id": "merchant_abc123"
}
```
`amount`, `due_at`, and `buyer_external_id` are required. The response echoes the request and adds a `fees` object broken down by service type – `financing`, `insurance`, and `collection`:
```json theme={null}
{
"amount": {
"net": 100000,
"gross": 119000,
"tax": 19000,
"currency": "EUR"
},
"due_at": 1725148800,
"buyer_external_id": "buyer_de_001",
"merchant_external_id": "merchant_abc123",
"fees": {
"financing": {
"merchant_fee": {
"base_rate": { "value": 0.005, "min": 0.005, "max": 0.012 },
"daily_rate": { "value": 0.0002, "min": 0.0002, "max": 0.0005 },
"total_rate": { "value": 0.017, "min": 0.017, "max": 0.042 },
"tax_rate": { "value": 0.19, "min": 0.19, "max": 0.19 },
"amount": { "net": 1700, "tax": 323, "gross": 2023 }
}
}
}
}
```
Each rate is an object rather than a bare number. When the buyer's risk band is not yet known, `value` is `null` and `min` and `max` still bound the possible outcome across your configured risk bands – so a checkout UI can show a range before underwriting completes.
All monetary values in the API are expressed in the smallest currency unit. A `gross` of `2023` represents €20.23.
Use this endpoint at checkout to show the buyer what they will owe, and on merchant dashboards to show what they will receive after fees.
***
## Configuring your fee structure
Fee configuration is set up during your platform onboarding with your Tilta integration manager. To update your fee structure after go-live – for example, to add new payment terms or adjust rates for specific risk tiers – contact your Tilta integration manager directly.
Fee configuration changes take effect on new invoices created after the change is applied. Existing invoices are not retroactively affected. Plan fee changes carefully and communicate them to your merchants and buyers in advance.