eSIM

Plan names (no plan IDs): Catalog.

Purchase travel / international data eSIMs through the Breeze eSIM API. Each product has a stable plan_id and an NGN checkout price. Delivery is an install QR, ICCID, and SM-DP+ / LPA string — not a local SIM swap.

Always fetch the catalog or quote immediately before purchase. Wallet debit is the order amount (purchase-time NGN quote). Catalog ngn_price and quote ngn_amount use the same pricing basis as purchase for the credential environment you are on, so the three should match when called back-to-back.

Response shapes

Operation	JSON shape
Catalog, quote, plan	`status`, `code`, `message`, `data`
Purchase & order status	`status`, `response_code`, `response_message`, `data`

On purchase and order status, status is the outcome word (success, failed, pending) and response_code is 00, 01, or 02. Create and poll use the same envelope.

Catalog API

List catalog


GET /v1/esim/catalog

Query	Description
`country`	ISO-2 destination, e.g. `GB`, `US`, `NG`
`region`	Region name substring, e.g. `Africa`, `Global`
`search`	Filter by title, country, region, or plan id

Each item includes plan_id, title, country, region, data_gb, duration_days, currency_code, and ngn_price when FX is configured.

Get NGN quote


GET /v1/esim/plans/{plan_id}/quote

Get one plan


GET /v1/esim/plans/{plan_id}

Purchase


POST /v1/esim/orders


curl -X POST "https://api.subthingy.io/v1/esim/orders" \
  -H "Content-Type: application/json" \
  -H "X-Merchant-Key: mk_your_key_id" \
  -H "X-Merchant-Secret: your_issued_secret" \
  -d '{
    "request_id": "esim-20260907-001",
    "plan_id": "ESIM-GB-15D-2GB-NOROAM"
  }'

Field	Required	Description
`request_id`	Yes	Your idempotency key (unique per merchant, max 40 characters)
`plan_id`	Yes	Catalog `plan_id`

Fulfillment is asynchronous. A 02 pending response is normal; poll GET /v1/esim/orders/{request_id} until 00 or 01. Status poll checks the provider, so you do not need to wait for a webhook. Do not treat pending as success. Success includes install fields only when the provider has issued an ICCID.

Order status


GET /v1/esim/orders/{request_id}

On success, data includes iccid, activation_code, smdp_address, lpa (LPA:1$…), and redemption_instructions.

QR code


GET /v1/esim/orders/{request_id}/qrcode

Returns image/png after the order is successful. 404 while pending.

Breeze Gift

A Breeze Gift card can also redeem into eSIM (product=ESIM, plan = catalog plan_id). Recipients pick a plan in redeem UI or WhatsApp. Install fields (iccid, lpa) are returned on a successful redeem.