Create Order

POST /api/v1/esim/orders

Purchases an eSIM. Octopus Cards picks the matching variant for (product_id, amount), debits your wallet, dispatches the order for fulfilment, and returns the activation code (an LPA string the device parses) along with the ICCID.

Hybrid sync/async. Every response is 200 OK — branch on the status field in the body:

• If fulfilment completes inside the 60-second handler deadline → status: DELIVERED with the full activation payload (activation_code, iccid).
• If 60 seconds elapse → status: PENDING. A detached goroutine keeps trying in the background; poll GET /esim/orders/:id until terminal.
• Synchronous user-fixable failures (invalid plan, etc.) come back as status: FAILED with failure_code / failure_reason / is_user_fixable populated. Wallet auto-refunded.

Quantity is fixed at 1 — each order produces exactly one eSIM. Send quantity: 1 or omit it; any other value is silently clamped.

Request

curl -X POST "https://api.octopuscards.io/api/v1/esim/orders" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": 712,
    "amount": 4.50,
    "quantity": 1,
    "client_reference": "TRIP_TOKYO_OCT"
  }'

Request Parameters

Response (fulfilled in time — status: DELIVERED)

200 OK

{
  "id": 9302481,
  "client_reference": "TRIP_TOKYO_OCT",
  "status": "DELIVERED",
  "status_text": "eSIM ready to install",
  "product_name": "Japan eSIM",
  "country_code": "JPN",
  "data_amount_gb": 1.0,
  "validity_days": 7,
  "amount": 4.275,
  "currency": "USD",
  "activation_code": "LPA:1$rsp.example.com$ACTIVATION-TOKEN-XYZ",
  "iccid": "8910300000123456789",
  "activation_status": "NOT_INSTALLED",
  "created_at": "2026-05-15T14:30:00Z"
}

The activation_code is the LPA Activation Code — the string the customer scans (via QR) or pastes into their device's eSIM setup screen. Once installed, the activation_code field is masked from subsequent responses (see Lifecycle).

Response (still in flight after 60 seconds — status: PENDING)

200 OK

{
  "id": 9302482,
  "client_reference": "TRIP_TOKYO_OCT",
  "status": "PENDING",
  "status_text": "Awaiting fulfilment",
  "product_name": "Japan eSIM",
  "country_code": "JPN",
  "data_amount_gb": 1.0,
  "validity_days": 7,
  "amount": 4.275,
  "currency": "USD",
  "activation_status": "NOT_INSTALLED",
  "created_at": "2026-05-15T14:30:00Z"
}

Poll GET /esim/orders/:id — the activation code lands once fulfilment completes. A detached dispatch goroutine keeps trying in parallel; the retry cron handles any remaining slow cases.

Response (rejected with user-fixable failure — status: FAILED)

200 OK

{
  "id": 9302483,
  "status": "FAILED",
  "status_text": "Plan unavailable in this region",
  "amount": 4.275,
  "currency": "USD",
  "activation_status": "NOT_INSTALLED",
  "failure_code": "PRODUCT_UNAVAILABLE",
  "failure_reason": "This plan is not currently available for new purchases. Try a different plan.",
  "is_user_fixable": true,
  "created_at": "2026-05-15T14:30:00Z"
}

The wallet is automatically refunded for failed orders.

Enumerations

status:

activation_status (lifecycle on the device; separate from order status):

Response Fields

HTTP Status Summary

Errors

{
  "error": {
    "name": "ValidationException",
    "code": "VALIDATION_FAILURE",
    "message": "Product ID is required"
  }
}