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

# API conventions

> snake_case on the wire, path versioning, and predictable errors.

## Everything is snake\_case

Every Traddal API is **snake\_case on the wire, in both directions**. Request
bodies are accepted as snake\_case and responses come back as snake\_case —
including nested objects and arrays:

```json theme={null}
{
  "customer_id": 1,
  "external_id": "order-4412",
  "receiver": { "company_name": "Acme Inc", "country_code": "US" },
  "parcels": [{ "orders": [{ "items": [{ "unit_value": 12.5 }] }] }]
}
```

<Warning>
  Do not send camelCase keys (`customerId`, `countryCode`). They are ignored,
  not coerced.
</Warning>

Free-form maps — a catalogue item's `attributes`, a flow `config`, carrier
`credentials` — are passed through verbatim: their keys are your data and are
never re-cased.

## Item amounts are unit prices

An item's monetary `amount` / `unit_value` is the **per-unit** price, not the
line total. Line totals are always `unit_value × quantity`.

## Versioning

The Admin API is versioned in the path: `/admin/api/v1/…`. Breaking changes
ship as a sibling version (`v2`) — `v1` stays stable. Additive changes (new
optional fields, new endpoints) can appear in `v1` at any time; build clients
that tolerate unknown fields.

## Errors

Errors are JSON with a conventional shape and an appropriate HTTP status:

```json theme={null}
{
  "error": "Invalid or expired token"
}
```

Validation failures (`400`) include field-level details from the schema
validator. See [Status and error codes](/api-reference/errors).

## Timestamps, countries, currencies

* Timestamps are ISO 8601 UTC (`2026-07-19T14:30:00Z`); date-only fields are
  `YYYY-MM-DD`.
* Countries are ISO 3166-1 alpha-2 (`US`, `GB`, `DE`).
* Currencies are ISO 4217 (`USD`, `GBP`, `EUR`).