Variants

SKU-level pricing for top-up products - fetch variants, inspect metadata, pick a denomination

A variant is a SKU within a top-up product. Variants are how denominations, validity windows, and regional pricing are expressed. When the same SKU is available through multiple fulfilment paths, the list endpoint returns the best one for your client.

You normally do not pass variant_id to the order or charges endpoints — those endpoints pick the best variant automatically given a product_id + amount. Use this page when you need to render variants in a UI (e.g. "Pick a pack: 60 UC / 325 UC / 660 UC").

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

Returns variants for the given product, deduplicated by SKU and filtered to your client's catalogue.

Request

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

Request Parameters

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

Response

[
  {
    "id": 88412,
    "name": "60 UC",
    "category": "In-Game Currency",
    "currency_code": "USD",
    "fixed_amounts": ["0.99"],
    "available_in": [
      { "code": "GLO", "name": "Global" }
    ],
    "fields": {
      "par_value": "60 UC",
      "delivery_time": "Instant",
      "validity_days": "365"
    }
  },
  {
    "id": 88413,
    "name": "325 UC",
    "category": "In-Game Currency",
    "currency_code": "USD",
    "fixed_amounts": ["4.99"],
    "available_in": [{ "code": "GLO", "name": "Global" }],
    "fields": {
      "par_value": "325 UC",
      "delivery_time": "Instant"
    }
  }
]

Response Fields

Key	Type	Description
`id`	integer	Unique variant identifier.
`name`	string	Variant display name (e.g. "60 UC", "1 GB / 28 days").
`category`	string	Sub-category within the product (e.g. "Airtime", "Data", "Bundle"). May be empty.
`currency_code`	string	ISO 4217 currency.
`min_amount`	number, omitempty	Lower bound of the customer-chosen amount. Omitted for fixed-denomination variants.
`max_amount`	number, omitempty	Upper bound of the customer-chosen amount. Omitted for fixed-denomination variants.
`fixed_amounts`	array, omitempty	Available denominations as decimal strings. Present only when the variant is fixed-denomination (`min_amount` / `max_amount` are absent).
`available_in`	array	Regions/countries where this variant is valid (`{code, name}` pairs).
`fields`	object	Customer-facing metadata as a `key → value` map (e.g. `par_value`, `delivery_time`, `validity_days`, `validity_unit`, `tag`, `benefit_*`). Internal-only keys (wholesale/retail/FX pricing, fulfilment routing identifiers) are stripped server-side.

Inactive variants are filtered out by the server. To detect fixed vs range pricing, branch on the presence of fixed_amounts (or, equivalently, on whether min_amount / max_amount are present).

Errors

400 Bad Request — id is not a valid integer.

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

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

Returns a single variant by ID. Same shape as a list element.

Request

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

Request Parameters

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

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

On this page