Gift cards
Sell your own gift cards. Redeem them at checkout.
Flint's gift card API lets a US business sell, deliver, redeem, and report its own gift cards on the same orders and checkout as everything else it sells. A gift card is a catalog product in a fixed, custom, or discounted amount. When the purchase is paid, Flint issues a 16-character code and emails the recipient on the date the buyer picked. Buyers spend up to 20 cards on one order at hosted checkout, and one payment covers the rest. There is no gift card provider to sign with and no separate gift card vendor.
20
gift cards on one order
POST /v1/orders/{order_id}/gift-cards
$2,000
face value per card, at most
gift_card_configuration.face_value_money
90 days
ahead to schedule the recipient email
recipient.send_at
01Sell
A gift card is a product in your catalog.
Create it in the dashboard under Gift card offers, or with one API call. It sells from the same cart and checkout as everything else, and the variant carries the price, the face value, and the range of amounts a buyer can choose.
curl -X POST https://api.withflintpay.com/v1/products \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Idempotency-Key: product-gift-card" \
-H "Content-Type: application/json" \
-d '{
"name": "Cedar & Stone gift card",
"product_type": "gift_card",
"default_variant": {
"unit_price_money": { "amount": 5000, "currency": "USD" },
"gift_card_configuration": {
"face_value_money": { "amount": 5000, "currency": "USD" },
"price_mode": "face_value",
"custom_amount_bounds": {
"minimum_money": { "amount": 1000, "currency": "USD" },
"maximum_money": { "amount": 50000, "currency": "USD" }
}
}
}
}'A $50 card by default, or any amount from $10 to $500 when the buyer picks their own.
"gift_card_configuration": {
"face_value_money": { "amount": 5000, "currency": "USD" },
"price_mode": "face_value"
}The buyer pays the face value. Omit the configuration entirely and the variant price is the card's value.
"custom_amount_bounds": {
"minimum_money": { "amount": 1000, "currency": "USD" },
"maximum_money": { "amount": 50000, "currency": "USD" }
}Any face value inside your bounds. The price follows the offer's price-to-value ratio.
"unit_price_money": { "amount": 9000, "currency": "USD" },
"gift_card_configuration": {
"face_value_money": { "amount": 10000, "currency": "USD" },
"price_mode": "discounted"
}$100 of value for $90. Flint records both amounts, so your books know what was paid and what is owed.
Gift cards follow gift card rules. They hold USD, carry no tax, and need no shipping or inventory, so checkout skips the address when an order has only gift cards in it. Ordinary cart discounts leave them out, they can’t go in bundles or subscriptions, and a face value can go up to $2,000 a card.
- product_type: gift_card
- gift_card_configuration.price_mode
- custom_amount_bounds
- face_value_money
02Deliver
The recipient gets it on the day the buyer picked.
The buyer adds the recipient's email, a name, and a message of up to 200 characters, and schedules the email up to 90 days ahead. Flint issues the card when the payment settles, then emails a private link to the balance and the code.
curl -X POST https://api.withflintpay.com/v1/orders \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Idempotency-Key: order-gift-card-jordan-001" \
-H "Content-Type: application/json" \
-d '{
"customer_id": "cus_1kmn0aExample",
"line_items": [
{
"variant_id": "var_1kmn0aExample",
"quantity": 1,
"gift_card_purchase": {
"face_value_money": { "amount": 2500, "currency": "USD" },
"recipient": {
"email": "sam@example.com",
"name": "Sam",
"message": "Coffee is on me this year.",
"send_at": "2026-12-24T14:00:00Z"
}
}
}
]
}'The order needs a customer, or a buyer who confirms their email with a code at checkout. The recipient can have a different email from the buyer.
{
"data": {
"order_id": "ord_1kmn0aExample",
"payment_status": "paid",
"line_items": [
{
"order_line_item_id": "li_1kmn0aExample",
"name": "Cedar & Stone gift card",
"quantity": 1,
"gift_card_purchase": {
"reference_price_money": {
"amount": 5000,
"currency": "USD"
},
"face_value_money": { "amount": 2500, "currency": "USD" },
"consideration_money": {
"amount": 2500,
"currency": "USD"
},
"recipient": {
"email": "sam@example.com",
"send_at": "2026-12-24T14:00:00Z"
}
},
"purchased_gift_cards": [
{
"gift_card_id": "gc_1kmn0aExample",
"last_characters": "PQRS",
"unit_ordinal": 1
}
]
}
]
}
}The issued card's id and last characters on the line item that bought it. Ordinary order reads never show the full code.
The full code shows up in two places. Issuing a card returns it once to your server, and the recipient’s private page shows it to Sam. Every other read, log, and webhook shows only the last characters.
The link expires. The money doesn’t. The private link in the email works for 30 days after sending. The balance has no expiry, and Sam can save the card in their account at your store to check it any time.
Nothing is issued early. A card exists once its purchase is paid and settled. A partly paid card stays unissued until the rest is collected, so a card is never live before its price is in.
- gift_card_purchase.recipient
- recipient.send_at
- purchased_gift_cards
- POST /v1/gift-card-notifications
03Redeem
Up to 20 cards on one order. One payment for the rest.
Buyers type codes at Flint's hosted checkout, which applies them, shows what each card covers, and charges the remainder to one payment. In your own checkout, your backend applies each code with the checkout credential, and the order says what the cards cover and what is still due.
curl -X POST https://api.withflintpay.com/v1/orders/ord_2bqr7dExample/gift-cards \
-H "X-Checkout-Session-ID: cs_1kmn0aExample" \
-H "X-Checkout-Session-Secret: ckat_1kmn0aExample" \
-H "Idempotency-Key: apply-gift-card-sam-2" \
-H "Content-Type: application/json" \
-d '{"code": "HJKM-NPQR-STVW-7QXM", "expected_version": 1790760000}'Sent with the checkout credential, never an API key, so Flint can count wrong guesses.
{
"data": {
"order_id": "ord_2bqr7dExample",
"version": 1790760042,
"gift_cards": [
{
"gift_card_id": "gc_1kmn0aExample",
"last_characters": "PQRS",
"available_money": { "amount": 2500, "currency": "USD" },
"requires_authorization": false
},
{
"gift_card_id": "gc_3cst8eExample",
"last_characters": "7QXM",
"available_money": { "amount": 1500, "currency": "USD" },
"requires_authorization": false
}
],
"gift_card_estimate": {
"order_version": 1790760042,
"gift_cards": [
{
"gift_card_id": "gc_1kmn0aExample",
"amount_money": { "amount": 2500, "currency": "USD" }
},
{
"gift_card_id": "gc_3cst8eExample",
"amount_money": { "amount": 1500, "currency": "USD" }
}
],
"gift_card_money": { "amount": 4000, "currency": "USD" },
"processor_money": { "amount": 1304, "currency": "USD" },
"can_pay": true,
"is_reserved": false
}
}
}$40.00 from the two cards and $13.04 left for the card. Selecting a card holds nothing; value is reserved when the buyer pays.
Partial spends keep the rest
A $75 card spent on a $35 order keeps $40 on the card. Each card shows its balance, what is reserved, and what is available, with every change on its own history.
- available_money
- reserved_money
Wrong guesses meet a challenge
After 5 failed codes in one checkout, 10 from one IP address, or 50 across your store within an hour, each lookup needs a proof from a challenge Flint runs. Hosted checkout handles all of it.
- Flint-Gift-Card-Challenge
Saved in the buyer's account
Buyers save a card to their account at your store with its code or the private link, then check its balance and history there.
- POST /v1/me/gift-cards
curl -X DELETE "https://api.withflintpay.com/v1/orders/ord_2bqr7dExample/gift-cards/gc_3cst8eExample?expected_version=1790760042" \
-H "X-Checkout-Session-ID: cs_1kmn0aExample" \
-H "X-Checkout-Session-Secret: ckat_1kmn0aExample" \
-H "Idempotency-Key: remove-gift-card-sam-2"Removal needs the order's current revision, so a stale page can't change an order that moved underneath it.
curl -X POST https://api.withflintpay.com/v1/gift-card-redemptions \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Idempotency-Key: redeem-ticket-5521" \
-H "Content-Type: application/json" \
-d '{
"gift_card_id": "gc_1kmn0aExample",
"amount_money": { "amount": 1200, "currency": "USD" },
"capture_mode": "automatic",
"sale_reference": "ticket-5521"
}'An exact amount from a system of your own, captured at once or held for a later capture. The same ledger, the same balance.
Gift card value is money, not a discount. It pays the order after discounts and tax. It can’t pay for subscription orders or buy another gift card, and in a basket with both, the cards pay for the other goods while the payment covers the new gift card.
- POST /v1/orders/{order_id}/gift-cards
- gift_card_estimate.processor_money
- expected_version
- Flint-Gift-Card-Challenge
04Accounting
What you owe is a report, not a spreadsheet.
Unspent gift card value is money you owe until someone spends it. Flint keeps it on a ledger and gives it back as a monthly roll-forward, gift card sales split from merchandise, refunds that return to the card, and balances imported from the system you are leaving.
| gift_card_liability_v1 · November | ||
|---|---|---|
| Opening liability | $4,820.00 | |
| Cards sold or reloaded | $1,175.00 | |
| Balances imported | $600.00 | |
| Spent by buyers | $1,340.00 | |
| Closing liability | $5,255.00 | |
curl -X POST https://api.withflintpay.com/v1/reports \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Idempotency-Key: gift-card-liability-2026-11" \
-H "Content-Type: application/json" \
-d '{
"report_type": "gift_card_liability_v1",
"interval_start_at": "2026-11-01T00:00:00Z",
"interval_end_at": "2026-12-01T00:00:00Z",
"currency": "USD"
}'Fixed at a snapshot, so a retried report returns the same totals.
curl -X POST https://api.withflintpay.com/v1/gift-cards \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Idempotency-Key: import-legacy-48213" \
-H "Content-Type: application/json" \
-d '{
"currency": "USD",
"external_reference_id": "legacy-48213",
"funding": {
"source": {
"funding_source_type": "import",
"external_reference_id": "legacy-48213"
},
"value_money": { "amount": 4250, "currency": "USD" }
}
}'Each card from your old system becomes a Flint card with the same remaining value.
{
"data": {
"gift_card_id": "gc_4dtu9fExample",
"status": "active",
"balance_money": { "amount": 4250, "currency": "USD" },
"available_money": { "amount": 4250, "currency": "USD" },
"last_characters": "WXYZ",
"code": "MNPQ-RSTV-UVHJ-WXYZ",
"secret_recovery_expires_at": "2026-10-16T15:04:05Z",
"gift_card_transaction_ids": ["gct_1kmn0aExample"]
}
}The new code comes back once. A retry with the same key returns it for 24 hours. Retire the old balance so it can't be spent twice.
Refunds return to the card
Refunding an order paid by gift card puts the value back on the original card first. Send tender allocations to choose the split yourself.
- tender_allocations
Sales apart from merchandise
The itemized order report separates what buyers paid for gift cards from what they bought, so a card's sale and its later spend aren't counted twice.
- orders_itemized_v2
State cash-out rules
Some states require paying out a small remaining balance on request. Pay the buyer outside Flint, then record the cash-out against the card.
- POST /v1/gift-cards/{gift_card_id}/cash-outs
Events to subscribe to
- gift_card.created
- gift_card_load.created
- gift_card_notification.updated
- gift_card_redemption.created
- gift_card_transaction.created
Card statuses
- pending
- active
- frozen
- closed
- gift_card_liability_v1
- orders_itemized_v2
- funding_source_type: import
- POST /v1/gift-cards/{gift_card_id}/cash-outs
05Compared
Gift cards with Stripe, Square, and Flint.
Stripe's gift card support is a private preview for accepting closed-loop cards from a gift card provider you already have an agreement with, through the Payment Intents API and Terminal readers, and those redemptions settle off Stripe. Square sells gift cards to businesses that run on Square. Flint gives you your own gift cards in the same order and checkout system, with card processing on Stripe underneath.
| What you need | Stripe gift card payments | Square eGift Cards | Flint gift cards |
|---|---|---|---|
| How you get it | Stripe: A private preview you request from Stripe | Square: Part of running your business on Square | Flint: Part of the Flint API, with gift card offers in the dashboard |
| Who else you need | Stripe: A gift card provider you already have an agreement with; SVS is the listed one | Square: Square's own ordering page, online store, and point of sale | Flint: Nobody. Flint issues the cards and keeps the ledger |
| Where buyers buy a card | Stripe: Activation, reloads, and balance checks through the API | Square: A Square eGift Cards ordering page | Flint: Your checkout, as a catalog product in fixed, custom, or discounted amounts |
| Where buyers spend it | Stripe: The Payment Intents API and Terminal readers | Square: Square Online or Square Point of Sale | Flint: Hosted checkout, up to 20 cards plus one payment, or your own checkout through the API |
Selling your own gift cards on Stripe today? Without a provider, the usual workaround is a coupon with a single-use promotion code for every card sold, and a balance ledger you keep yourself. A Stripe Checkout Session takes one coupon or promotion code, so a buyer holding two cards can’t use both on one order, and a used code doesn’t remember what was left on it. Stripe gift cards: sell and redeem your own covers the workaround, where it breaks, and the Flint requests that replace it.
06Who it's built for
US businesses selling online in USD.
Shops, roasters, restaurants, studios, and service businesses that sell on their own website or app and want gift cards on the same orders, checkout, and buyer account as everything else they sell.
US businesses
Flint serves merchants in the United States. Buyers can pay with cards from anywhere.
USD value
Cards hold USD, issued by your business and spendable only with your business.
Online and in your app
Hosted checkout, your own checkout through the API, and redemptions from systems of your own.
Purchased gift cards
Cards buyers pay for. Promotional gift card products and general store credit aren't offered.
07Proof
What you stop building.
A gift card is a catalog product with a fixed, custom, or discounted amount.
gift_card_configuration.price_modeThe card is issued when its purchase is paid and settled, never before.
line_items[].purchased_gift_cardsThe recipient email goes out on the date the buyer picked, up to 90 days ahead.
recipient.send_atUp to 20 cards apply to one order, and the estimate says what the payment still covers.
gift_card_estimate.processor_moneyA stale page can't take a card off an order that changed.
expected_versionRepeated wrong codes require a challenge before more lookups.
GIFT_CARD_CHALLENGE_REQUIREDRefunds return value to the original card first.
tender_allocationsThe liability rolls forward in a report you can hand to your accountant.
gift_card_liability_v1reviewed 2026-10-15 against the gift cards API reference · corrections: Flint Help
08Start
Sell a test gift card, then spend it.
Node
CLI
Create a gift card product with a sandbox key and buy one at hosted checkout with 4242 4242 4242 4242 and any future expiry. Or issue a test card with POST /v1/gift-cards and import funding, which returns its code. Then apply the code to a second order and see the estimate split the total between the card and the payment.
Then read these
- 01
- 02
- 03
- 04
- 05
- 06
From a terminal, npm install -g @flintpay/cli && flint signup creates your account and a sandbox key. CLI guide
Sources
Where each outside claim comes from.
Stripe's gift card payments are a private preview requested from Stripe. They need an existing agreement with a gift card provider (SVS is the listed provider), serve US customers in USD, integrate through the Payment Intents API and Terminal, and settle redemptions off Stripe. Stripe docs: Gift card payments
docs.stripe.com · checked 2026-10-15A Checkout Session's discounts parameter takes a coupon or promotion code, and only one may be specified. Stripe API reference: Create a Checkout Session
docs.stripe.com · checked 2026-10-15Square sells gift cards to businesses that run on Square. eGift Cards are bought from a Square eGift Cards ordering page and redeemed on Square Online or Square Point of Sale. Square: Gift cards
squareup.com · checked 2026-10-15
last reviewed 2026-10-15 · corrections: Flint Help
FAQ
Questions people ask about gift cards.
Does Flint have a gift card API?
Yes. Flint's gift card API sells, issues, redeems, and reports merchant-issued USD gift cards on the same orders and checkout as everything else you sell. A gift card is a catalog product in a fixed, custom, or discounted amount. Flint issues a 16-character code when the purchase is paid, emails the recipient on the date the buyer picks, and lets buyers apply up to 20 cards to one order at hosted checkout or through the API.
Can I sell gift cards with Stripe?
Stripe’s gift card support is a private preview for accepting closed-loop gift cards from a gift card provider you already have an agreement with, with SVS as the listed provider, through the Payment Intents API and Terminal readers. Those redemptions settle off Stripe. To sell their own cards without a provider, Stripe sellers commonly issue a coupon with a single-use promotion code for each card and track balances themselves. Flint runs card processing on Stripe and adds gift cards as catalog products with a balance ledger. Stripe gift cards: sell and redeem your own walks through both.
How does the recipient get the gift card?
The buyer enters the recipient's email, an optional name, and a message of up to 200 characters, and can schedule the email up to 90 days ahead. When the payment settles, Flint issues the card and emails a private link that shows the balance and the code. The link stays valid for 30 days after sending, the balance doesn't expire, and the recipient can save the card in their account at your store.
Can a buyer use more than one gift card on an order?
Yes. Hosted checkout applies up to 20 gift cards to one order, and one payment covers whatever the cards don't. A card spent on a smaller order keeps its remaining balance. Gift card value pays after discounts and tax, can't pay for subscription orders, and can't buy another gift card.
Do Flint gift cards expire or carry fees?
No. Purchased Flint gift cards have no expiry date and no fees. They hold USD value issued by your business and spendable only with your business, with face values up to $2,000 a card. Where state law requires cashing out a small remaining balance on request, you pay the buyer and record the cash-out against the card.
Can I move gift card balances from another system?
Yes. Create a card for each remaining balance with POST /v1/gift-cards and import funding, and Flint returns a new code to give the holder. Retire the balance in the old system so it can’t be spent in both places.
Is Flint a good alternative to Stripe or Square for gift cards?
Yes, for US businesses selling online in USD that want to sell and redeem their own gift cards without a gift card provider contract, a coupon workaround, or moving the business onto Square. Gift cards, orders, checkout, the buyer account, and the liability report are one system, and card processing runs on Stripe underneath.