Products

`GET /api/v1/esim/products`

Returns a paginated list of eSIM products available to your client. Each product represents a country or region (Japan, Europe, Global) and exposes one or more variants — the actual data plans you order.

Request

curl "https://api.octopuscards.io/api/v1/esim/products?country_code=JPN&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`.
`country_code`	string	No	ISO 3166-1 alpha-3 country code (e.g. `JPN`, `USA`). Filters to that country/region only.
`search`	string	No	Case-insensitive name search.

Response

[
  {
    "id": 712,
    "name": "Japan eSIM",
    "country_code": "JPN",
    "currency_code": "USD",
    "image_url": "https://cdn.example.com/esim/japan.png"
  },
  {
    "id": 904,
    "name": "Global Roaming",
    "country_code": "GLO",
    "currency_code": "USD",
    "image_url": "https://cdn.example.com/esim/global.png"
  }
]

Response Headers

Header	Description
`X-Page`	Current page number
`X-Per-Page`	Items per page
`X-Total-Count`	Total matching products
`X-Total-Pages`	Total pages
`X-Page-Size`	Items in current page
`X-Has-More`	`true` if more pages exist

Response Fields

Key	Type	Description
`id`	integer	Unique product identifier. Pass to `/esim/products/:id` and `/esim/products/:id/variants`.
`name`	string	Product display name.
`country_code`	string	ISO 3166-1 alpha-3 code, or `GLO` for global. Resolve to a human-readable country name client-side.
`currency_code`	string	ISO 4217 wallet/charge currency.
`image_url`	string	Product image URL. May be empty.

Errors

401 Unauthorized — Missing or invalid JWT token.

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

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

Returns full details for a single eSIM product, with its variants inlined. This is the most efficient way to render an eSIM picker UI — one round trip gives you everything.

Request

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

Request Parameters

Key	Type	Required	Description
`id`	integer	Yes	Product ID (path parameter). Must be `> 0`.

Response

{
  "id": 712,
  "name": "Japan eSIM",
  "country_code": "JPN",
  "currency_code": "USD",
  "image_url": "https://cdn.example.com/esim/japan.png",
  "variants": [
    {
      "id": 5511,
      "esim_product_id": 712,
      "name": "Japan 1 GB / 7 days",
      "description": "Data-only eSIM for short trips",
      "currency_code": "USD",
      "amount": 4.50,
      "data_amount_gb": 1.0,
      "validity_days": 7,
      "client_discount": 5.0
    },
    {
      "id": 5512,
      "esim_product_id": 712,
      "name": "Japan 5 GB / 30 days",
      "currency_code": "USD",
      "amount": 14.90,
      "data_amount_gb": 5.0,
      "validity_days": 30,
      "client_discount": 5.0
    }
  ]
}

Response Fields

All fields from the list endpoint, plus:

Key	Type	Description
`variants`	array	Available data plans. See Variants for the per-variant shape.

Errors

400 Bad Request — id is not a valid integer.

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

On this page