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 purchaseFor 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.
giftCards: {
codeFormat: { length: 16, alphabet: "readable" },
validityYears: 3,
minimum: 500,
maximum: 50000,
channels: ["de"],
},| Option | Default | What it does |
|---|---|---|
codeFormat | 16, readable | The 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. |
validityYears | 3 | A card is valid to the end of the year it was issued in, plus these years. |
minimum, maximum | none | The 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. |
channels | all | The 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.
| Event | When | data |
|---|---|---|
gift_card.issued | A card came into being, sold or made by your team. | giftCard, lastFour, amount, order when sold |
gift_card.redeemed | An Order took value off a card. | giftCard, lastFour, amount, balance, order |
gift_card.credited | A refund put value back on a card. | giftCard, lastFour, amount, balance, order |
gift_card.voided | A 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 →