# Gift cards (/docs/products/gift-cards)

## What you can sell [#what-you-can-sell]

Gift cards are digital cards from retail, gaming, travel, entertainment and other brands. A card is one brand in one
issuing country, and it lists one or more offers:

- A **fixed** offer sells one face value, for example 50 USD.
- A **range** offer sells any value between a minimum and a maximum, on a step, for example 1 to 500 USD. You choose
  the value when you quote and order.

An order delivers the card number and PIN (or whichever parts the card has) in the order item. You can also ask
OpenRoam to email the card to a recipient as a gift.

This page covers what is specific to gift cards. Authentication, environments, idempotency, errors, webhooks and the
order envelope are shared by every product:
[Quickstart](/docs/quickstart), [Authentication](/docs/authentication), [Environments](/docs/environments),
[Idempotency](/docs/idempotency), [Errors](/docs/errors), [Webhooks](/docs/webhooks) and [Orders](/docs/orders).

## The flow [#the-flow]

<Steps>
<Step>
### Browse the catalog [#browse-the-catalog]

| Route | Use it to |
|---|---|
| [`GET /v1/giftcards/search`](/docs/api-reference/gift-cards/search) | List cards with their offers, one page at a time. |
| [`GET /v1/giftcards/cards/{id}`](/docs/api-reference/gift-cards/get-card) | Read one card by its `card_...` id. It returns the same item that search returns. |
| [`GET /v1/giftcards/catalog`](/docs/api-reference/gift-cards/get-catalog) | Walk every card in id order with a cursor, for example to build your own copy of the catalog. |
| [`GET /v1/giftcards/categories`](/docs/api-reference/gift-cards/get-categories) | Read the category list (`shopping`, `foodAndDining`, `entertainment`, `gaming`, `travel`, `paymentCards`, `softwareAndDigital`, `other`) with display names. |
</Step>

<Step>
### Quote [#quote]

[`POST /v1/giftcards/quote`](/docs/api-reference/gift-cards/quote) prices the items of an order body. It has no side
effects: nothing is reserved and nothing expires.
</Step>

<Step>
### Order [#order]

[`POST /v1/giftcards/order`](/docs/api-reference/gift-cards/create-order) takes the same body as the quote. It needs an
`Idempotency-Key` header and an API key with the `manage` permission. It returns the shared order envelope.
</Step>

<Step>
### Read the result [#read-the-result]

Follow the order with [`GET /v1/orders/{id}`](/docs/api-reference/orders/get-by-id) or the
[`order.fulfillment.updated`](/docs/api-reference/webhooks/order-fulfillment-updated) webhook.
</Step>
</Steps>

An id from the catalog names a card. You never order a card id: you quote and order one of its offers by `publicId`.

## Search and read cards [#search-and-read-cards]

```bash
curl "https://api.sandbox.openroam.com/v1/giftcards/search?countryCode=US&limit=10" \
  -H "X-Partner-Key: $OPENROAM_API_KEY"
```

```json
{
  "items": [
    {
      "id": "card_example1234567890abcdefghij",
      "name": "Example Store",
      "countryCode": "US",
      "category": "shopping",
      "logoUrl": "https://cdn.example.com/logo.png",
      "description": "Redeem at example.com",
      "offers": [
        {
          "publicId": "giftcard_example1fixed00000000000",
          "name": "Example Store 50 USD",
          "description": null,
          "value": { "type": "fixed", "amount": 50, "currency": "USD" },
          "price": { "amount": 48.98, "currency": "USD" },
          "requiredInputs": [
            { "name": "recipientEmail", "type": "email", "required": false, "description": "Sends the card to this email address as a gift." },
            { "name": "giftMessage", "type": "text", "required": false, "description": "Message included in the gift email." }
          ]
        },
        {
          "publicId": "giftcard_example1range0000000000",
          "name": "Example Store 1–500 USD",
          "description": null,
          "value": { "type": "range", "min": 1, "max": 500, "step": 0.01, "currency": "USD" },
          "price": { "min": 2.01, "max": 506.00, "currency": "USD" },
          "requiredInputs": [
            { "name": "recipientEmail", "type": "email", "required": false, "description": "Sends the card to this email address as a gift." },
            { "name": "giftMessage", "type": "text", "required": false, "description": "Message included in the gift email." }
          ]
        }
      ],
      "details": { "isRedeemableGlobally": false, "redemptionInstructions": "Go to example.com/redeem and enter the code." }
    }
  ],
  "pagination": { "currentCount": 1, "totalCount": 1, "skip": 0, "limit": 10, "hasMore": false, "page": 1, "totalPages": 1 }
}
```

