Variants

A variant is a data plan within an eSIM product — 1 GB / 7 days, 5 GB / 30 days, etc. You pass amount (matching the variant's amount) when creating an order; Octopus Cards resolves to the matching variant.

The detail endpoints inline variants in the product response, so you usually only hit these endpoints directly when refreshing prices, listing plans for a specific product, or rendering a custom catalogue.

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

Returns the variants for a single product. If no variants are in the local catalogue (e.g. first request for a recently-added product), this endpoint hydrates them on demand and writes them back — so a second call returns instantly.

Request

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

Request Parameters

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

Response

[
  {
    "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
  }
]

Response Fields

Key	Type	Description
`id`	integer	Variant ID.
`esim_product_id`	integer	Parent product ID.
`name`	string	Variant display name (typically encodes data + validity, e.g. "1 GB / 7 days").
`description`	string	Optional longer description.
`currency_code`	string	ISO 4217 currency.
`amount`	number	Wholesale price per eSIM in `currency_code`. Use this as the `amount` field in the order request.
`data_amount_gb`	number	Included data in gigabytes. May be `0` for unlimited or per-minute plans.
`validity_days`	integer	Plan validity once activated.
`client_discount`	number	Client-specific discount percentage. Applied when calculating the wallet debit.

Inactive variants are filtered out server-side and never appear in this response. Wholesale-margin fields are internal-only and never surfaced.

Errors

400 Bad Request — id is not a valid integer.

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

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

Returns a single variant by ID, including any extended fields and regions loaded from the database.

Request

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

Request Parameters

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

Response

Same shape as a single list entry — see the list endpoint above.

Errors

400 Bad Request — id is not a valid integer.

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

On this page