> ## 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.
# Calculate fees
> Calculate the exact buyer and merchant fees for a proposed invoice. Use this before capturing financing to show transparent fee amounts at checkout.
Before creating an invoice, you can use this endpoint to calculate the precise service fees that would apply to a proposed financing transaction. The fee calculation takes into account the buyer's credit facility terms, the requested payment term, the invoice amount, and your platform's configured fee structure. Calling this endpoint at checkout lets you display exact fee amounts to the buyer before they confirm their payment term selection – improving transparency and reducing disputes.
Call this endpoint for each payment term option you display to the buyer at checkout. Showing a breakdown of fees per term
(e.g., "30 days – €5.95 fee / 60 days – €9.50 fee") helps buyers make informed decisions and reduces post-purchase confusion.
Fee calculations are non-binding estimates based on current configuration. The actual fees applied when you create the invoice
may differ if the buyer's credit facility terms or your platform's fee configuration changes between the calculate-fees call
and invoice creation.
## OpenAPI
````yaml POST /v1/invoices/calculate_fees
openapi: 3.0.0
info:
version: 0.0.1
title: Tilta API
description: Tilta API documentation
servers:
- url: https://api.tilta.io
description: Tilta Production API
- url: https://api.tilta-sandbox.io
description: Tilta Sandbox API
security: []
paths:
/v1/invoices/calculate_fees:
post:
tags:
- Invoices
summary: Calculate fees for an invoice
description: |-
Calculate service fees for an invoice.
The fees are calculated based on the request values, considering the buyer's facility and platform configuration.
requestBody:
content:
application/json:
schema:
type: object
properties:
amount:
type: number
description: Total amount of the invoice in cents.
due_at:
type: number
description: Timestamp indicating when the invoice should be paid.
example: 1582896122
paid_out_at:
type: number
nullable: true
description: Timestamp indicating when the invoice is actually paid.
example: 1582896122
buyer_external_id:
type: string
maxLength: 100
pattern: ^[a-zA-Z0-9-_]+$
description: Unique identifier of a related buyer.
merchant_external_id:
type: string
maxLength: 100
pattern: ^[a-zA-Z0-9-_]+$
description: >-
Unique identifier of a merchant. Optional only for
Single-merchant platforms.
required:
- amount
- due_at
- buyer_external_id
responses:
'200':
description: ''
content:
application/json:
schema:
type: object
properties:
fees:
type: object
properties:
financing:
type: object
properties:
merchant_fee:
type: object
properties:
base_rate:
type: object
properties:
value:
type: number
nullable: true
description: >-
Exact value when known. Null when no risk
band is available to resolve it.
min:
type: number
description: >-
Lower bound of the range across configured
risk bands.
max:
type: number
description: >-
Upper bound of the range across configured
risk bands.
required:
- value
- min
- max
description: >-
Numeric value with min/max range. When the
value depends on the buyer risk band and the
band is not yet known, `value` is null and the
range still indicates the bounds.
daily_rate:
type: object
properties:
value:
type: number
nullable: true
description: >-
Exact value when known. Null when no risk
band is available to resolve it.
min:
type: number
description: >-
Lower bound of the range across configured
risk bands.
max:
type: number
description: >-
Upper bound of the range across configured
risk bands.
required:
- value
- min
- max
description: >-
Numeric value with min/max range. When the
value depends on the buyer risk band and the
band is not yet known, `value` is null and the
range still indicates the bounds.
total_rate:
type: object
properties:
value:
type: number
nullable: true
description: >-
Exact value when known. Null when no risk
band is available to resolve it.
min:
type: number
description: >-
Lower bound of the range across configured
risk bands.
max:
type: number
description: >-
Upper bound of the range across configured
risk bands.
required:
- value
- min
- max
description: >-
Numeric value with min/max range. When the
value depends on the buyer risk band and the
band is not yet known, `value` is null and the
range still indicates the bounds.
tax_rate:
type: object
properties:
value:
type: number
nullable: true
description: >-
Exact value when known. Null when no risk
band is available to resolve it.
min:
type: number
description: >-
Lower bound of the range across configured
risk bands.
max:
type: number
description: >-
Upper bound of the range across configured
risk bands.
required:
- value
- min
- max
description: >-
Numeric value with min/max range. When the
value depends on the buyer risk band and the
band is not yet known, `value` is null and the
range still indicates the bounds.
amount:
type: object
properties:
net:
type: object
properties:
value:
type: number
nullable: true
description: >-
Exact value when known. Null when no
risk band is available to resolve it.
min:
type: number
description: >-
Lower bound of the range across
configured risk bands.
max:
type: number
description: >-
Upper bound of the range across
configured risk bands.
required:
- value
- min
- max
description: >-
Numeric value with min/max range. When the
value depends on the buyer risk band and
the band is not yet known, `value` is null
and the range still indicates the bounds.
tax:
type: object
properties:
value:
type: number
nullable: true
description: >-
Exact value when known. Null when no
risk band is available to resolve it.
min:
type: number
description: >-
Lower bound of the range across
configured risk bands.
max:
type: number
description: >-
Upper bound of the range across
configured risk bands.
required:
- value
- min
- max
description: >-
Numeric value with min/max range. When the
value depends on the buyer risk band and
the band is not yet known, `value` is null
and the range still indicates the bounds.
gross:
type: object
properties:
value:
type: number
nullable: true
description: >-
Exact value when known. Null when no
risk band is available to resolve it.
min:
type: number
description: >-
Lower bound of the range across
configured risk bands.
max:
type: number
description: >-
Upper bound of the range across
configured risk bands.
required:
- value
- min
- max
description: >-
Numeric value with min/max range. When the
value depends on the buyer risk band and
the band is not yet known, `value` is null
and the range still indicates the bounds.
required:
- net
- tax
- gross
required:
- base_rate
- daily_rate
- total_rate
- tax_rate
- amount
required:
- merchant_fee
insurance:
type: object
properties:
merchant_fee:
type: object
properties:
base_rate:
type: object
properties:
value:
type: number
nullable: true
description: >-
Exact value when known. Null when no risk
band is available to resolve it.
min:
type: number
description: >-
Lower bound of the range across configured
risk bands.
max:
type: number
description: >-
Upper bound of the range across configured
risk bands.
required:
- value
- min
- max
description: >-
Numeric value with min/max range. When the
value depends on the buyer risk band and the
band is not yet known, `value` is null and the
range still indicates the bounds.
daily_rate:
type: object
properties:
value:
type: number
nullable: true
description: >-
Exact value when known. Null when no risk
band is available to resolve it.
min:
type: number
description: >-
Lower bound of the range across configured
risk bands.
max:
type: number
description: >-
Upper bound of the range across configured
risk bands.
required:
- value
- min
- max
description: >-
Numeric value with min/max range. When the
value depends on the buyer risk band and the
band is not yet known, `value` is null and the
range still indicates the bounds.
total_rate:
type: object
properties:
value:
type: number
nullable: true
description: >-
Exact value when known. Null when no risk
band is available to resolve it.
min:
type: number
description: >-
Lower bound of the range across configured
risk bands.
max:
type: number
description: >-
Upper bound of the range across configured
risk bands.
required:
- value
- min
- max
description: >-
Numeric value with min/max range. When the
value depends on the buyer risk band and the
band is not yet known, `value` is null and the
range still indicates the bounds.
tax_rate:
type: object
properties:
value:
type: number
nullable: true
description: >-
Exact value when known. Null when no risk
band is available to resolve it.
min:
type: number
description: >-
Lower bound of the range across configured
risk bands.
max:
type: number
description: >-
Upper bound of the range across configured
risk bands.
required:
- value
- min
- max
description: >-
Numeric value with min/max range. When the
value depends on the buyer risk band and the
band is not yet known, `value` is null and the
range still indicates the bounds.
amount:
type: object
properties:
net:
type: object
properties:
value:
type: number
nullable: true
description: >-
Exact value when known. Null when no
risk band is available to resolve it.
min:
type: number
description: >-
Lower bound of the range across
configured risk bands.
max:
type: number
description: >-
Upper bound of the range across
configured risk bands.
required:
- value
- min
- max
description: >-
Numeric value with min/max range. When the
value depends on the buyer risk band and
the band is not yet known, `value` is null
and the range still indicates the bounds.
tax:
type: object
properties:
value:
type: number
nullable: true
description: >-
Exact value when known. Null when no
risk band is available to resolve it.
min:
type: number
description: >-
Lower bound of the range across
configured risk bands.
max:
type: number
description: >-
Upper bound of the range across
configured risk bands.
required:
- value
- min
- max
description: >-
Numeric value with min/max range. When the
value depends on the buyer risk band and
the band is not yet known, `value` is null
and the range still indicates the bounds.
gross:
type: object
properties:
value:
type: number
nullable: true
description: >-
Exact value when known. Null when no
risk band is available to resolve it.
min:
type: number
description: >-
Lower bound of the range across
configured risk bands.
max:
type: number
description: >-
Upper bound of the range across
configured risk bands.
required:
- value
- min
- max
description: >-
Numeric value with min/max range. When the
value depends on the buyer risk band and
the band is not yet known, `value` is null
and the range still indicates the bounds.
required:
- net
- tax
- gross
required:
- base_rate
- daily_rate
- total_rate
- tax_rate
- amount
required:
- merchant_fee
collection:
type: object
properties:
merchant_fee:
type: object
properties:
base_rate:
type: object
properties:
value:
type: number
nullable: true
description: >-
Exact value when known. Null when no risk
band is available to resolve it.
min:
type: number
description: >-
Lower bound of the range across configured
risk bands.
max:
type: number
description: >-
Upper bound of the range across configured
risk bands.
required:
- value
- min
- max
description: >-
Numeric value with min/max range. When the
value depends on the buyer risk band and the
band is not yet known, `value` is null and the
range still indicates the bounds.
daily_rate:
type: object
properties:
value:
type: number
nullable: true
description: >-
Exact value when known. Null when no risk
band is available to resolve it.
min:
type: number
description: >-
Lower bound of the range across configured
risk bands.
max:
type: number
description: >-
Upper bound of the range across configured
risk bands.
required:
- value
- min
- max
description: >-
Numeric value with min/max range. When the
value depends on the buyer risk band and the
band is not yet known, `value` is null and the
range still indicates the bounds.
total_rate:
type: object
properties:
value:
type: number
nullable: true
description: >-
Exact value when known. Null when no risk
band is available to resolve it.
min:
type: number
description: >-
Lower bound of the range across configured
risk bands.
max:
type: number
description: >-
Upper bound of the range across configured
risk bands.
required:
- value
- min
- max
description: >-
Numeric value with min/max range. When the
value depends on the buyer risk band and the
band is not yet known, `value` is null and the
range still indicates the bounds.
tax_rate:
type: object
properties:
value:
type: number
nullable: true
description: >-
Exact value when known. Null when no risk
band is available to resolve it.
min:
type: number
description: >-
Lower bound of the range across configured
risk bands.
max:
type: number
description: >-
Upper bound of the range across configured
risk bands.
required:
- value
- min
- max
description: >-
Numeric value with min/max range. When the
value depends on the buyer risk band and the
band is not yet known, `value` is null and the
range still indicates the bounds.
amount:
type: object
properties:
net:
type: object
properties:
value:
type: number
nullable: true
description: >-
Exact value when known. Null when no
risk band is available to resolve it.
min:
type: number
description: >-
Lower bound of the range across
configured risk bands.
max:
type: number
description: >-
Upper bound of the range across
configured risk bands.
required:
- value
- min
- max
description: >-
Numeric value with min/max range. When the
value depends on the buyer risk band and
the band is not yet known, `value` is null
and the range still indicates the bounds.
tax:
type: object
properties:
value:
type: number
nullable: true
description: >-
Exact value when known. Null when no
risk band is available to resolve it.
min:
type: number
description: >-
Lower bound of the range across
configured risk bands.
max:
type: number
description: >-
Upper bound of the range across
configured risk bands.
required:
- value
- min
- max
description: >-
Numeric value with min/max range. When the
value depends on the buyer risk band and
the band is not yet known, `value` is null
and the range still indicates the bounds.
gross:
type: object
properties:
value:
type: number
nullable: true
description: >-
Exact value when known. Null when no
risk band is available to resolve it.
min:
type: number
description: >-
Lower bound of the range across
configured risk bands.
max:
type: number
description: >-
Upper bound of the range across
configured risk bands.
required:
- value
- min
- max
description: >-
Numeric value with min/max range. When the
value depends on the buyer risk band and
the band is not yet known, `value` is null
and the range still indicates the bounds.
required:
- net
- tax
- gross
required:
- base_rate
- daily_rate
- total_rate
- tax_rate
- amount
required:
- merchant_fee
required:
- financing
- insurance
- collection
amount:
type: number
description: Total amount of the invoice in cents.
due_at:
type: number
description: Timestamp indicating when the invoice should be paid.
example: 1582896122
paid_out_at:
type: number
nullable: true
description: Timestamp indicating when the invoice is actually paid.
example: 1582896122
buyer_external_id:
type: string
maxLength: 100
pattern: ^[a-zA-Z0-9-_]+$
description: Unique identifier of a related buyer.
merchant_external_id:
type: string
maxLength: 100
pattern: ^[a-zA-Z0-9-_]+$
description: Unique identifier of a related merchant.
required:
- fees
- amount
- due_at
- buyer_external_id
- merchant_external_id
'400':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/badRequestSchema'
'401':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/unauthorizedRequestSchema'
security:
- bearerAuth: []
components:
schemas:
badRequestSchema:
type: object
properties:
code:
type: string
description: Error code
example: BAD_REQUEST
error:
type: string
description: Error message for debugging purposes
example: Request validation failed. 1 issue found.
issues:
type: array
items:
type: object
properties:
code:
type: string
description: Issue code
example: INVALID_TYPE
path:
type: string
description: Issue path starting with body, params, querystring, or headers
example: body.registered_at
message:
type: string
description: Issue message for debugging purposes
example: Invalid type
required:
- code
- path
- message
description: List of issues
example:
- code: INVALID_TYPE
path: body.registered_at
message: Invalid type
required:
- code
- error
- issues
description: Bad Request, see error message for details.
example:
code: BAD_REQUEST
error: Request validation failed. 1 issue found.
issues:
- code: INVALID_TYPE
path: body.registered_at
message: Invalid type
unauthorizedRequestSchema:
type: object
properties:
error:
type: string
description: Error details.
example: Unauthorized
code:
type: string
description: Error code.
example: UNAUTHORIZED
required:
- error
- code
description: Unauthorized Request.
example:
error: Unauthorized
code: UNAUTHORIZED
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: Your Tilta API key, sent as `Bearer `.
````