Products

Voucher products are digital gift cards available through Octopus Cards. Each product represents a brand and country (e.g. Steam US, Google Play UK) with one or more denominations and a discount schedule.

For gaming top-ups and mobile recharges, see Topup Products. For eSIM data plans, see eSIM Products.

Product Structure

Every voucher product has a fixed country and currency. Within a product, one or more denominations are available - either a fixed face value (e.g. $50 Steam card) or a range (e.g. $10–$500 Amazon card).

Product: Steam Wallet Card (US)
├── Country:  United States (US)
├── Currency: USD
├── Category: Gaming
├── Delivery: Code with PIN - Instant
└── Denominations:
    ├── $10.00  (fixed)  - discount: 3.0%
    ├── $25.00  (fixed)  - discount: 3.0%
    ├── $50.00  (fixed)  - discount: 3.5%
    └── $100.00 (fixed)  - discount: 3.5%

Denominations

Each denomination defines a value range and a discount:

Field	Description
`min_value`	Minimum face value
`max_value`	Maximum face value
`discount`	Discount percentage off face value

Fixed denominations: min_value equals max_value (e.g. a $50 card)
Range denominations: min_value < max_value (e.g. $10–$500, you choose the exact amount)

Pricing & Discounts

The discount you see on a product is the best available rate for your client account. Discounts come from two sources:

Default discount - the standard discount for the product
Client-specific discount - a custom rate negotiated for your account (overrides the default when higher)

The actual cost of an order is calculated by the Charges API, which factors in quantity, discounts, and any FX conversion.

Product Visibility

Not all products in the catalog are visible to every client:

Products can be blacklisted per client (hidden from your catalog)
Only active products with available inventory are returned

Delivery

Mode	Description
`Code with PIN`	A voucher code and PIN are delivered
`URL`	A claim URL is provided for redemption

Time	Description
`Instant`	Delivered in the API response or within seconds
`Delayed`	Processed asynchronously - delivered via webhook

`GET /api/v1/products`

Browse the product catalog. Returns a paginated list of products available to your client account, filtered by country, currency, category, or search term.

Request

curl "https://api.octopuscards.io/api/v1/products?country_id=1&category=Gaming&page=1&limit=25" \
  -H "Authorization: Bearer <token>"

Query Parameters

Key	Type	Default	Description
`page`	integer	`1`	Page number (1-based)
`limit`	integer	`10`	Items per page (1–500)
`category`	string	-	Filter by category name (exact match)
`country_id`	integer	-	Filter by country ID
`currency_id`	integer	-	Filter by currency ID
`search`	string	-	Search by product name (case-insensitive)
`sort_by`	string	`name`	Sort field: `name`, `category`
`sort_dir`	string	`asc`	Sort direction: `asc` or `desc`

Response

[
  {
    "id": 123,
    "name": "Steam Wallet Card",
    "category": "Gaming",
    "sub_category": "PC Gaming",
    "country_code": "USA",
    "currency_code": "USD",
    "image_url": "https://cdn.example.com/steam.png",
    "delivery_mode": "Code with PIN",
    "delivery_time": "Instant",
    "validity": "12 months",
    "available_denominations": [
      {
        "min_value": 50.00,
        "max_value": 50.00,
        "discount": 3.5
      },
      {
        "min_value": 100.00,
        "max_value": 100.00,
        "discount": 3.5
      }
    ]
  }
]

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
`name`	string	Product name (e.g. "Steam Wallet Card")
`category`	string	Primary category (e.g. "Gaming", "Gift Cards")
`sub_category`	string or null	Secondary category (e.g. "PC Gaming")
`country_code`	string	ISO 3166-1 alpha-3 country code (e.g. `USA`)
`currency_code`	string	ISO 4217 currency code (e.g. `USD`)
`image_url`	string or null	Product image URL
`delivery_mode`	string or null	`Code with PIN` or `URL`
`delivery_time`	string or null	`Instant` or `Delayed`
`validity`	string or null	Voucher validity period (e.g. "12 months")
`available_denominations`	array	List of available denominations with pricing
`available_denominations[].min_value`	number	Minimum face value
`available_denominations[].max_value`	number	Maximum face value (equals `min_value` for fixed denominations)
`available_denominations[].discount`	number	Discount percentage off face value

Errors

400 Bad Request - Invalid query parameters.

{
  "error": {
    "name": "BadRequestError",
    "code": "BAD_REQUEST",
    "message": "Invalid query parameters"
  }
}

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

Returns full details for a single product, including all available denominations and their discounts.

Request

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

Request Parameters

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

Response

{
  "id": 123,
  "name": "Steam Wallet Card",
  "category": "Gaming",
  "sub_category": "PC Gaming",
  "country_code": "USA",
  "currency_code": "USD",
  "image_url": "https://cdn.example.com/steam.png",
  "terms": "Non-refundable. Redeemable on Steam only.",
  "details": "Add funds to your Steam wallet for games, DLC, and in-game items.",
  "how_to_use": "Open Steam client → Account Details → Add Funds → Redeem code",
  "delivery_mode": "Code with PIN",
  "delivery_time": "Instant",
  "validity": "12 months",
  "available_denominations": [
    {
      "min_value": 10.00,
      "max_value": 10.00,
      "discount": 3.0
    },
    {
      "min_value": 50.00,
      "max_value": 50.00,
      "discount": 3.5
    },
    {
      "min_value": 100.00,
      "max_value": 100.00,
      "discount": 3.5
    }
  ]
}

Response Fields

All fields from the list endpoint, plus:

Key	Type	Description
`terms`	string or null	Redemption terms and conditions
`details`	string or null	Product description
`how_to_use`	string or null	Step-by-step redemption instructions

Errors

400 Bad Request - ID is not a valid integer.

{
  "error": {
    "name": "BadRequestError",
    "code": "BAD_REQUEST",
    "message": "Invalid product ID"
  }
}

On this page