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

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

Safe rollout

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.
Send canonical fields in sandbox and keep the legacy pair during validation.
If both forms are sent, make their values identical; conflicts return a coded 400.
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 for request and response schemas.