Orders

Issues a new eSIM for the given plan_id. Always send a unique Idempotency-Key so retries don't double-charge.

Request body

• plan_id (required) — id from the catalog.
• customer_reference (optional, ≤120 chars) — your internal reference, echoed back.

curl -X POST https://portal.esimerge.com/api/public/v1/orders \
  -H 'Authorization: Bearer esm_sk_test_...' \
  -H 'Idempotency-Key: 8f0b1f9e-1f70-4a3e-9b3a-2c2bdcf7a1d2' \
  -H 'Content-Type: application/json' \
  -d '{"plan_id":"esm_plan_sa_5gb_30d","customer_reference":"cust_42"}'

Example response (201)

{
  "id": "esm_order_AbCdEf...",
  "object": "order",
  "order_number": "TJW-2026-000123",
  "status": "issued",
  "plan": {
    "id": "esm_plan_sa_5gb_30d",
    "name": "Saudi Arabia 5GB / 30 days",
    "scope": "country",
    "country_code": "SA",
    "data_mb": 5120,
    "validity_days": 30
  },
  "quantity": 1,
  "amount_sar": 35.00,
  "amount_usd": 9.33,
  "customer_reference": "cust_42",
  "created_at": "2026-05-26T12:00:00Z",
  "activated_at": null,
  "esim": {
    "id": "esm_esim_AbCdEf...",
    "iccid": "8988000000000000000",
    "qr_code": "LPA:1$smdp.esimerge.com$ABCDEF",
    "smdp_address": "smdp.esimerge.com",
    "activation_code": "ABCDEF"
  },
  "request_id": "req_..."
}

Fetch an order by id. Useful to poll status when not using webhooks.

curl https://portal.esimerge.com/api/public/v1/orders/esm_order_AbCdEf \
  -H 'Authorization: Bearer esm_sk_test_...'