Changelog

This page tracks notable changes to the Octopus Cards API surface. Non-breaking additions are merged silently; anything that changes a contract you may depend on shows up here.

For Octopus Cards's compatibility commitments and how breaking changes are communicated, see Our API promise.

2026-05

eSIMs API introduced

The eSIM vertical ships as a complete surface, end-to-end parity with vouchers and topups:

GET /api/v1/esim/products?country_code=… — browse plans by destination country (ISO 3166-1 alpha-3, e.g. JPN).
GET /api/v1/esim/products/:id/variants — list plans for a product (data allowance, validity, price).
POST /api/v1/esim/charges — quote a variant's final price; cross-currency-aware (returns net_amount, handling_fee_amount, forex_rate, conversion_fee when wallet currency differs from variant currency).
POST /api/v1/esim/orders — place an order. 60-second hybrid: response is always 200 OK; body status is DELIVERED (with activation code inline) if fulfilment lands in time, PENDING otherwise.
GET /api/v1/esim/orders and GET /api/v1/esim/orders/:id — list and poll. The activation_status field surfaces install / activate / expired transitions for life-of-plan tracking.
PATCH /api/v1/esim/orders/:id/notification-email — attach an email address for terminal-transition receipts.
client_reference is the optional dedup + lookup key on create (same model as voucher and topup); a duplicate returns 400 "Duplicate client_reference". ?client_reference=… on the list endpoint fetches the matching order.
status is PENDING / DELIVERED / FAILED / CANCELLED; clients branch on that plus status_text (no sub_status on the wire).

See the eSIM flow guide for the end-to-end pattern.

Topups & vouchers — wallet support on order creation

wallet_id is now accepted on POST /api/v1/topups/orders and POST /api/v1/orders. When the wallet currency differs from the variant currency, the charges endpoint returns FX fields (net_amount, handling_fee_amount, forex_rate, conversion_fee).
See Cross-currency orders for the pattern.

Failure-code taxonomy

Implementation-specific failure codes are no longer surfaced. Customer-facing surfaces emit a fixed enum (INVALID_RECIPIENT, OPERATOR_UNAVAILABLE, PRODUCT_OUT_OF_STOCK, etc.) plus is_user_fixable.
Transient connectivity errors no longer reach FAILED. Orders stay PENDING and Octopus Cards retries; see Handling errors.

2026-04

Docs IA — vertical-based reference structure

/docs/reference/products, /docs/reference/orders, /docs/reference/webhooks/events moved under /docs/reference/vouchers/*. Redirects in place; old URLs continue to resolve.
New /docs/reference/topups/* and /docs/reference/esim/* verticals.