# Migrate to ISO bill data

Adopt exact ISO 4217 money values and calendar-only due dates while keeping legacy integrations working during the compatibility window.

> **Note**
> Legacy `amount_due`, `currency`, and `due_date` fields remain available. New integrations should use `total_amount` and `due_date_iso`.

## Canonical fields

`total_amount.value` is a decimal string with the exact exponent required by `total_amount.currency`. `due_date_iso` is a real calendar date in `YYYY-MM-DD` format and has no timezone conversion.

### Canonical bill input

**JSON**

```json
{
  "client_user_id": "user_abc123",
  "payee_name": "Example Utility",
  "total_amount": {
    "value": "123.45",
    "currency": "USD"
  },
  "due_date_iso": "2026-09-30"
}
```

## Safe rollout

1. Update response parsing to prefer canonical fields and fall back to legacy fields; canonical siblings can be absent for malformed historical records or during rollout.
2. Send canonical fields in sandbox and keep the legacy pair during validation.
3. If both forms are sent, make their values identical; conflicts return a coded 400.
4. Stop sending legacy fields after every supported flow is verified; removal from the API will only happen in a future major version after the announced compatibility window.

For USD use two decimals, for JPY use no decimals, and for BHD use three decimals. Values are never silently rounded. See the [Bills API reference](/docs/api/bills) for request and response schemas.