Issue and accept gift cards

A gift card is a voucher with a monetary balance. Each successful redemption spends up to the order amount, records a transaction, and leaves any unused balance available for a later order.

Use gift cards for prepaid value, promotional credit, or support-issued store credit when the balance should be managed inside OfferKit.

Decide the policy

Before issuing cards, decide:

• whether codes are purchased, promotional, or manually issued;
• whether each card is assigned to a customer;
• the initial value and currency;
• expiration and redemption limits;
• how the remaining balance appears in checkout and account pages;
• what your application does when the card covers only part of the order.

OfferKit tracks value and spend. Your application remains responsible for selling the card, collecting any remaining payment, and communicating the code securely.

Configure the campaign and card

Create a GIFT_VOUCHERS campaign, set its currency and dates, then activate it. Create one gift-card voucher or generate a batch. A gift card requires a positive starting balance.

For example, this creates a USD 50 card through the SDK:

const card = await offerkit.vouchers.create({
  code: "GIFT-7K3PQ9LM",
  campaignId: giftCampaignId,
  type: "GIFT_CARD",
  giftBalance: 5_000,
  customerId: customer.id,
});

Money uses minor units, so 5_000 USD is USD 50.00.

Preview spend at checkout

Validate the card with the current order:

const preview = await offerkit.vouchers.validate({
  params: { code: submittedCode },
  body: {
    customerExternalId: session.user.id,
    order: { amount: cart.totalCents, currency: cart.currency, items: cart.items },
  },
});

The preview spends no balance. If the card contains USD 20 and the order is USD 50, the calculated benefit is USD 20 and your checkout must collect the remaining USD 30. If the card contains more than the order total, only the order amount is used.

Commit the spend

Redeem the card at the same business boundary you use for other payment value. Pass the order ID as the idempotency key:

const spend = await offerkit.vouchers.redeem({
  params: { code: submittedCode },
  body: {
    customerExternalId: session.user.id,
    externalOrderId: order.id,
    order: { amount: order.totalCents, currency: order.currency, items: order.items },
    idempotencyKey: `gift-card:${order.id}`,
  },
});

Only treat the balance as spent when spend.ok is true. Store the redemption ID and amount on the order. A replay with the same key returns the original result.

Show balance and history

Fetch the voucher to show its current giftBalance. Fetch its ledger when the customer or support agent needs the history:

const card = await offerkit.vouchers.get({ params: { code } });
const history = await offerkit.vouchers.transactions({ params: { code } });

The ledger can contain initial credit, redemption, rollback, and adjustment reasons. Rollback and ledger-preserving adjustments are not exposed through the public API. Do not calculate the authoritative balance by summing a cached history in the browser; use the current balance returned by OfferKit.

Test before launch

Test a card that:

• fully covers an order;
• covers only part of an order;
• has more balance than the order needs;
• has zero balance;
• belongs to a different customer;
• uses the wrong currency;
• expires before redemption;
• receives two concurrent spend attempts.

Operate gift cards

Use the voucher page for current status and the transactions endpoint for its balance history. Disable a compromised card immediately. Pause the parent campaign only when all cards in that program must stop working.

Gift cards are not supported inside the multi-voucher stack redemption flow. Process a gift card separately from stacked discount vouchers and make the payment order explicit in your checkout.

Payment and refunds

Gift cards, store credit, and promotional credit all use a gift-card voucher when OfferKit holds the monetary balance. Your application decides whether customers purchase that value or receive it as a benefit. A discount reduces the price; gift value pays part of the amount remaining. Both currently appear as a voucher redemption in OfferKit.

For example, after discounts a USD 50 order may have USD 20 paid by gift value and USD 30 collected by your payment provider. Pass 5000 as the gift redemption’s order amount and store the actual gift spend. If the card has USD 80, the same call spends USD 50; it has no separate input for “spend only USD 10.” Keep that policy explicit in your checkout.

Canceling the order or refunding the payment does not restore gift value. There is no public gift-card rollback or ledger-preserving balance-adjustment command. Plan support compensation before launch; Retries, refunds, and recovery describes the supported options.

Gift-card redemption currently does not emit voucher.redeemed. Use the direct spend response and your stored order record to trigger receipts or reconciliation.