Skip to main content
The Tilta API uses a consistent set of data type conventions across every endpoint. Understanding these conventions – particularly how monetary amounts and dates are represented – prevents the most common integration mistakes. Read this page carefully before you start sending requests.

​
Currency

Tilta represents currencies using ISO 4217 three-letter codes. Always pass the currency as an uppercase string.

​
Monetary amounts

All monetary amounts are expressed in minor units (the smallest denomination of the currency) as defined by ISO 4217. For euros and most other currencies, one major unit equals 100 minor units (cents). Always pair an amount field with its corresponding currency field in the same object:
The JSON above represents €100.00.
Do not pass decimal values for amounts. Sending 100.00 instead of 10000 will result in a drastically lower value being processed and may cause rejected orders or underpayments.

​
Dates and timestamps

Tilta uses Unix timestamps expressed in seconds (not milliseconds) for all date and time fields. Convert any ISO 8601 datetime to a Unix second-precision integer before including it in a request.
A quick reference for common conversions:
If you pass a timestamp in milliseconds by mistake, Tilta will interpret the date as being far in the future (~year 47,000). Always divide millisecond timestamps by 1000 before sending.

​
Character encoding

All request and response bodies must be encoded in UTF-8. Set your Content-Type header accordingly:

​
External IDs

External IDs are the identifiers you assign to buyers, merchants, orders, and other resources. Tilta stores and returns these IDs so that you can correlate Tilta records with records in your own systems without maintaining a separate mapping table. Rules for external IDs:
  • Must be unique per resource type in your Tilta account (e.g., every buyer must have a distinct external buyer ID).
  • Should match the primary key or stable identifier you already use in your system (e.g., your database row ID or UUID).
  • Are treated as opaque strings by Tilta – you may use any alphanumeric characters, hyphens, or underscores.
  • Cannot be changed after the resource is created.
Use a consistent, predictable format for external IDs (for example, buyer-{uuid} or order-{timestamp}-{sequence}) so that they remain human-readable in the Platform Portal and in Tilta’s support tooling.