Getting Started

Octopus Cards API documentation — authenticate, browse products, and create orders

The Octopus Cards API gives you programmatic access to 10,000+ digital products across 100+ countries. This documentation covers authentication, product catalog, order management, and more.

Quickstart

Authenticate — POST your credentials to /auth/login to receive a JWT
Browse products — Query /api/v1/products with your token
Create orders — POST to /api/v1/orders with a product ID and quantity

Base URL

https://sandbox-api.octopuscards.io

Authentication

All API requests (except login) require a Bearer token in the Authorization header:

curl {{host}}/api/v1/products \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

See the Authentication section for the full login, refresh, and logout flow.

Request Headers

Every request can include these headers:

Header	Required	Description
`Authorization`	Yes (except `/auth/login`)	`Bearer <access_token>` — your JWT from the login endpoint
`Content-Type`	Yes (POST/PUT/PATCH)	Must be `application/json`
`X-Request-Id`	No	Your own trace ID (KSUID format). If omitted, the server generates one and returns it in the response. Use this to correlate requests across your systems.

Response Headers

Every response includes:

Header	Description
`X-Request-Id`	The request trace ID — either echoed from your request or server-generated

List endpoints also include pagination headers:

Header	Description	Example
`X-Page`	Current page number (1-based)	`1`
`X-Per-Page`	Items per page	`50`
`X-Total-Count`	Total items across all pages	`250`
`X-Total-Pages`	Total number of pages	`5`
`X-Page-Size`	Items in the current page (may be less than `X-Per-Page` on the last page)	`50`
`X-Has-More`	Whether more pages exist	`true`

Pagination

List endpoints accept these query parameters:

Parameter	Default	Range	Description
`page`	`1`	1+	Page number (1-based)
`limit`	`50`	1–10,000	Items per page
`sort`	`id DESC`	—	Sort config as JSON: `{"Field":"name","Direction":"ASC"}`

Example:

curl "{{host}}/api/v1/products?page=2&limit=25" \
  -H "Authorization: Bearer <token>"

Date Format

All date and time fields in requests and responses use RFC 3339 (ISO 8601 with timezone):

2025-01-15T13:00:00Z
2025-01-15T18:30:00+05:30