> ## 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.

# Data types

> Reference for Tilta API data types including ISO 4217 currency codes, minor-unit amounts, Unix timestamps, UTF-8 encoding, and external IDs.

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](https://www.iso.org/iso-4217-currency-codes.html) three-letter codes. Always pass the currency as an uppercase string.

```json theme={null}
"currency": "EUR"
"currency": "GBP"
"currency": "PLN"
```

## 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).

| Example value | Currency | Minor units | Meaning   |
| ------------- | -------- | ----------- | --------- |
| `1000`        | `EUR`    | cents       | €10.00    |
| `5`           | `USD`    | cents       | \$0.05    |
| `250000`      | `GBP`    | pence       | £2,500.00 |

Always pair an `amount` field with its corresponding `currency` field in the same object:

```json theme={null}
{
  "amount": 10000,
  "currency": "EUR"
}
```

The JSON above represents **€100.00**.

<Warning>
  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.
</Warning>

## 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.

```
ISO 8601:  2015-08-10T07:45:00.098Z
Unix:      1439192700
```

A quick reference for common conversions:

```javascript theme={null}
// JavaScript – convert ISO 8601 to Unix seconds
const unixSeconds = Math.floor(new Date("2015-08-10T07:45:00.098Z").getTime() / 1000);
// → 1439192700
```

```python theme={null}
# Python – convert ISO 8601 to Unix seconds
from datetime import datetime, timezone
dt = datetime(2015, 8, 10, 7, 45, 0, tzinfo=timezone.utc)
unix_seconds = int(dt.timestamp())
# → 1439192700
```

<Note>
  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.
</Note>

## Character encoding

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

```
Content-Type: application/json; charset=utf-8
```

## 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.

```json theme={null}
{
  "external_id": "buyer-00421",
  "legal_name": "Acme GmbH"
}
```

<Tip>
  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.
</Tip>