# Limits
Source: https://docs.zahlo.eu/limits

Limits apply equally in test mode and in live, unless a row says otherwise. When a request breaks a limit, the API answers with the error code shown, so your code can branch on `error.code`.

## Currencies and payment methods

| Payment method | Currencies |
|---|---|
| Cards (Visa, Mastercard and others) | EUR; CAD, CHF, DKK, GBP, JPY, PLN, RON and USD on request |
| Apple Pay, Google Pay | EUR |
| SEPA Direct Debit (subscriptions) | EUR only |

Currencies marked "on request" are enabled per account; contact support. `GET /payment-methods` returns the methods enabled for **your** account; use it instead of hard-coding this table. SEK and NOK are not supported.

## Amounts

| Limit | Value | Error code |
|---|---|---|
| Unit | integer `amountMinor` in the currency's minor unit (JPY has no minor unit) | `parameter_invalid` |
| Minimum per payment | €1.00 (¥164); in other currencies, about the equivalent of €1.00 | `amount_below_minimum` |
| Maximum per payment | €15,000.00; in other currencies, about the equivalent | `amount_above_maximum` |
| Zero-total one-time checkout | not allowed (a 100% coupon on a one-time payment is rejected) | `amount_below_minimum` |
| Line items per Checkout Session | 1-100 lines, quantity 1-999 | `parameter_invalid` |

Discounts are spread across the line items, so the customer sees discounted line amounts, never a negative line.

### Decimals per currency

`amountMinor` is always an integer in the currency's minor unit: `10.50 EUR` is `1050`, `1050 JPY` is `1050`.

| Currency | Decimals | `amountMinor` for the amount |
|---|---|---|
| CAD, CHF, DKK, EUR, GBP, PLN, RON, USD | 2 | cents: 10.50 is `1050` |
| JPY | 0 | whole yen: 1050 is `1050` |

The deprecated major-unit field `amount` follows the same rule and is never rounded. A value with more decimals than the currency allows is rejected, so `1.005` EUR or `12.5` JPY fails instead of being silently changed. JavaScript sums such as `0.1 + 0.2` send `0.30000000000000004` and are rejected too. Send `amountMinor` as an integer instead.

```json
{
  "error": {
    "code": "parameter_invalid",
    "message": "amount has more decimal places than EUR allows (2). Send amountMinor in cents instead.",
    "param": "amount"
  }
}
```

## Subscriptions

| Limit | Value |
|---|---|
| Billing interval | whole months, 1-36 (no daily or weekly intervals) |
| Amount per charge | 0.50 to 5,000.00 in the major unit (`amount_exceeds_subscription_limit`) |
| Failed card renewal | retried automatically up to 3 times, once a day |
| Plan or quantity change | upgrades apply now, prorated onto the next charge; downgrades and interval switches at the period end |
| `repeating` coupon | counts charged periods; a coupon below the payment minimum is rejected (`amount_below_minimum`) |
| 100%-off `forever` coupon | rejected |
| SEPA Direct Debit | EUR only; a debit is `processing` for several banking days and counts as active meanwhile; a later return starts the failed-payment process |

## Checkout Sessions

| Limit | Value |
|---|---|
| Expiry (`expiresInSeconds`) | 1,800-86,400 seconds (30 minutes to 24 hours); default 24 hours |
| What the customer sees | no countdown; an expired session shows "This checkout expired" with a link back to your site |
| Fulfilment | only on `checkout.session.completed` |

## Checkout domains

| Limit | Value | Error code |
|---|---|---|
| Return URLs | their host must be registered as a checkout domain | `checkout_domain_not_registered` |
| `localhost` and `http://` | Test mode only (`zk_test_` keys); live requires HTTPS | `domain_invalid` |
| New accounts | checkout may be unavailable for a short time while Zahlo enables it for your account; registering a checkout domain takes effect immediately | `checkout_domain_pending` |
| Apple Pay in embedded checkout | needs a real HTTPS host registered with `applePay: true`; a temporary tunnel host does not work | — |

## Webhooks

| Limit | Value |
|---|---|
| Signature tolerance | reject when `t` is more than 300 seconds from your clock |
| Response | any 2xx within 10 seconds counts as delivered |
| Retries after a failure | 1 min, 5 min, 30 min, 2 h, 5 h, 10 h, 24 h, 24 h (about 2.8 days) |
| Endpoint disabled | after 3 days with no successful delivery; you are emailed, and you can re-enable it and retry the failed deliveries |
| Secret rotation | the previous secret keeps signing for 24 hours |
| Event retention | 30 days (`GET /events`) |

## Requests

| Limit | Value | Error code |
|---|---|---|
| API requests | 600 per minute per IP address | `rate_limit_error` (429) |
| Payment-link checkouts | 10 per link per IP per hour, 300 per account per hour | `attempt_limit` (429) |
| `Idempotency-Key` | kept for 24 hours per account and route | `idempotency_key_reused`, `request_in_progress` (409) |
| List page size | `limit` 1-100, default 20 | `parameter_invalid` |
| Metadata | up to 50 keys; key up to 40 characters; value up to 500 characters | `parameter_invalid` |
| Refund outcome | a `pending` refund can take up to one business day to become `succeeded` or `failed` | — |
