Changelog & migration to 3.1

Add MCP server to your AI tool

Allow AI tools and LLMs to interact with the API documentation portal through MCP.

MCP server URL

https://bump.sh/zim/doc/esim-api/mcp

Standard setup for AI tools providing an mcp.json file

mcp.json
{
  "eSIM API MCP server": {
    "url": "https://bump.sh/zim/doc/esim-api/mcp"
  }
}

Close

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).