Gift card orders

This page is about gift cards, game codes and software keys. Selling eSIMs instead? See eSIM orders.

Place an order, read the codes, retry safely.

Place an order

POST/orders

Buys one variant from the balance you name and returns the codes.

Request body

{"variant_id": 12, "quantity": 2, "balance": "MVR", "reference": "my-order-10045"}

Field	Required	Meaning
variant_id or sku	one of them	What to buy. One variant per order.
quantity	yes	1 to 100, and never more than the variant's `available`.
balance	if the key has no default	`"MVR"`, `"USD"` or `"USDT"`: the balance to charge, at that currency's price. Left out, the key's default currency is charged (USD when none is set).
reference	yes	Your own unique id for this purchase. Up to 64 characters: letters, digits and `. _ : -`

Response · 201 (200 for a repeated reference)

{"data": {
  "number": "NC-1042", "reference": "my-order-10045", "status": "completed",
  "variant_id": 12, "product": "Apple Gift Card (US)", "variant": "USD 10",
  "quantity": 2, "delivered": 2, "processing": 0, "refunded_units": 0,
  "currency": "MVR", "unit_price": 18500, "total": 37000, "refunded": 0, "charged": 37000,
  "created_at": "2026-09-18T10:12:44+00:00",
  "codes": [
    {"unit": 1, "code": "XXXX-XXXX-XXXX", "pin": "1234", "link": null, "serial": null, "expires_at": null},
    {"unit": 2, "code": "YYYY-YYYY-YYYY", "pin": null,   "link": null, "serial": null, "expires_at": null}
  ]}}

Amounts are in minor units, laari and cents: see Balances & amounts. Each order buys one variant: make one call per variant.

Retrying safely

The reference makes an order safe to repeat. If the same reference arrives again, for any reason, you get the first order back with status 200: no second order, no second charge, and the same codes.

On a timeout or a dropped connection, retry with the same reference. Only use a new reference when you really want another purchase, for example after a refunded order.

Order status

Status	Meaning	What to do
completed	Every unit delivered. `codes` has them all.	Done.
processing	Paid, and some units are still being bought from our supplier.	Poll `GET /orders/{reference}` every few seconds.
partial_refunded	Some units delivered (they are in `codes`). The rest were refunded to the same balance.	Order the rest again with a new reference.
refunded	Nothing could be delivered. The full amount is back in your balance.	Try again later with a new reference.

An API order never waits for manual delivery. charged is always what the order cost you in the end: total minus refunded.

The codes

Field	Meaning
unit	The unit number within the order, starting at 1.
code, pin	The code to redeem, and its PIN when the product has one.
link	For activation-link products: the link to open instead of a code.
serial, expires_at	Present when the supplier provides them, otherwise null.

Read orders

GET/orders/{number or reference}

One order, in the same shape as above, codes included. 404 not_found when it is not yours or does not exist.

GET/orders?page=1&per_page=25

Your gift card and software orders placed through the API, newest first, without codes. per_page up to 100; meta carries current_page, last_page and total.

Codes are as sensitive as cash. Store them encrypted, and do not write API responses to logs.