What to know about the catalog:

- `countryCode` is the issuing country, or null for a card without one (a global card). A `countryCode` filter does not
  list a card without one.
- `details.isRedeemableGlobally` says whether the card can be redeemed outside its issuing country. The
  `isRedeemableGlobally=true` filter keeps only such cards.
- A card with the same brand and country but another face currency is a separate card with its own id.
- Offers list fixed values from low to high, then at most one range offer. A range always has a `max`, and its `step`
  is the smallest allowed increment.
- `price` is indicative and in the requested currency (`currency`, or your API key's currency). For a range it is the
  price of the `min` value and of the `max` value. The quote is authoritative.
- A fixed offer whose value the range also sells is hidden when the range sells that value for the same price or less.
  In that case you buy that value through the range.

Filters for search and catalog:

| Parameter | Search | Catalog | Meaning |
|---|---|---|---|
| `countryCode` | yes | yes | ISO 3166-1 alpha-2. Omit it for every country. |
| `category` | yes | yes | One of the category values above. |
| `q` | yes | no | Brand name or card id, case-insensitive, at most 100 characters. |
| `isRedeemableGlobally` | yes | yes | `true` keeps only cards that can be redeemed in any country. |
| `valueType` | yes | yes | `fixed` or `range`. Keeps those offers within each card. |
| `currency` | yes | yes | Price currency, three letters. Defaults to your API key's currency. |
| `page`, `limit` | yes | `limit` only | Search: `page` defaults to 1, `limit` to 10 (at most 100). Catalog: `limit` 1 to 100, default 100. |
| `cursor` | no | yes | The `nextCursor` of the previous catalog page. |

Search can return fewer cards than `limit` on a page. Catalog pages can even be empty while `nextCursor` is not null:
keep following `nextCursor`, with the same filters and currency, until it is null. A cursor reused with other filters
or another currency returns `400 / 10001`.

## Quote and order [#quote-and-order]

Quote and order take the same body.

```json
{
  "currency": "USD",
  "referenceId": "partner-order-42",
  "items": [
    {
      "publicId": "giftcard_example1fixed00000000000",
      "quantity": 1,
      "inputs": { "maxPrice": { "amount": 50, "currency": "USD" } }
    },
    {
      "publicId": "giftcard_example1range0000000000",
      "quantity": 1,
      "inputs": {
        "recipientEmail": "friend@example.com",
        "giftMessage": "Happy birthday!",
        "value": { "amount": 25, "currency": "USD" },
        "maxPrice": { "amount": 30, "currency": "USD" }
      }
    }
  ]
}
```

- `items` holds 1 to 5 items, and at most 5 cards in total. `quantity` can be above 1; each card becomes its own order
  item.
- `currency` is the order currency. It defaults to your API key's currency.
- `referenceId` is your own order reference, unique per partner, at most 128 characters. A quote validates it and
  ignores it.
- The card value and the price limit are members of `inputs`. A `value` or `maxPrice` beside `inputs` is rejected as
  an unknown member.

### Product inputs [#product-inputs]

| `inputs` member | When | Meaning |
|---|---|---|
| `value` | Required for a range offer; optional for a fixed offer | `{ amount, currency }` in the card's face currency. For a range it must be within `min` and `max` and on the `step`. For a fixed offer it must equal the offer's amount. |
| `maxPrice` | Optional | The highest unit price you accept, `{ amount, currency }` in the order currency. |
| `recipientIdentifier` | Only when the offer lists it in `requiredInputs` | The recipient's government or tax identifier, up to 64 characters. |
| `recipientEmail` | Optional, on every offer | Sends the card to this address as a gift email, up to 254 characters. |
| `giftMessage` | Optional, only with `recipientEmail` | Message in the gift email, up to 500 characters. |

`inputs` can be left out for a fixed offer that does not list `recipientIdentifier`. A range offer needs at least
`inputs.value`.

### The quote response [#the-quote-response]

```json
{
  "currency": "USD",
  "items": [
    {
      "publicId": "giftcard_example1fixed00000000000",
      "quantity": 1,
      "name": "Example Store 50 USD",
      "value": { "amount": 50, "currency": "USD" },
      "price": { "amount": 48.98, "currency": "USD" }
    },
    {
      "publicId": "giftcard_example1range0000000000",
      "quantity": 1,
      "name": "Example Store 25 USD",
      "value": { "amount": 25, "currency": "USD" },
      "price": { "amount": 26.25, "currency": "USD" }
    }
  ],
  "total": { "amount": 75.23, "currency": "USD" }
}
```

For a range item, the quote prices the cheapest offer of the same card that sells exactly that value: the range you
sent, another range of the card, or a fixed offer of exactly that value. The quote item returns the `publicId` of the
winning offer, which can differ from the one you sent. Order with the id the quote returned.

### Place the order [#place-the-order]

```bash
curl -X POST https://api.sandbox.openroam.com/v1/giftcards/order \
  -H "X-Partner-Key: $OPENROAM_API_KEY" \
  -H "Idempotency-Key: 5a1f0c3e-8d1a-4c1e-9a55-0f6b7a2d9e10" \
  -H "Content-Type: application/json" \
  -d @order.json
```

### Price limit at order time [#price-limit-at-order-time]

The order recalculates every price. A lower price is charged as calculated. A higher price is accepted only up to the
item's `inputs.maxPrice`. Above it, the order fails with `409 / 11002` at `items[i].inputs.maxPrice` and nothing is
charged. The card value is never reduced to fit `maxPrice`.

```json
{
  "code": 11002,
  "name": "OFFER_PRICE_CHANGED",
  "message": "The price changed.",
  "requestId": "0123456789abcdef0123456789abcdef",
  "details": [ { "path": "items[0].inputs.maxPrice", "reason": "PRICE_CHANGED" } ]
}
```

Quote and order check the body in the same way. Structural problems (an unknown member, a missing `publicId`, a
`quantity` below 1, more than 5 items) give `400 / 10001` before any item is priced. After that, items are checked one at
a time in request order, and the first failing item ends the request. Its index is in the error path.

## What the order item contains [#what-the-order-item-contains]

Read an item with [`GET /v1/order-items/{id}`](/docs/api-reference/order-items/get-by-id), or as one entry of
`items` in [`GET /v1/orders/{id}`](/docs/api-reference/orders/get-by-id).

```json
{
  "id": "01a1413c-265f-77b1-9041-25aee298d4d0",
  "orderId": "01a1413c-2642-7348-bf49-0f93879eacf1",
  "productType": "giftCard",
  "price": { "amount": 26.25, "currency": "USD" },
  "purchasedProduct": {
    "name": "Example Store 25 USD",
    "countryCode": "US",
    "logoUrl": "https://cdn.example.com/logo.png",
    "value": { "amount": 25, "currency": "USD" },
    "inputs": { "recipientIdentifier": null, "recipientEmail": "f***@example.com", "giftMessage": "Happy birthday!" },
    "details": {
      "brandName": "Example Store",
      "isRedeemableGlobally": false,
      "redemptionInstructions": "Go to example.com/redeem and enter the code."
    }
  },
  "fulfillment": {
    "status": "fulfilled",
    "result": {
      "deliveredValue": { "amount": 25, "currency": "USD" },
      "details": {
        "codes": [ { "cardNumber": "CARD-0001", "pinCode": "PIN-0001", "instructions": null } ],
        "delivery": { "status": "pending" }
      }
    },
    "failure": null
  },
  "actions": {
    "amendment": { "availability": "notAvailable", "reason": null },
    "cancellation": { "availability": "notAvailable", "reason": null },
    "update": { "availability": "available", "reason": null }
  },
  "createdAt": "2026-10-15T20:23:43.489051Z",
  "effectivePaidAmount": { "amount": 26.25, "currency": "USD" }
}
```

`purchasedProduct` is what was bought:

- `name` is the card at its value. `value` is the face value, and `countryCode` the issuing country.
- `inputs` echoes `recipientIdentifier`, `recipientEmail` and `giftMessage`. The identifier is masked as `***` plus its
  last four characters, and the email as `f***@example.com`. `giftMessage` is returned as sent. The card value is in
  `value`, and `maxPrice` is never echoed.
- `details` has `brandName`, `isRedeemableGlobally` and `redemptionInstructions`.

`fulfillment.result` is what was delivered:

- `deliveredValue` is the face value of the issued card. It is null until a card is issued.
- `details.codes` lists the issued codes as `cardNumber`, `pinCode` and `instructions`. Any of the three can be null,
  because cards differ. The list is empty when the item does not release its codes, for example after a refund.
- `details.delivery` is null for a card that is not a gift. For a gift it is `{ status }`, where `status` is `pending`,
  `processing`, `retry`, `sent` or `failed`. The gift email is sent after fulfillment, so an item can be `fulfilled`
  while its delivery is still `pending`.

`fulfillment.status` stays `pending` until a code has been retrieved, so a purchase that reports success without a
code has not delivered anything. If the item stays pending longer than usual, `fulfillment.progress` carries the code
`CONFIRMING_OUTCOME`.

## After purchase [#after-purchase]

Gift cards use the shared order-item routes, described in [Orders](/docs/orders).

- **Change the gift recipient.** [`POST /v1/order-items/{id}/update`](/docs/api-reference/order-items/update) changes
  who a delivered gift card is sent to. It takes `{ "inputs": { "recipientEmail": "...", "giftMessage": "..." } }`,
  needs the `manage` permission and an `Idempotency-Key`, and never charges or refunds anything. A member you leave
  out keeps its current value, and a card bought without a recipient needs `recipientEmail`. A successful update sends
  the gift email again and starts `delivery.status` at `pending` again. `actions.update` is `available` only for a
  delivered, unrefunded card whose codes can be shown and while no gift email is being sent. Otherwise the update
  returns `409 / 18005` with the reason `IN_PROGRESS` or `NOT_AVAILABLE`.
- **Cancel and amend.** An issued card cannot be taken back or changed. [Cancel](/docs/api-reference/order-items/cancel)
  and its [preview](/docs/api-reference/order-items/get-cancellation-preview) answer `422 / 18000`
  (`CANCELLATION_NOT_SUPPORTED`), and amending answers `422 / 18002` (`AMENDMENT_NOT_SUPPORTED`). While the card is
  still pending, cancel answers `409 / 18001`.
- **Rejected cards are refunded.** If fulfillment is rejected, the item is refunded in full automatically and the
  [`order-item.refunded`](/docs/api-reference/webhooks/order-item-refunded) webhook reports it. Cancelling with the
  reason `fulfillmentFailed` returns that refund.

## Testing in Sandbox [#testing-in-sandbox]

Sandbox supports gift cards. It uses the same routes and rules as production with a test catalog and test wallet
funds; see [Environments](/docs/environments). Gift cards in Sandbox never produce redeemable codes, and no real gift
email is sent.

On `POST /v1/giftcards/order`, set the `OpenRoam-Sandbox-Scenario` header to choose the fulfillment outcome:

| Header value | Result |
|---|---|
| `success` (or no header) | The order is fulfilled and each item gets a clearly synthetic code and PIN. |
| `fulfillment.rejected` | Fulfillment is rejected after payment. There are no codes, and the item is refunded automatically. |
| `fulfillment.pending` | Returns pending at once. The item becomes eligible for success after 15 minutes. |
| `fulfillment.late_success` | Returns pending at once and becomes eligible for success after 2 minutes. |
| `fulfillment.late_rejected` | Returns pending at once and confirms the rejection after 2 minutes. |

- The scenario applies to every item of the order and is part of idempotency. The same key, body and scenario replay
  the same order, and changing the scenario with the same key returns `409`.
- The header is accepted only on order creation in Sandbox. Anywhere else, including search and quote, it returns
  `400 / 10001` with the reason `NOT_ALLOWED`. An unknown or repeated value returns `400 / 10001` with
  `INVALID_VALUE`.
- Pending results contain no codes. Read the order again or wait for the webhook: the outcome appears on the next
  reconciliation pass, so the durations are not a guaranteed delay.
- Even with `success`, fulfillment takes a few seconds, so read the order again if the first read shows `pending`.

Sandbox codes look like `SANDBOX-NOT-REDEEMABLE-...`, with a PIN starting `TEST-ONLY-`. They are the same on replay,
and separate order items get distinct codes. Gift email delivery starts `pending` and then reads `sent`, which here
means a local test delivery.

Fixtures to try. Card ids are generated per environment, so find each card with search (`countryCode` and `q`) and use
the `publicId` of its offers.

| Card | Offer | Inputs to send |
|---|---|---|
| Apple, US | Fixed 10 USD | None |
| Amazon, US | Range 5 to 100 USD, step 5 | `inputs.value`, for example 25 USD |
| Xbox, US | Fixed 25 USD | `inputs.recipientIdentifier`, for example `TEST-RECIPIENT-1234` |
| Steam, AZ | Fixed 20 USD | None |
| Caspian Market, AZ | Fixed 10, 25 and 50 AZN | None (try `currency` USD to see a face value in AZN) |
| Baku Digital, AZ | Range 5 to 50 USD, step 5 | `inputs.value` and `inputs.recipientIdentifier` |
| PlayStation, GB | Fixed 10 GBP | None |

The face value keeps its own currency through quote, order and fulfillment: 25 AZN stays 25 AZN while the checkout price
is in USD. Send an `inputs.maxPrice` below a quoted price to trigger `409 / 11002`.

## Errors to handle [#errors-to-handle]

Shared error handling is in [Errors](/docs/errors). Gift card specific cases:

| Status / code | Reason | Path | When |
|---|---|---|---|
| `400 / 10001` | `REQUIRED` | `items[i].inputs.value` | A range offer without a value. |
| `400 / 10001` | `INVALID_VALUE` | `items[i].inputs.value.amount` | A value outside the range, off its step, or different from a fixed offer's amount. |
| `400 / 10001` | `CURRENCY_MISMATCH` | `items[i].inputs.value.currency` | The value is not in the card's face currency. |
| `400 / 10001` | `CURRENCY_MISMATCH` | `items[i].inputs.maxPrice.currency` | `maxPrice` is not in the order currency. |
| `400 / 10001` | `REQUIRED` or `INVALID_VALUE` | `items[i].inputs.recipientIdentifier` | The offer needs a recipient identifier and it is missing, too long or has control characters. |
| `400 / 10001` | `NOT_ALLOWED` | `items[i].inputs.giftMessage` | A gift message without `recipientEmail`. |
| `400 / 10001` | `INVALID_VALUE` | `items[i].inputs.<member>` | An `inputs` member the offer does not define. |
| `400 / 11004` | `EXPIRED_OR_INVALID` | `items[i]` | An unknown, malformed or foreign `publicId`, including a card id or another product's offer. |
| `409 / 11003` | `UNAVAILABLE` | `items[i]` | The offer cannot be sold now. |
| `409 / 11002` | `PRICE_CHANGED` | `items[i].inputs.maxPrice` | The current unit price is above `maxPrice`. Nothing is charged. |
| `404 / 10004` | none | none | `GET /v1/giftcards/cards/{id}` with an unknown id, or a card with no orderable offer. |
| `403 / 10003` | `SERVICE_NOT_ENABLED` | `service` | Gift cards are not enabled for your account. |
| `422 / 18000` | none | none | Cancelling an issued card. |
| `409 / 18005` | `IN_PROGRESS` or `NOT_AVAILABLE` | `id` | A recipient update while the gift email is being sent, or on a card that cannot be updated. |

Browse routes reject any unknown query parameter with `400 / 10001` and the reason `UNSUPPORTED_FIELD`. A failing
quote or order creates and charges nothing.