Skip to Content
Build a shop

ORBCOMMERCE DOCUMENTATION

Gift cards

Sell gift cards as products, let your team make them, and set how their codes look and how long they last.

A gift card is a code with a balance. OrbCart keeps that balance for you, one card at a time, so no spreadsheet and no second system is needed.

A card comes into being in two ways: an Order sells one, or your team makes one.

Sell a gift card

A gift card is a product like any other. Mark its offer in your offers answer with giftCard: true: its price is the card's value. The Order that sells it issues one card for every unit, each worth the Line's price.

Cards become spendable only after the Order is paid in full. A bank transfer waiting for funds, or a card authorization whose capture fails, issues no gift card yet.

The buyer receives one mail per card, with its value, its code and a page to print it from. The code is not in the Order, the Cart or any event; the mail service reads it from OrbCart when the mail goes. Buyer emails →

VAT. Without more, a gift card is multi-purpose: the sale carries no VAT, and the goods the card later pays for do. A card that can be spent on one kind of goods at one rate of VAT is single-purpose: add singlePurpose: true beside giftCard: true and VAT falls on the sale at the offer's tax category. Which of the two a card is, is a statement of yours, not a guess of ours.

Pay at checkout

await cart.enterGiftCard("ABCD-EFGH-JKMP-QRST");
const quote = await cart.quote();
// quote.giftCards shows each card's share; quote.toPay is the amount left for the payment provider.
await quote.pay({ payment: "gift_card" }); // only when gift cards cover the whole purchase

For a part-payment, choose any of the remaining payment methods as usual. Its field or wallet collects only quote.toPay, not the Order's full total. Provider approvals made before checkout, such as PayPal Express, are not offered beside a gift-card payment.

The React Checkout includes a gift-card field. For your own bag, use GiftCard with the Cart returned by useCart, onEnter={bag.enterGiftCard} and onRemove={bag.removeGiftCard}. Remove a card through cart.removeGiftCard(card.id); the code is never needed again.

Cards pay in the order entered, up to their available balance. They cannot buy other gift cards. Their value is reserved when the buyer agrees to a Quote, then redeemed for the Order; a failed or canceled payment releases the reservation. A balance spent elsewhere meanwhile requires a new Quote, never a silently increased provider charge. The unspent balance stays on the card for another checkout or the merchant's desk.

A multi-purpose card changes no prices or VAT: it is payment, not a discount. For single-purpose cards, issuance freezes the country, tax category, rate, face value and VAT actually paid on the sale. The card pays only goods, deposits or shipping with that same country, category and rate; another tax scope cannot use its balance. Until tax is known, it pays nothing of the estimate. The signed Quote keeps that original taxScope and the share of its historical taxPaid, never VAT invented from the redemption basket. This follows the known place of supply and VAT due required by Directive 2016/1065, Article 30a(2). Refunds return the provider's captured share first and restore the rest to the original cards. The refund and card credits keep their own durable keys, so retries never restore value twice.

Refunding a card's original sale is different: automatic refunds require its full face value to be available. Used, reserved or expired cards return gift_card_refund_unavailable for review; this is not a decision about the customer's refund rights. OrbCart reserves the full value before asking for the cash refund. An unknown result keeps it reserved; confirmed success retires the card, while a definite refusal releases it. Expiry during an unknown refund does not change that outcome: the original operation is reconciled with its provider. A refund of one unit retires only that unit's card.

Redeem at a desk

An assigned staff member presents the customer's code and redeems a multi-purpose card through POST /v1/gift-cards/{id}/redemptions, naming the amount and Location. Running checkouts keep their reserved value. The same Idempotency-Key replays the same redemption.

Single-purpose cards return gift_card_desk_unavailable: desk redemption does not yet describe the supply whose tax must match the card. Use checkout for those cards; a Location alone is not proof of a compatible tax scope.

Make a card by hand

Your team makes a card for a goodwill gesture or a prize. In the Admin API:

curl https://commerce.example.com/v1/gift-cards \
  -H "Authorization: Bearer sk_live_…" \
  -H "Idempotency-Key: goodwill-order-4711" \
  -d '{ "amount": 2500, "currency": "EUR", "reason": "Late parcel", "channel": "de" }'

amount is in minor units. reason is for your team and never reaches the buyer. channel may be left out when only one Channel sells in the currency. The same Idempotency-Key again answers the same card, so a retry never makes a second one; the same key with another amount is refused.

GET /v1/gift-cards/{id} shows a card's standing: what it was worth, what it is worth now, what running checkouts have set aside and what orders took off. It never shows the code, only its last four characters.

Set PUBLIC_URL to the API's public base address to offer printable cards, including its mount path when a gateway serves it, such as https://shop.example/api/cart. A merchant-wide staff member can request a fresh signed print link; the link expires after 30 days. Without this setting, issuance still works but printing returns gift_card_print_unavailable.

Set the terms

Terms are yours, not your team's: they change with a deployment, like a Channel.

src/worker.ts
giftCards: {
  codeFormat: { length: 16, alphabet: "readable" },
  validityYears: 3,
  minimum: 500,
  maximum: 50000,
  channels: ["de"],
},
OptionDefaultWhat it does
codeFormat16, readableThe code's length, up to 24; at least 16 for readable or 20 for digits. readable leaves out 0 O 1 I L; digits is only numbers.
validityYears3A card is valid to the end of the year it was issued in, plus these years.
minimum, maximumnoneThe least and the most a card may be worth, in minor units. A gift card offer outside it is unavailable in the Cart; staff cannot make one either.
channelsallThe Channels whose buyers may pay with a card.

A buyer types the code in any spelling: with or without hyphens and spaces, in any case. Looking a card up by its code is limited per network, so nobody can guess codes at speed.

Events

Four events tell what happens to a card. They name the card, its last four characters, the amounts and the Order where applicable, and never the code.

EventWhendata
gift_card.issuedA card came into being, sold or made by your team.giftCard, lastFour, amount, order when sold
gift_card.redeemedAn Order took value off a card.giftCard, lastFour, amount, balance, order
gift_card.creditedA refund put value back on a card.giftCard, lastFour, amount, balance, order
gift_card.voidedA sale refund retired the card's remaining value.giftCard, lastFour, amount, balance

A till or ERP that keeps the books follows these events by their ID, like every other event. Events →

On this page