Skip to main content

Share gift-card reward links

Hand out one card at a time from inventory you already bought: reserve a single card from a pool and get a shareable link the recipient opens to reveal it.

Once you've ordered gift cards, they sit in a pool you own. A reward link is how you give one of those cards to a specific person. Each link reserves exactly one card, is single-use, and carries no account — the recipient just opens it and reveals their card. You decide the denomination, currency, and when the link expires; Paylode reserves a matching card and returns a URL you can drop into an email, a chat message, or your own app.

The link is the bearer: anyone who has it can reveal the card. Treat it like a secret.

There are two ways to generate links, and they make the same thing:

  • In the admin app — pick a pool, a denomination, and an expiry, and generate one link or several on the spot. No code; right for hand-picked sends and small batches.
  • Through the API — generate links in bulk from your own systems, and use them anywhere you like, inside or entirely outside Paylode: your email tool, your CRM, a printed QR code. The rest of this guide covers this path.

How it works​

Generating a reward link does three things atomically:

  1. Reserves a card from the pool matching the denomination and currency you asked for. The card leaves the pool's available inventory immediately, so counts stay accurate and two concurrent requests can never hand out the same card.
  2. Mints a single-use link — the public Allocation Page URL, plus the opaque token embedded in it.
  3. Sets an expiry. If the recipient hasn't revealed the card by then, the link expires and the reserved card returns to the pool's available inventory.

You share the link; the recipient reveals the card on the Allocation Page. You never call the reveal step yourself — that's the recipient's action, and it needs no key.

Before you begin​

  • A funded pool. You need a pool with available cards at the denomination and currency you want to give out. See Order gift cards.
  • Your API key. Reserving a card authenticates with the X-API-Key header.
  • The API host. https://gift.paylode.com.

Steps​

1. Find your pool​

List the pools you own to get the pool id and confirm it holds the denomination you want.

curl https://gift.paylode.com/pools \
  -H "X-API-Key: sk_example_0000000000000000"

A trimmed response — the inventories array is the part you care about, one entry per denomination/currency/country:

[
  {
    "id": "b0075e00-0000-4000-8000-00000000000d",
    "owner": "example-co",
    "inventories": [
      {
        "denomination": 50.00,
        "currency": "USD",
        "country": "US",
        "available": 5,
        "reserved": 0,
        "redeemed": 0
      }
    ]
  }
]

Here the pool holds 5 available $50 USD cards. Reserving one drops available to 4 and raises reserved to 1.

Reserve one card and mint the link. Like placing an order, this takes an idempotencyKey (a UUID you generate, so retries don't reserve two cards) and an X-Created-By header.

The body sets the card to reserve and when the link expires. expires_at is a Unix timestamp in seconds — the moment the link stops working if it hasn't been revealed.

curl -X POST "https://gift.paylode.com/pool/b0075e00-0000-4000-8000-00000000000d/reward-links?idempotencyKey=e3b1c7d4-0000-4000-8000-00000000000e" \
  -H "X-API-Key: sk_example_0000000000000000" \
  -H "X-Created-By: pm@example.com" \
  -H "Content-Type: application/json" \
  -d '{
    "denomination": 50.00,
    "currency": "USD",
    "expires_at": 1784377800
  }'

The response carries the shareable URL and the token embedded in it:

{
  "reward_link": "https://rewards.paylode.com#rl_example_9f2c8b1a4d",
  "token": "rl_example_9f2c8b1a4d"
}

The same call in fetch:

const params = new URLSearchParams({ idempotencyKey: crypto.randomUUID() });
const res = await fetch(
  `https://gift.paylode.com/pool/${poolId}/reward-links?${params}`,
  {
    method: "POST",
    headers: {
      "X-API-Key": "sk_example_0000000000000000",
      "X-Created-By": "pm@example.com",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      denomination: 50.0,
      currency: "USD",
      expires_at: 1784377800,
    }),
  },
);
const { reward_link } = await res.json();

Put reward_link wherever you're reaching the recipient — an email, an SMS from your own sender, an in-app message. When they open it, the Allocation Page shows the gift and a reveal action. On reveal, the card's code is shown; the link then keeps showing that same card if they reload or come back later.

Security​

caution

The link is the credential. There's no account and no password behind a reward link — the token in the URL is the authorization. Anyone who obtains the link can reveal the card. Two practical rules:

  • Keep links out of your logs and analytics. Don't log the full reward_link or token, and don't forward it into third-party tracking. The token rides in the URL fragment (after the #), which browsers never send to servers — but your own code can still leak it, so scrub it.
  • Send each link to exactly one recipient. One link is one card. Sending the same link to a group means whoever reveals first gets the card.

A link is always in one of three states:

StateMeaning
RESERVEDA card is reserved and bound to the link, awaiting reveal. This is the state at generation.
REVEALEDThe recipient has revealed the card. Terminal — the link keeps returning the same code on reload, so it's safe for the recipient to revisit.
EXPIREDThe expiry elapsed before reveal. Terminal — the reserved card has returned to the pool's available inventory.

Because an expired link returns its card to the pool, an unclaimed link isn't a lost card — it becomes available to reserve again.

Troubleshooting​

Error bodies here are a plain string carrying a code:

CodeMeaningWhat to do
NO_AVAILABLE_CARDSThe pool has no available card matching the denomination and currency.Order more inventory, or pick a denomination the pool holds.
EXPIRING_DATE_INVALIDexpires_at is missing or not a valid future time.Send a Unix-seconds timestamp in the future.
IDEMPOTENCY_KEY_CONFLICTThe same key was reused with a different body (409).Use a fresh key, or resend the exact original body to replay the same link.
note

Retries won't burn a card. If a generate call times out, resend it with the same idempotencyKey and body — Paylode replays the original link and reserves nothing new.

API reference​

Full schemas are on the Gift document of the API reference — see getGiftCardPools, getGiftCardPool, and generateRewardLink. The recipient-facing view and reveal operations (getRewardLink, revealRewardLink) are anonymous and token-authenticated; you don't call them from your integration.