Orders

Orders are how you purchase digital gift cards and top-ups through the Octopus Cards API. You submit an order with a product, denomination, and quantity — the platform handles fulfillment and delivers voucher codes, PINs, or claim URLs back to you.

Order Lifecycle

1. Calculate charges    POST /api/v1/products/:id/charges
2. Create order         POST /api/v1/orders
3. Poll for delivery    GET  /api/v1/orders/:id
4. Retrieve vouchers    (included in order response)

Sync vs Async Delivery

Orders are fulfilled in one of two modes depending on quantity:

Mode	Condition	Behaviour
Synchronous	Quantity ≤ 5	Vouchers are returned directly in the create order response
Asynchronous	Quantity > 5	Order is created with status `PENDING`. A background job processes the order and delivers vouchers. Poll the order endpoint to check status.

For async orders, the response returns immediately with status: PENDING and an empty vouchers array. Use GET /api/v1/orders/:id to check when delivery is complete.

Order Statuses

Status	Description
`PENDING`	Order placed, vouchers are being processed
`DELIVERED`	All vouchers have been successfully delivered
`PARTIALLY_DELIVERED`	Some vouchers delivered, others still pending or failed
`FAILED`	Order could not be fulfilled
`CANCELLED`	Order was cancelled

Status Transitions

Orders follow a predictable lifecycle. The diagram below shows all valid transitions:

                    ┌──────────┐
                    │ PENDING  │
                    └────┬─────┘
                         │
              ┌──────────┼──────────┐
              ▼          ▼          ▼
      ┌───────────┐ ┌────────┐ ┌──────────┐
      │ DELIVERED │ │ FAILED │ │CANCELLED │
      └───────────┘ └────────┘ └──────────┘
              ▲
              │
   ┌──────────┴──────────┐
   │ PARTIALLY_DELIVERED  │
   └──────────────────────┘

From	To	When
`PENDING`	`DELIVERED`	All vouchers fulfilled successfully
`PENDING`	`PARTIALLY_DELIVERED`	Some vouchers delivered, others still in progress
`PENDING`	`FAILED`	Fulfillment failed entirely
`PENDING`	`CANCELLED`	Order cancelled before fulfillment
`PARTIALLY_DELIVERED`	`DELIVERED`	Remaining vouchers fulfilled
`PARTIALLY_DELIVERED`	`FAILED`	Remaining vouchers could not be fulfilled

DELIVERED, FAILED, and CANCELLED are terminal statuses — once an order reaches one of these, it will not change again. PARTIALLY_DELIVERED is the only non-terminal status besides PENDING.

Voucher Delivery

When an order is DELIVERED or PARTIALLY_DELIVERED, the vouchers are included in the order response. Each voucher may contain:

Field	Description
`card_number`	The voucher code (e.g. gift card number)
`pin_code`	PIN associated with the voucher (if applicable)
`claim_url`	A URL to redeem the voucher (for URL-based delivery)
`expires_at`	Expiry date of the voucher (RFC 3339)
`voucher_reference_number`	Reference code for the voucher

Not all fields are present on every voucher — it depends on the product's delivery mode:

Delivery Mode	Fields Present
`Code with PIN`	`card_number`, `pin_code`, `expires_at`, `voucher_reference_number`
`URL`	`claim_url`, `pin_code` (optional), `expires_at`

Voucher codes and PINs are encrypted at rest and decrypted on-the-fly when you retrieve the order. Store them securely on your side — they represent real monetary value.

Balance & Wallet Checks

Before an order is created, the platform verifies:

Wallet exists — you must have a wallet in the product's currency (or specify a wallet_id for cross-currency orders with FX conversion)
Sufficient balance — your wallet balance must be ≥ the total payable amount (from the charges endpoint)
Atomic deduction — the wallet is debited in the same database transaction as the order creation, ensuring consistency

If the balance is insufficient, the order is rejected with a 400 error and no funds are moved.

Quantity Limits

Limit	Description
Bulk limit	Your client account has a configurable maximum quantity per order. Check `max_quantity` from the charges endpoint.
Absolute max	Code-based orders are capped at 5,000 vouchers per request

Reference Codes

Every order has a ref (reference code):

If you provide one, it must be unique across all your orders. Duplicate references are rejected.
If you omit it, the platform generates a UUID automatically.
Use the client_reference field for your own internal tracking (not required to be unique).

Endpoints

Method	Path	Description
`POST`	`/api/v1/orders`	Create a new voucher order
`GET`	`/api/v1/orders`	List all orders with pagination
`GET`	`/api/v1/orders/:id`	Get order details with vouchers

On this page