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.breezeinnovations.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 is enough — you do not need to wait for a webhook. Do not treat pending as success. Success includes install fields only when an ICCID has been issued.

On test credentials, purchase is simulated after catalog validation and usually returns 00 immediately with test install fields. See Environments — Test eSIM.

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.