> For the complete documentation index, see [llms.txt](https://bump.sh/zim/doc/esim-api/llms.txt)

# Changelog & migration to 3.1

**Breaking changes**


  * `GET /subscriptions` is now **paginated**. The response is no longer
    a bare array but a `{ data, meta }` envelope (see `PaginatedSubscriptions`).
    Use the `page` (default `1`) and `limit` (default `10`, max `20`)
    query parameters and iterate while `meta.hasNext` is `true`.
  * `GET /plans` without filters (or with `page` / `limit`) returns a
    paginated `{ data, meta }` envelope.
  * Path parameters are now documented as real path segments
    (`/esims/{esimID}` instead of `/esims/:esimID` with a query
    parameter). The URLs called are unchanged.
  * Field names: `Esim.matchingId` (previously documented as
    `matchingID`) and `Price.minorUnitsExponent` (previously documented
    as `minorExponentUnits`).
  * All `POST` endpoints return `201 Created` (previously documented as `200`).
  * Unknown request properties (body or query) are rejected with `400`.
  * New Subscription status `CANCEL_PENDING`: cancellation is now
    asynchronous (see `POST /subscriptions/{subscriptionID}/cancel`).
  * Cancelling an Order that was `PROCESSING` or `FAILED` moves it to
    the new status `REFUNDED` (not `CANCELLED`). `REFUNDED` Orders can
    no longer be cancelled, and cancelling an `IN_BASKET` Order removes it.
  * `GET /plans` accepts at most `limit=1000`.
  * `POST /plans/search` without `payload` is rejected with `400`.
  * Orders are paid the way your Account's billing is set up, not as
    the request chooses: `POST /v2/orders` no longer takes a payment
    method (see *Create an Order*). An Account that is not set up to
    order through the API is refused with `PAYMENT_METHOD_NOT_ALLOWED`.
  * An Advance Pay wallet that was never funded is refused with
    `INSUFFICIENT_BALANCE` (previously `Wallet not found for customer`),
    and a refused order no longer leaves a `PENDING` Order behind.


**Deprecations** — deprecated endpoints keep working until their sunset date and return the headers `Deprecation: true`, `Sunset: Thu, 31 Dec 2026 23:59:59 GMT` and `Link: <successor>; rel="successor-version"`.


  * `POST /orders/with-wallet` → `POST /v2/orders`
  * `DELETE /subscriptions/{subscriptionID}` → `POST /subscriptions/{subscriptionID}/cancel`
  * `GET /plans/{iso3}/local` → `GET /plans?destination={iso3}&scope=LOCAL`
  * `GET /plans/{iso3}/local/regular` → `GET /plans?destination={iso3}&scope=LOCAL&category=REGULAR`
  * `GET /plans/{iso3}/local/unlimited` → `GET /plans?destination={iso3}&scope=LOCAL&category=UNLIMITED`
  * `GET /destinations/supported_destinations` is kept as an alias of
    `GET /destinations/supported-destinations` (not deprecated).


**New**


  * `POST /v2/orders` — unified order creation, one-off and top-up, paid per your Account's billing.
  * `POST /plans/search/domestic` — UK domestic plans.
  * `GET /plans`, `GET /plans/details/{planID}`.
  * `GET /esims/{esimID}/config`, `GET /esims/{esimID}/qrcode-url`.
  * `GET /subscriptions/{subscriptionID}/compatible-plans` (top-up plan discovery).


