Orders

List eSIM orders and fetch a single order with auto-refreshed installation status

`GET /api/v1/esim/orders`

Returns a paginated list of your client's eSIM orders, sorted by most recent first.

Request

curl "https://api.octopuscards.io/api/v1/esim/orders?status=DELIVERED&page=1&per_page=50" \
  -H "Authorization: Bearer <token>"

Query Parameters

Key	Type	Required	Description
`page`	integer	No	Page number (1-based). Default: `1`.
`per_page`	integer	No	Items per page. Default: `50`.
`status`	string	No	Filter by status. One of `PENDING`, `DELIVERED`, `FAILED`, `CANCELLED`.
`client_reference`	string	No	Exact-match lookup against the `client_reference` you supplied on create. Recommended path for fetching an order by your own key — at most one result.

Response

[
  {
    "id": 9302481,
    "client_reference": "TRIP_TOKYO_OCT",
    "status": "DELIVERED",
    "product_name": "Japan eSIM",
    "country_code": "JPN",
    "data_amount_gb": 1.0,
    "validity_days": 7,
    "amount": 4.275,
    "currency": "USD",
    "activation_status": "ACTIVE",
    "is_installed": true,
    "installed_at": "2026-05-15T18:42:11Z",
    "activated_at": "2026-05-15T19:01:08Z",
    "transaction_id": 7402011,
    "created_at": "2026-05-15T14:30:00Z"
  }
]

The list endpoint does not refresh installation status — it returns whatever's persisted. Use GET /esim/orders/:id for the latest installation state.

Response Headers

Pagination headers as documented in Conventions.

See the Create Order response table. Same shape across all order endpoints, except activation_code is never in the list response (it's only emitted from the single-order endpoint, and only when not yet installed).

Errors

401 Unauthorized — missing JWT.

{
  "error": {
    "name": "UnauthorizedError",
    "code": "UNAUTHORIZED",
    "message": "Authentication required"
  }
}

`GET /api/v1/esim/orders/:id`

Returns a single eSIM order. For delivered orders that are still NOT_INSTALLED, this endpoint refreshes installation status on every call — so a single hit returns the most current state.

The activation_code and iccid fields are decrypted on the way out. Once is_installed becomes true, the activation_code is masked from subsequent responses — the activation code is single-use, and emitting it after install would leak credentials.

Request

curl "https://api.octopuscards.io/api/v1/esim/orders/9302481" \
  -H "Authorization: Bearer <token>"

Request Parameters

Key	Type	Required	Description
`id`	integer	Yes	Order ID (path parameter).

Response (delivered, not yet installed)

{
  "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",
  "is_installed": false,
  "transaction_id": 7402011,
  "created_at": "2026-05-15T14:30:00Z"
}

Response (installed and active)

{
  "id": 9302481,
  "client_reference": "TRIP_TOKYO_OCT",
  "status": "DELIVERED",
  "product_name": "Japan eSIM",
  "country_code": "JPN",
  "data_amount_gb": 1.0,
  "validity_days": 7,
  "amount": 4.275,
  "currency": "USD",
  "iccid": "8910300000123456789",
  "activation_status": "ACTIVE",
  "is_installed": true,
  "installed_at": "2026-05-15T18:42:11Z",
  "activated_at": "2026-05-15T19:01:08Z",
  "transaction_id": 7402011,
  "created_at": "2026-05-15T14:30:00Z"
}

Note the absence of activation_code — it's burned after install.

Response Fields

See the Create Order response table.

Errors

400 Bad Request — id is not a valid integer.

{
  "error": {
    "name": "ValidationException",
    "code": "VALIDATION_FAILURE",
    "message": "Invalid order ID"
  }
}

`PATCH /api/v1/esim/orders/:id/notification-email`

Attaches (or updates) the email address that will be notified when the order reaches a terminal status. Only accepted while the order is still in flight — once DELIVERED, FAILED, or CANCELLED, the email is locked.

Use this when your customer enters their email after placing the order (e.g. in a "where should we send the receipt?" follow-up screen).

Request

curl -X PATCH "https://api.octopuscards.io/api/v1/esim/orders/9123456/notification-email" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "customer@example.com"
  }'

Request Parameters

Key	Type	Required	Description
`id`	integer	Yes	Order ID (path parameter).
`email`	string	Yes	Email address. Max 254 characters.

Response

{
  "success": true,
  "message": "Notification email updated successfully"
}

Response Fields

Key	Type	Description
`success`	boolean	Always `true` on success.
`message`	string	Confirmation string.

Errors

400 Bad Request — email missing, empty, or too long.

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

Other messages: "email is too long (max 254 characters)", "Invalid order ID", "Invalid request body".

On this page