Gift cards
Gift cards hold purchased value issued by one merchant, in USD. They work only with that merchant and environment. Purchased cards have no expiry or fees. Refunds can issue store credit as new gift cards. Promotional gift card products, customer-bound credit balances, transfers, and cross-merchant spending are not supported. To add unpaid value to a card, use a positive adjustment with reason complimentary.
You can issue, load, redeem, and reconcile cards without a Flint order. Hosted checkout uses the same ledger and can apply up to 20 cards alongside one processor payment. Gift card value pays the order after discounts and tax; it is not a discount. Gift card value cannot pay for subscription orders. Existing gift card value cannot fund a new gift card purchase. In a mixed basket, it can pay for eligible merchandise. Sell, redeem, and refund gift cards walks through the calls in order.
Save a card in a buyer account#
A buyer with a full customer session can save a card with POST /v1/me/gift-cards. The session determines the buyer, merchant, and environment; do not pass identity selectors. Reads and removal accept no request body. Provide one possession proof:
{ "credential_type": "code", "code": "GIFT_CARD_CODE" }
Or provide credential_type: "recipient_access", grant_id, and recipient_access_token from the original private recipient link. The grant ID is in the link's path and the token is in its fragment. Do not send both proof types or extra fields. Parse pasted links locally without fetching their URL, and keep codes and tokens out of navigation, browser storage, and telemetry.
Imported-code cards cannot be saved by code; use a private recipient link instead. They can still be spent in checkout.
Saving an active or frozen card, including one with no remaining balance, adds it to the buyer's saved collection. Several buyers may save the same card. Saving does not change customer_id, move funds, reveal the full code, or authorize checkout spending. Buying a card or matching its recipient email does not grant saved access. Order, invoice, return, and subscription sessions cannot use these endpoints.
GET /v1/me/gift-cards lists saved cards with current access. GET /v1/me/gift-cards/{gift_card_id} returns the card's masked identifier, status, balance, reserved amount, available amount, and timestamps. Existing saved cards remain readable after being frozen or closed. Replacing the code removes them from the list and makes detail and history reads return 404 until the buyer saves again with fresh proof. Expiry of the original private link does not expire previously saved access.
GET /v1/me/gift-card-transactions?gift_card_id={gift_card_id} returns the full anonymous balance-change history for a card the authenticated buyer has saved, including changes made by other holders. A card the buyer has not saved returns 404. Each entry includes its per-card sequence, signed amount, balance before and after, and posting time. Customer identities, order and payment references, source identifiers, reasons, and command keys are omitted.
Both lists take page_size and page_token, with a default of 20 and a maximum of 100. Cards sort by saved time, then card ID, descending. History sorts by per-card sequence, descending. Continue with the same page size and authenticated buyer. History tokens also require the same gift_card_id and saved credential version.
DELETE /v1/me/gift-cards/{gift_card_id} removes only that buyer's saved access. Save returns 201 and remove returns 200 with the card as the buyer saw it before removal. A duplicate save returns the saved card without adding another entry. Once access is removed, the buyer gets 404 for that card, so a repeated removal without the original Idempotency-Key returns 404, and a buyer who never saved the card learns nothing about it. Both writes accept an optional Idempotency-Key, scoped to the buyer, merchant, environment, and operation. A replay cannot restore removed or revoked access. Removing and re-adding a card requires a new save key.
Issue and recover a card#
Create a card with currency: USD and optional funding. Unfunded cards remain pending. Funding records value_money, the face value issued, separately from consideration_money, the amount paid. external_payment funding requires a source.customer_id for a customer in the environment, an external_reference_id, and consideration_money. import funding requires an external_reference_id; customer_id and consideration_money are optional. source.external_reference_id is your reference for the payment or import record, such as a POS sale ID. Supply an optional top-level code only with import funding to keep the original code. It must contain 16 gift card alphabet characters after removing spaces and hyphens. A code already assigned to a card in the same merchant environment returns 409 ALREADY_EXISTS at code. Retire an imported balance in the source system so it cannot be spent in both places. References record activity outside Flint and do not mean Flint processed a payment. flint_payment funding requires a succeeded standalone payment intent from the same merchant, with enough unrefunded captured value to cover consideration_money. Manual-payment funding is created only through an order.
External references on cards and funding sources, a redemption's sale_reference, and a cash-out's cash_out_reference accept 1 to 255 characters, counted as characters rather than bytes. Flint stores them exactly as sent, including whitespace and letter case.
Commands that move value require a caller-chosen Idempotency-Key: issuing a card, loads, balance adjustments, cash-outs, redemptions, and funding dispositions. Retain and reuse the same key after a timeout. Replaying identical input returns the original operation; changing input with that key produces a conflict. Flint keeps these keys for as long as the ledger exists, so a lost response can always be recovered by replaying the original request. Loads, redemptions, transactions, and funding dispositions can also be listed with an idempotency_key filter, which matches only keys you sent. Other gift card writes, such as updates, freeze, unfreeze, close, code rotation, notifications, and redemption capture and cancel, accept an optional key. Flint keeps a key you send them for as long as the ledger exists too; without one, each request runs once and can't be replayed.
When you supply an imported code, issuance omits data.code and data.code_recovery_expires_at, including on replays. GiftCard.code_source is imported for a supplied code and generated for a Flint-issued code; code rotation resets it to generated.
Issuance with a generated code and code rotation return the full code once, as data.code with data.code_recovery_expires_at. Replaying the same request returns it again for 24 hours. After that, or once the code has been replaced by a later rotation, a replay still returns the result but omits code and code_recovery_expires_at, because the old code no longer works. Other reads, logs, and webhooks show only last4, the last four characters of the current code. The recipient's private access page is the only other place the full code appears. Store codes as credentials. Never put them in URLs or logs. Lookup uses a JSON request body. Code rotation revokes old credentials and recipient links while preserving balances and protecting already-reserved payments. It cancels scheduled and pending notifications for the previous code when sending has not started, with status_reason: credential_rotated. Notifications already being sent or accepted by the email service are left as they are. Send a replacement notification if needed, either in the rotation request or with a new notification request after rotation.
Codes have 16 normalized ASCII characters, for example 0000-0000-0000-0000 in a synthetic test. Every code input trims surrounding whitespace, ignores ASCII spaces and hyphens, accepts ASCII letter case, maps O to 0, and maps I and L to 1. It rejects Unicode and does not support prefix matching.
To keep an existing code while importing its balance:
{"currency":"USD","code":"7783 3200 0100 1635","funding":{"value_money":{"amount":3750,"currency":"USD"},"source":{"funding_source_type":"import","external_reference_id":"legacy-card-001"}}}
Rotate imported codes when you can reach their holders, and delete migration exports after completing the import.
Create a load with POST /v1/gift-card-loads, sending gift_card_id, value_money, and source in the body. Funding uses the same source rules as issuance. Send the card's version as optional expected_gift_card_version to reject a concurrent card change. GET /v1/gift-card-loads?gift_card_id={gift_card_id} lists loads for exactly that card; GET /v1/gift-card-loads/{gift_card_load_id} retrieves one load.
What each command returns#
A command that changes one card's value returns a result object in data. Every result has gift_card, the card after the command, and gift_card_transactions, the full transactions the command posted, in posting order (sequence ascending). gift_card_transactions is [] when the command posted nothing. A command that creates or changes a load or redemption also returns it, as gift_card_load or gift_card_redemption.
| Command | Status | data | Version fence |
|---|---|---|---|
POST /v1/gift-cards | 201 | gift_card, gift_card_transactions, gift_card_load when you send funding, gift_card_notification when you send notification, and code with code_recovery_expires_at only for a generated code | None |
POST /v1/gift-cards/{gift_card_id}/rotate-code | 200 | gift_card, code, code_recovery_expires_at, and gift_card_notification when you send notification. Rotation posts nothing, so there is no gift_card_transactions | expected_version: data.gift_card.version |
POST /v1/gift-card-loads | 201 | gift_card_load, gift_card, gift_card_transactions | expected_gift_card_version: data.gift_card.version |
POST /v1/gift-cards/{gift_card_id}/adjust-balance | 200 | gift_card, gift_card_transactions, and gift_card_load for a positive adjustment | expected_version: data.gift_card.version |
POST /v1/gift-cards/{gift_card_id}/cash-out | 200 | gift_card, gift_card_transactions | expected_version: data.gift_card.version |
POST /v1/gift-card-redemptions | 201 | gift_card_redemption, gift_card, gift_card_transactions ([] for manual capture until you capture) | expected_gift_card_version: data.gift_card.version |
POST /v1/gift-card-redemptions/{gift_card_redemption_id}/capture or /cancel | 200 | gift_card_redemption, gift_card, gift_card_transactions | expected_version: data.gift_card_redemption.version |
PATCH /v1/gift-cards/{gift_card_id}, POST /v1/gift-cards/{gift_card_id}/freeze, /unfreeze, or /close | 200 | The gift card, which posts nothing | expected_version: data.version |
POST /v1/gift-card-notifications | 201 | The notification | None |
POST /v1/gift-card-notifications/{gift_card_notification_id}/cancel | 200 | The notification | None |
Replaying a command with the same Idempotency-Key returns the same transactions, with the same IDs and balance snapshots, and posts nothing again. Capture, cancel, and notification cancel accept an empty body.
Concurrency#
Send the version from your read to reject a command if its target changed. Load and redemption creates take expected_gift_card_version, which checks the card named by gift_card_id in the body. Other card commands (update, freeze, unfreeze, close, code rotation, balance adjustments, cash-outs) take expected_version to check the card. Capture and cancel take expected_version to check the redemption. The last column of the table above lists each fence. A mismatch returns 409 VERSION_CONFLICT with the current version in details[0].current_version. details[0].resource_type and resource_id name the resource that carries the version: the gift_card for card commands and for redemption create, where the card is the gift_card_id in the body, and the gift_card_redemption for capture and cancel. Other state conflicts return 409 ACTION_NOT_ALLOWED. In details[0], reason is terminal_status when current_status is closed or the resource is a gift card notification, restricted when a freeze or funding dispute blocks a cash-out or redemption, unsupported_state for another recorded lifecycle status, or not_offered when no lifecycle status applies. When present, current_status gives the blocking resource's status.
Available actions#
Merchant gift cards, redemptions, and notifications always include supported_actions, with [] when no lifecycle action is available. Flint derives it from stored state, independently of your credential or scopes. Reads, command results, and webhook snapshots carry the same list for the same state. Your credential still needs the action's scope; an available action without the required scope returns 403 INSUFFICIENT_SCOPE.
| Resource | Action | Route |
|---|---|---|
| Gift card | freeze | POST /v1/gift-cards/{gift_card_id}/freeze |
| Gift card | unfreeze | POST /v1/gift-cards/{gift_card_id}/unfreeze |
| Gift card | close | POST /v1/gift-cards/{gift_card_id}/close |
| Gift card | adjust_balance | POST /v1/gift-cards/{gift_card_id}/adjust-balance |
| Gift card | cash_out | POST /v1/gift-cards/{gift_card_id}/cash-out |
| Redemption | capture | POST /v1/gift-card-redemptions/{gift_card_redemption_id}/capture |
| Redemption | cancel | POST /v1/gift-card-redemptions/{gift_card_redemption_id}/cancel |
| Notification | cancel | POST /v1/gift-card-notifications/{gift_card_notification_id}/cancel |
An action appears only when state permits it. adjust_balance describes the balance-adjustment command; its amount, reason, and funding limits still have to be valid. cash_out appears only when the card has value and has no freeze, restriction, or unresolved funding dispute; the requested amount must fit its unreserved value. Creating loads or notifications, looking up a code, and rotating a code aren't listed in supported_actions.
Funding limits#
Funding limits apply to issued and loaded value, including external payments, imports, and positive adjustments. Refunds restored to a card do not count. Daily limits reset at 00:00 UTC.
| Limit | Amount |
|---|---|
| Balance of one card | $2,000.00 |
| Value added to one card per day | $2,000.00 |
| Value added for one buyer per day, across cards. Pending gift card purchases count. | $10,000.00 |
Imports without a customer_id, per environment per day | $10,000.00 |
| Positive adjustments, per environment per day | $10,000.00 |
A load, import, or adjustment that would exceed a limit returns 409 LIMIT_EXCEEDED. In details[0], reason names the limit (card_balance, card_daily, buyer_daily, merchant_imports_daily, or merchant_adjustments_daily), maximum_money is the remaining amount you can add, and current_money is the amount already counted toward the limit. The message gives the remaining amount and, for daily limits, when the limit resets.
Reserve and redeem value#
balance_money is posted value, including reservations. reserved_money is value held by manual-capture redemptions; it is unrelated to a balance's reserve_money. available_money is the spendable remainder. A freeze prevents new spending and retains the balance. Closing requires resolving remaining value and protected reservations. It cannot erase money.
A redemption that exceeds available value returns 409 LIMIT_EXCEEDED, with param: amount_money, details[0].reason: insufficient_available_value, and details[0].maximum_money containing the available amount and currency when Flint tried to reserve it. This amount can be zero. remediation.retry is none: collect the rest of the payment another way, or submit a new redemption for up to that amount. Availability can change before the new request. A checkout whose accepted gift card allocation has changed still requires a refreshed allocation; that error does not include this bound.
A card's restrictions lists what keeps it frozen, and is [] when nothing does. A merchant_freeze restriction comes from POST /v1/gift-cards/{gift_card_id}/freeze, which takes a reason: suspicious_activity, customer_request, or support_issue. POST /v1/gift-cards/{gift_card_id}/unfreeze removes the merchant freeze. POST /v1/gift-cards/{gift_card_id}/close permanently closes a card once its remaining value and reservations are resolved. All three take an optional expected_version; none takes an action field. A funding_dispute restriction names the dispute_id on a payment that funded value on the card, with dispute_status open or lost. supported_actions includes unfreeze only when every restriction is a merchant_freeze. Treat a restriction type you don't recognize as one you can't clear.
A cash-out or redemption blocked by a freeze, restriction, or unresolved funding dispute returns 409 ACTION_NOT_ALLOWED with details[0].reason: restricted. details[0].restrictions has the same shape as the card's restrictions. Funding disputes also appear in details[0].blocking_resources as resource_type: dispute when your credential can read disputes. remediation.retry is none and error_source is merchant: lift the merchant freeze, or resolve the funding dispute, before retrying.
Create a redemption with gift_card_id, an amount, a sale_reference, and capture_mode. Send optional expected_gift_card_version to check the card's version on create. sale_reference is your reference for the sale the redemption pays for, from 1 to 255 characters. Redemptions you create return it, and GET /v1/gift-card-redemptions?sale_reference= finds them by it. A redemption from a Flint order's payment has sale_reference: null and names its payment attempt in order_payment_attempt_id, which is null on redemptions you create. Automatic capture posts the spend immediately and returns status: "succeeded". Manual capture creates a reserved redemption that you later capture to succeeded or cancel to canceled; add expected_version to reject a concurrent change. Reservations last 15 minutes by default and up to 24 hours. An automatic redemption has expires_at: null. source_type is external for redemptions you create and flint_order for redemptions from a Flint order's payment. Expiry cannot release money behind a payment whose outcome is still unknown. Retrieve the existing redemption to recover its state before issuing another command.
Applying a card to an order returns an estimate. Accept the exact order_version, card allocations, and processor remainder when paying. Any change, up or down, returns 409 VERSION_CONFLICT with param: accepted_gift_card_allocation; refresh the estimate and get the buyer's acceptance again before sending a new request with a new Idempotency-Key. Gift-card-only payment settles without a processor charge.
Refunds and funding losses#
To refund a sale you redeemed with POST /v1/gift-card-redemptions, create a refund with refund_type: "amount", an amount_money, and one tender_allocations entry per redemption, with no order_id. Each entry needs tender_type: "gift_card_redemption", the gift_card_redemption_id, and an amount_money no larger than the redemption's remaining_refundable_money. Put your POS return ID in external_reference_id. The refund credits the card that paid and adds a refund transaction whose source is the refund's allocation. A redemption stays succeeded; refunded_money grows with each refund. Don't use adjust-balance for returns: an adjustment has no link to the sale and counts toward funding limits.
Send this body to POST /v1/refunds with Idempotency-Key: pos-return-8841:
{
"refund_type": "amount",
"amount_money": {"amount": 2500, "currency": "USD"},
"tender_allocations": [
{
"tender_type": "gift_card_redemption",
"gift_card_redemption_id": "gcr_01K...",
"amount_money": {"amount": 2500, "currency": "USD"}
}
],
"external_reference_id": "pos-return-8841",
"reason": "requested_by_customer",
"metadata": {"register": "3"}
}
Refund merchandise through the refund API. Without tender_allocations, an order refund returns value to the original gift cards first; send tender_allocations with refund_type: "amount" and an amount_money that equals their sum to choose gift card redemptions or processor payments yourself. Each original tender has a cumulative refund cap. The default destination, original, restores the original card. If that card is closed or cannot accept the full allocation, explicitly authorize new_gift_card as the destination. Value moved to a new card retains its funding provenance and risk restrictions; it does not become a newly paid load. Replays recover the same destinations.
Set new_gift_card on a payment allocation, or destinations.payment_intent, to refund a card, Apple Pay, Google Pay, or Link payment as store credit. Flint issues new cards for the value and makes no processor refund, so you keep the cash and the processing fee is not returned. The new card's load has source.funding_source_type: "store_credit" with the original payment_intent_id, order_id, and the refund_id, and the card carries the order's customer_id. A dispute on the original payment freezes the card like any other payment-funded value. You can't create or load a card with store_credit, and a store credit load can't be refunded as a gift card purchase.
Refunding a gift card purchase removes eligible unspent value from its funding load, including value restored through linked merchandise refunds. Spent or reserved value causes a conflict. Unknown provider refund outcomes remain protected until reconciled. Purchase refunds and manual-payment reversals do not use an ordinary balance adjustment to hide unavailable value.
After reversing a manual payment for a gift card purchase, collecting the outstanding amount through a processor or another manual payment restores the reversed value. The purchase keeps its original unit identities. If restoration requires a replacement card, purchased_gift_cards links it to the original card with restoration_reason: processor_recollection or manual_recollection, according to the new payment.
An open or lost dispute on a funding payment freezes the whole card and adds a funding_dispute entry to its restrictions. Value from other loads keeps its provenance but cannot be spent or cashed out until the dispute is won or its loss is honored. Winning clears only that dispute's restriction. A restriction with dispute_status: lost needs a gift card funding disposition: create one with its dispute_id and a reason_message. disposition defaults to honor_value, the only disposition. Use commerce.gift_cards.adjustments.write and a durable Idempotency-Key. The 201 response returns the GiftCardFundingDisposition directly in data, including the disputed amount, original consideration, honored value, and preserved reservations. Unknown disputes return 404; disputes without an eligible funding loss return 409. Retrieve a disposition with GET /v1/gift-card-funding-dispositions/{gift_card_funding_disposition_id}, or list them filtered by dispute_id or idempotency_key. Cash-out records require a reference for the cash you paid outside Flint; recording one does not send cash to the buyer.
Recipient email#
Creating or rotating a card does not send an email unless you explicitly supply notification. Otherwise, create a notification with the card ID and recipient. Notifications use the current credential version and do not issue value, activate a card, or fulfill an order. Recipient email is required; name is optional, the message can contain up to 200 characters, and send_at can schedule up to 90 days ahead.
Notification status uses the closed message_status vocabulary and emits only these values:
| Status | Meaning |
|---|---|
scheduled | Waiting for the recipient's chosen send time. |
pending | Waiting to send, or sending now. A notification for a pending card waits until the card is funded. |
sent | Flint's email service accepted the message. This doesn't mean the recipient opened it. |
failed | Sending failed, or the recipient's email service bounced the message. |
unconfirmed | Flint's email service didn't confirm whether it sent the message. Flint doesn't resend it automatically. |
canceled | Cancellation stopped further sending. |
Retrieve the notification for its recent delivery.attempts and delivery.events; list responses omit delivery. An attempt's status is pending while its outcome is awaited, sent when the email service accepts it, failed when it fails, or unconfirmed when the attempt ends without a confirmed outcome. An event's type is accepted (Flint's email service accepted the message for delivery), delivered, bounced, or dropped, and its delivery_attempt_id names the attempt it belongs to. A bounce remains visible as a bounced event even though notification status is failed. Each retrieval returns up to 20 attempts and 50 events, newest first, and has_more_attempts and has_more_events are true when older records exist. After an outcome resolves, an explicit resend uses resend_of_notification_id and a new command identity.
Cancel with POST /v1/gift-card-notifications/{gift_card_notification_id}/cancel when supported_actions includes cancel. Once sending starts, cancellation returns a conflict even though status remains pending. Read supported_actions rather than deciding from status alone.
Recipient email opens private hosted access valid for 30 days from sending. Expiring or revoking that access does not expire the card's funds. Changing a credential revokes old access. Issuing and loading, spending, and adjustments and cash-outs have separate scopes. Recipient email and code replacement both require commerce.gift_cards.secrets.write; grant each scope only to callers that need it.
Reconcile#
List gift cards, loads, redemptions, notifications, and funding dispositions with created_after and created_before to filter created_at. Filter gift cards by status, external_reference_id, or customer_id, which returns the cards associated with that customer; retrieve one card by its ID with GET /v1/gift-cards/{gift_card_id}. Filter loads by funding_source_type and source_external_reference_id, matching source.funding_source_type and source.external_reference_id. Use posted_after and posted_before on the merchant-wide transaction feed to filter posted_at. Bounds are RFC 3339 timestamps; _after is inclusive and _before is exclusive. Money fields use the shared Money schema; transaction amounts and adjustment inputs use SignedMoney because they can be negative. Gift cards use USD.
The redemption status filter accepts reserved, succeeded, canceled, and expired. The notification status filter accepts scheduled, pending, sent, failed, unconfirmed, and canceled. pending matches both notifications waiting to send and those already sending; failed includes bounced notifications.
Timestamps use whole seconds in UTC with Z. Fractional seconds in request timestamps, including recipient.send_at, are truncated.
Use the merchant-wide transaction feed to reconcile postings by card, source, order, period, or durable command key. Transactions are immutable and expose balance before and after each posting. A transaction's idempotency_key is the Idempotency-Key you sent on the command that posted it. It is null when Flint posted the transaction, as for a refund to a card or an order's gift card payment, and when an optional-key command ran without a key. Loads and redemptions follow the same rule. The idempotency_key list filters match only keys you sent, so a Flint-posted record never matches. reason is your reason on an adjustment and customer_request on a cash_out; it is null on every other type, including funding_loss_accepted. Neither field uses an empty string for a missing value. Reservations and notification events do not change posted liability.
Each transaction's source names the record that posted it, as a resource_type and resource_id: a gift_card_load, gift_card_redemption, gift_card_funding_disposition, refund_allocation (a refund's share paid back to the card, listed in the refund's tender_allocations), or purchase_refund_allocation (an entry in a load's purchase_refunds, for a refund of the card's purchase). source is null on adjustments and cash-outs, because the transaction is the record. transaction_type says what the posting did. Filter the feed with source_type and source_id, which match source.resource_type and source.resource_id, or with transaction_type, which takes several values: ?transaction_type=adjustment,cash_out returns adjustments and cash-outs.
Subscribe to gift_card.*, gift_card_load.*, gift_card_notification.*, gift_card_redemption.*, and gift_card_transaction.created events. Set enabled_events to exact event names, such as gift_card_notification.created and gift_card_notification.updated, to receive only those events. Card, redemption, and notification snapshots include supported_actions at the time of the event. Notification events carry a snapshot of the recipient, status, and notification version; retrieve the notification for current delivery history. A refund sends refund.created, and the redemption, card, loads, and transactions it changed send their own updated and created events. Delivery is at least once and can arrive out of order. Deduplicate by event ID, compare resource versions, and retrieve current state when needed. Events never include full codes or recipient access secrets.
Use gift_card_liability_v1 for a fixed liability roll-forward and orders_itemized_v2 to separate gift card purchase consideration from merchandise. A $25 card sold for $22 adds $25 of face value and records $22 of consideration; its later redemption pays for merchandise. Do not count cash collected at issuance as another merchandise sale. See reports for report boundaries and columns.
Cash-out eligibility#
Check that supported_actions includes cash_out before paying the holder. Any freeze, restriction, or unresolved funding dispute prevents recording a cash-out, including when the requested value came from an undisputed load. Lift the merchant freeze or resolve the funding dispute first; there is no override.
The merchant pays the customer outside Flint, then records the completed cash payment with POST /v1/gift-cards/{gift_card_id}/cash-out. The required cash_out_reference is your reference for that payment, such as a check number or transfer ID. The cash_out transaction carries it as cash_out_reference, which is null on every other transaction type, and GET /v1/gift-card-transactions?cash_out_reference= finds it. A cash-out is a balance debit, separate from a merchandise refund or a refund of the card's purchase. Its amount cannot exceed unreserved value. Recording a larger voluntary cash payment is supported; these thresholds are eligibility floors, not maximum ledger debits.
State law sets the minimum: a remaining balance under the state's threshold must be paid out on request. Your policy can cover larger balances but not fewer. State rules include conditions and exclusions, and the state that governs an online sale needs legal review. The following table covers purchased, single-merchant cards and was checked on October 2, 2026.
| State | Remaining balance eligible on request | Conditions and source |
|---|---|---|
| California | Less than $15 | Operative April 1, 2026. Civil Code 1749.5 |
| Colorado | $5 or less | Single-merchant cards. C.R.S. 6-1-722 |
| Connecticut | Less than $5 | After a purchase; the statute has exclusions, including some discounted cards and out-of-state retailers. Consumer protection guidance |
| Hawaii | Less than $5 | Consumer protection guidance |
| Maine | Less than $5 | After an in-person redemption; original value must exceed $5. 33 M.R.S. 2067 |
| Massachusetts | $5 or less for a reloadable card; otherwise after at least 90% of its value has been redeemed | Retail rights guide, gift certificate guidance |
| Montana | Less than $5 | Original value must exceed $5. MCA 30-14-108 |
| New Jersey | Less than $5 | After redemption. Cash balance redemption guidance |
| New York | Less than $5 | Division of Consumer Protection guidance |
| Oregon | $5 or less | Most cards after a purchase; consult the linked guidance for exceptions. Department of Justice guidance |
| Rhode Island | Less than $1 | Remaining value after redemption. R.I. Gen. Laws 6-13-12 |
| Vermont | Less than $1 | 8 V.S.A. 2704 |
| Washington | Less than $5 | Remaining value after a purchase. RCW 19.240.020 |
Checkout credential verification#
Failed gift card guesses are counted independently for the checkout session, client IP and merchant environment. Each count runs for one hour from its first failure. After five session failures, ten IP failures, or fifty merchant failures, every checkout lookup in that hour requires a single-use proof, even with a valid code. API keys and installed integrations are not challenged, so apply buyer-entered codes with the checkout credential. Buyers get the same 400 INVALID_REQUEST refusal with detail code INVALID_VALUE on code for unknown, other-merchant, and inactive codes.
Get a proof from the challenge at gift_card_challenge.url, which an open checkout session returns on a single read, or from remediation.next_actions[].url on the error. Load that page in an iframe on the session's page_origin. When the buyer passes, it posts a proof to your page. Send the proof in Flint-Gift-Card-Challenge and repeat the same apply request, with the same Idempotency-Key. A proof is valid for five minutes, works only for its checkout session, and authorizes one lookup. Flint spends it before the lookup, so it is used even if the code turns out to be unavailable. While a challenge is required, every apply request needs a new proof, including a retry after any error. A retry that replays a recorded success doesn't spend its proof. A value that isn't a proof Flint issued, including a Cloudflare Turnstile token, is rejected.
GIFT_CARD_CHALLENGE_REQUIRED carries a reason in details[0]: proof_required when no proof was sent, proof_rejected when the proof is malformed, unknown, expired, used, or issued for another session, merchant, environment, or mode, and page_origin_required when an embedded session has no page_origin and can't show the challenge. The first two include one complete_gift_card_challenge next action with the page's URL. A sandbox challenge always passes and follows the same proof rules. The challenge is separate from the spending code and is never part of the financial command identity. Build your own checkout covers the iframe, the messages, and retry; Flint's hosted checkout does all of it for you.
A dashboard session must have verified its strongest available sign-in factor within the last five minutes to send a recipient email, issue a card with notification, or replace a code. Creating or updating an API key, approving CLI access, or authorizing a partner installation with commerce.gift_cards.secrets.write or accounts.api_keys.write requires the same verification; developer email sessions verify by email. The dashboard prompts and retries for API keys and CLI access. Other session callers receive 403 IDENTITY_VERIFICATION_REQUIRED; verify again, get a new token, and retry with the same Idempotency-Key. Refreshing a token alone does not renew verification. API keys and installed integrations are not challenged.
In a dashboard session, merchant viewers can read gift cards, and order operators can also redeem, capture, and cancel reservations. Every other gift card command, including updates, freezes, closing, honoring a funding loss, and canceling notifications, requires a merchant administrator or owner. Fresh verification preserves these role requirements.
Purchase velocity limits#
Processor-funded gift card purchase attempts have separate daily face-value limits for the buyer email, the payment card fingerprint on card, Apple Pay, and Google Pay payments, and the device when one is sent. Each defaults to $10,000 per merchant environment and UTC day. The platform can lower each limit. Failed attempts count toward the limit; exact retries of the same attempt count once. Split payment legs each count the full face value of gift cards that have not yet been issued, including partially funded cards, so a split purchase can reach the limit sooner. Value awaiting restoration after a manual-payment reversal also counts. Already-issued cards do not count again toward unrelated merchandise payments. The funding limits still apply.
For checkout-session purchases, send Flint-Buyer-Device with a stable random 32-character lowercase hexadecimal device identifier. Keep it across orders on the same device. A checkout-session purchase without it returns 400 INVALID_REQUEST with detail code REQUIRED. Hosted checkout supplies it from a secure, HttpOnly cookie, separate from checkout credentials. This identifier is a fraud signal and grants no access. Clearing cookies or changing device identifiers can reset that signal; payment card and buyer email controls remain independent. Merchant integrations can supply the same header when they have a buyer device. Standalone flint_payment creation and reloads apply these limits before adding gift card value, using the captured payment's original card, buyer email, and device identities. A standalone payment may already have charged its buyer before you choose to allocate it to a gift card. If allocation is refused, refund that payment or use it for its original purpose. Manual, imported, and external attested funding retain the funding limits and audit requirements; they do not claim a processor card identity.
Card fingerprints come from the processor, and the buyer email comes from the Flint customer bound to the payment. Caller-supplied billing or receipt emails do not replace that buyer identity. For order purchases, a missing fingerprint on a card-backed payment, a missing required device identifier, or an unavailable verification service rejects the purchase before charging. 409 LIMIT_REACHED with details[0].reason: daily_gift_card_purchases means this purchase would exceed a limit for the current UTC day. The limit resets at the next UTC day. A smaller purchase can still fit, and a single purchase above a limit is always rejected.
Recovery by key#
Recover a lost issuance with GET /v1/gift-cards?idempotency_key={key}. It returns the issued cards without full codes; only a same-key replay of the original request returns a code, within its recovery window. Loads, redemptions, funding dispositions, and transactions accept the same filter. See Recovery reads for matching rules and what an empty or pending result means.
The Gift card object#
Merchant-issued purchased gift card. Posted balance includes reserved value; available value is balance minus reservations. Frozen value remains part of outstanding liability. Gift cards are independent resources and cannot be transferred across merchants or currencies.
Returned by GET /v1/gift-cards/{gift_card_id} and carried by the endpoints below.
Attributes
available_moneyobjectRequiredThe balance minus reserved value: what can be spent now.
amountintegerRequiredAmount in the currency's minor unit, such as cents for USD.
currencystringRequiredISO 4217 currency code for this amount.
balance_moneyobjectRequiredThe posted balance, including value reserved for redemptions in progress.
amountintegerRequiredAmount in the currency's minor unit, such as cents for USD.
currencystringRequiredISO 4217 currency code for this amount.
code_sourceenumRequiredOrigin of the current code: generated means Flint issued a random code; imported means the merchant supplied an existing code during import. Rotating the code resets this to generated.
generatedimported
created_atstringRequiredRFC3339 timestamp.
currencyenumRequiredISO 4217 currency code.
USD
customer_idstring or nullRequiredID of the customer associated with the card. `null` when no customer is associated.
external_reference_idstring or nullRequiredCaller-owned identifier for this resource in an external system. `null` when none is set.
gift_card_idstringRequiredUnique identifier for this gift card, prefixed `gc_`.
last4stringRequiredLast four characters of the card's current code.
last_loaded_atstring or nullRequiredRFC3339 timestamp. `null` when no value has been loaded onto the card.
last_redeemed_atstring or nullRequiredRFC3339 timestamp. `null` when the card has never been redeemed.
merchant_idstringRequiredID of the merchant this resource belongs to.
reserved_moneyobjectRequiredValue held for redemptions in progress. It isn't available to other payments until the redemption succeeds or is released.
amountintegerRequiredAmount in the currency's minor unit, such as cents for USD.
currencystringRequiredISO 4217 currency code for this amount.
restrictionsarray of objectRequiredThe restrictions that keep the card frozen. unfreeze is supported only when every restriction is merchant_freeze. A funding_dispute with dispute_status lost needs a gift card funding disposition.
dispute_idstringPresent only for type funding_dispute. The dispute on the payment that funded value on this card.
dispute_statusenumPresent only for type funding_dispute. A copy of the funding dispute's current state. lost means the loss must be honored with a gift card funding disposition before the card can be spent.
openlost
reasonenumPresent only for type merchant_freeze. The merchant's freeze reason.
suspicious_activitycustomer_requestsupport_issue
typeenumRequiredThe kind of restriction. merchant_freeze is a freeze requested by the merchant. funding_dispute is a dispute on the payment that funded value on this card.
merchant_freezefunding_dispute
statusenumRequiredWhere the card is in its lifecycle. Only an `active` card can be spent.
pendingactivefrozenclosed
supported_actionsarray of enumRequiredLifecycle actions accepted for the stored card state, independent of the caller's credentials. Empty when no action is available.
adjust_balancecash_outclosefreezeunfreeze
updated_atstringRequiredRFC3339 timestamp.
versionintegerRequiredCurrent version of this resource's owned state. Send it as `expected_version` when changing the resource to reject a stale write.
{
"available_money": {
"amount": 5000,
"currency": "USD"
},
"balance_money": {
"amount": 5000,
"currency": "USD"
},
"code_source": "generated",
"created_at": "2026-09-07T12:00:00Z",
"currency": "USD",
"customer_id": "cus_01KEZF7C003ACYXT6Q5EQZ78EE",
"external_reference_id": null,
"gift_card_id": "gc_01KEZF7C00Z8CQGX4BKKBJ3B5S",
"last4": "1234",
"last_loaded_at": "2026-09-07T12:00:00Z",
"last_redeemed_at": null,
"merchant_id": "mer_01KEZF7C00MPP0T9S0KH5BB4CC",
"reserved_money": {
"amount": 0,
"currency": "USD"
},
"restrictions": [],
"status": "active",
"supported_actions": [
"freeze",
"adjust_balance",
"cash_out"
],
"updated_at": "2026-09-07T12:00:00Z",
"version": 2
}The Gift card funding disposition object#
A merchant decision to honor gift card value after its funding payment lost a dispute.
Returned by GET /v1/gift-card-funding-dispositions/{gift_card_funding_disposition_id} and carried by the endpoints below.
Attributes
created_atstringRequiredWhen the disposition was created.
dispositionenumRequiredHow Flint handles the lost funding. honor_value keeps the affected cards' unspent value spendable and removes the freeze this dispute placed on them.
honor_value
dispute_amount_moneyobjectRequiredThe whole disputed payment amount, which can include consideration for other purchases. It is separate from the original gift card consideration and honored face value.
amountintegerRequiredAmount in the currency's minor unit, such as cents for USD.
currencystringRequiredISO 4217 currency code for this amount.
dispute_idstringRequiredThe lost dispute this disposition resolves.
gift_card_funding_disposition_idstringRequiredStable identifier of the disposition.
gift_card_idsarray of stringRequiredGift cards whose value this disposition honors, including replacement cards that received value from the disputed funding.
honored_value_moneyobjectRequiredUnspent value that stays spendable under this disposition, summed across the affected cards, including replacement cards that received value from the disputed funding.
amountintegerRequiredAmount in the currency's minor unit, such as cents for USD.
currencystringRequiredISO 4217 currency code for this amount.
idempotency_keystringRequiredThe Idempotency-Key sent with the request that created this disposition.
original_gift_card_consideration_moneyobjectRequiredWhat the buyer paid for the gift card value the disputed payment funded, summed across its funding loads.
amountintegerRequiredAmount in the currency's minor unit, such as cents for USD.
currencystringRequiredISO 4217 currency code for this amount.
payment_intent_idstringRequiredThe disputed payment that funded the gift card value.
preserved_reserved_value_moneyobjectRequiredPart of honored_value_money that pending redemptions held when the disposition was created. It stays reserved for them.
amountintegerRequiredAmount in the currency's minor unit, such as cents for USD.
currencystringRequiredISO 4217 currency code for this amount.
reason_messagestringRequiredYour reason for honoring the value, from the create request.
{
"created_at": "2026-09-07T12:01:00Z",
"disposition": "honor_value",
"dispute_amount_money": {
"amount": 5000,
"currency": "USD"
},
"dispute_id": "du_01KEZF7C00329MTHSY5GX1VZJR",
"gift_card_funding_disposition_id": "gfd_01KEZF7C0077Q8RK3Q4FD2DTW8",
"gift_card_ids": [
"gc_01KEZF7C00Z8CQGX4BKKBJ3B5S"
],
"honored_value_money": {
"amount": 5000,
"currency": "USD"
},
"idempotency_key": "gift-card-honor-1842",
"original_gift_card_consideration_money": {
"amount": 5000,
"currency": "USD"
},
"payment_intent_id": "pi_01KEZF7C0050JFFB0HNCWWV1G3",
"preserved_reserved_value_money": {
"amount": 0,
"currency": "USD"
},
"reason_message": "The merchant will honor the remaining gift card value."
}The Gift card load object#
Top-level child of a gift card. Value and consideration are separate. External funding and import provenance are merchant-attested; no payment is collected by recording them. Replacement refund lots retain original funding provenance and do not represent new paid funding.
Returned by GET /v1/gift-card-loads/{gift_card_load_id} and carried by the endpoints below.
Attributes
consideration_moneyobject or nullRequiredWhat the buyer paid for the value, separate from `value_money`. `null` when no payment amount is recorded.
amountintegerRequiredAmount in the currency's minor unit, such as cents for USD.
currencystringRequiredISO 4217 currency code for this amount.
created_atstringRequiredRFC3339 timestamp.
funding_disputesarray of objectRequiredRestrictions tied to original funding, including value restored to replacement cards. A win clears only its own restriction. A loss keeps spending restricted until you create a gift card funding disposition.
created_atstringRequiredRFC3339 timestamp.
dispute_idstringRequiredThe dispute on the payment that funded this load.
requires_resolutionbooleanRequiredtrue when the dispute is lost and no funding disposition exists for it yet. Create one with POST /v1/gift-card-funding-dispositions.
resolutionobject or nullRequiredThe funding disposition recorded for this lost dispute. `null` when you have not created one yet.
statusenumRequiredWhere the dispute on the funding payment stands. Spending of the value it funded stays restricted while it is `open` or `lost`.
openwonlost
updated_atstringRequiredRFC3339 timestamp.
versionintegerRequiredCurrent version of this resource's owned state. Send it as `expected_version` when changing the resource to reject a stale write.
gift_card_idstringRequiredID of the gift card the load added value to.
gift_card_load_idstringRequiredUnique identifier for this gift card load, prefixed `gcl_`.
idempotency_keystring or nullRequiredYour Idempotency-Key for the command that created this record. `null` when Flint created it or no key was sent.
purchase_refund_value_holdsarray of objectPending original cash refunds holding unspent value on this descendant funding lot. Unknown provider outcomes retain these holds.
purchase_refund_allocation_idstringRequiredID of the pending purchase refund entry that holds the value.
refund_idstringRequiredID of the pending refund that holds the value.
root_gift_card_idstringRequiredID of the original card whose purchase is being refunded.
root_gift_card_load_idstringRequiredID of the original funding load that is being refunded.
value_moneyobjectRequiredThe unspent value held.
purchase_refundsarray of objectRequiredCash refunds and manual payment reversals against this original funding load. Pending refunds reserve their value; confirmed success removes it, and confirmed failure releases the hold.
consideration_moneyobjectRequiredThe part of the amount the buyer paid that this refund or reversal returns.
created_atstringRequiredRFC3339 timestamp.
order_manual_reversal_idstringID of the manual payment reversal. Set when this entry reverses a manual payment instead of refunding a payment.
purchase_refund_allocation_idstringRequiredID of this entry in the load's purchase refunds.
recoveryobjectHow the value was restored after the refund failed. `null` when no recovery happened.
refund_idstring or nullRequiredID of the refund. `null` when the entry reverses a manual payment, which has no refund.
statusenumRequiredWhether the refund has succeeded, failed, or is still pending.
pendingsucceededfailed
updated_atstringRequiredRFC3339 timestamp.
value_allocationsarray of objectActual value lots reserved or reversed for this original cash refund. Omitted when all value remains on the original load.
value_moneyobjectRequiredThe unspent face value this entry removes from the load.
versionintegerRequiredCurrent version of this resource's owned state. Send it as `expected_version` when changing the resource to reject a stale write.
purchase_restorationobjectLinks a gift card load to the original card and load it restores value to after a purchase refund, for one unit of an order line item.
order_line_item_idstringRequiredoriginal_gift_card_idstringRequiredoriginal_gift_card_load_idstringRequiredpurchase_refund_allocation_idstringRequiredunit_ordinalintegerRequiredrefund_provenanceobjectTraces a load made by a refund back to its original funding. `null` when the load wasn't made by a refund.
original_consideration_moneyobject or nullRequiredWhat the buyer paid for the original funding load. It describes that load, never a new payment. `null` when no payment amount was recorded.
original_created_atstringRequiredWhen the original funding load was created. RFC3339 timestamp.
original_sourceone ofRequiredWhere the original funding value came from.
original_source_created_atstring or nullRequiredWhen the original funding value was received, as recorded on that load. `null` when no source time was recorded.
refund_allocation_idstringRequiredID of the refund tender allocation that created this load. Empty when a failed gift card purchase refund created it.
root_gift_card_idstringRequiredID of the gift card that holds the original funding load. It stays the same through any number of replacement refunds.
root_gift_card_load_idstringRequiredID of the original funding load. It stays the same through any number of replacement refunds.
source_gift_card_idstringRequiredID of the gift card the refunded value came from.
source_gift_card_redemption_idstringRequiredID of the redemption whose refund created this load. Empty when a failed gift card purchase refund created it.
source_purchase_refund_allocation_idstringID of the gift card purchase refund allocation whose failure created this load. Present only then.
source_refund_idstringID of the refund whose failure created this load. Present only when a failed gift card purchase refund created it.
refund_transferred_moneyobjectMonetary amount represented as integer minor units plus an ISO 4217 currency code.
amountintegerRequiredAmount in the currency's minor unit, such as cents for USD.
currencystringRequiredISO 4217 currency code for this amount.
remaining_moneyobjectRequiredMonetary amount represented as integer minor units plus an ISO 4217 currency code.
amountintegerRequiredAmount in the currency's minor unit, such as cents for USD.
currencystringRequiredISO 4217 currency code for this amount.
reversed_moneyobjectRequiredMonetary amount represented as integer minor units plus an ISO 4217 currency code.
amountintegerRequiredAmount in the currency's minor unit, such as cents for USD.
currencystringRequiredISO 4217 currency code for this amount.
sourceone ofRequiredWhere the value came from, with your reference for it.
One of these shapes
The `external_payment` variant of `GiftCardFundingSource`.
customer_idstringRequiredID of the customer the funding is attributed to. Required for `external_payment` and `flint_manual_payment`; optional for `import`.
external_reference_idstringRequiredYour reference for the payment or import record that funded this value, such as a POS sale ID. Required; 1 to 255 characters.
funding_source_typeenumRequiredWhere the value came from.
external_payment
order_manual_payment_idstringID of the manual payment on the order that funded the value. Required for `flint_manual_payment`.
refund_idstringRefund that issued this value. Present only when funding_source_type is store_credit.
source_created_atstring or nullRequiredRFC3339 timestamp. `null` when no source time was recorded.
value_moneyobjectRequiredThe face value the load adds to the card.
amountintegerRequiredAmount in the currency's minor unit, such as cents for USD.
currencystringRequiredISO 4217 currency code for this amount.
versionintegerRequiredCurrent version of this resource's owned state. Send it as `expected_version` when changing the resource to reject a stale write.
{
"consideration_money": null,
"created_at": "2026-09-07T12:00:00Z",
"funding_disputes": [],
"gift_card_id": "gc_01KEZF7C00Z8CQGX4BKKBJ3B5S",
"gift_card_load_id": "gcl_01KEZF7C00HYJ6X0YSQMT751AP",
"idempotency_key": "gift-card-import-1842",
"purchase_refunds": [],
"remaining_money": {
"amount": 5000,
"currency": "USD"
},
"reversed_money": {
"amount": 0,
"currency": "USD"
},
"source": {
"customer_id": "cus_01KEZF7C003ACYXT6Q5EQZ78EE",
"external_reference_id": "legacy-card-1842",
"funding_source_type": "import"
},
"source_created_at": "2026-07-01T10:00:00Z",
"value_money": {
"amount": 5000,
"currency": "USD"
},
"version": 1
}The Gift card notification object#
A message sent to a gift card recipient.
Returned by GET /v1/gift-card-notifications/{gift_card_notification_id} and carried by the endpoints below.
Attributes
created_atstringRequiredRFC3339 timestamp.
deliveryobjectIncluded on notification retrieval. Contains the most recent sending attempts and delivery events, newest first. A failed attempt describes the send call; use notification.status to determine whether acceptance remains unconfirmed.
attemptsarray of objectRequiredRecent delivery attempts for the notification.
eventsarray of objectRequiredRecent delivery events for the notification.
has_more_attemptsbooleanRequiredWhether the notification has more attempts than `attempts` lists.
has_more_eventsbooleanRequiredWhether the notification has more events than `events` lists.
gift_card_idstringRequiredID of the gift card the notification is about.
gift_card_notification_idstringRequiredUnique identifier for this gift card notification, prefixed `gcn_`.
recipientobjectRequiredWho the notification is sent to.
emailstringRequiredEmail address the notification is sent to.
messagestringMessage included in the notification.
namestringName of the person the notification is addressed to.
send_atstringOptional whole-second send time between now and 90 days from now.
resend_of_notification_idstringID of the earlier notification this one sends again.
sent_atstringRFC3339 timestamp.
statusenumRequiredscheduledpendingsentfailedunconfirmedcanceled
status_reasonenum or nullRequiredWhy the notification has its current status. credential_rotated means code rotation canceled an unsent notification for the previous code. Null when no reason applies.
credential_rotatednull
supported_actionsarray of enumRequiredLifecycle actions accepted for this notification's stored state, independent of the caller's credentials. Empty when none are available.
cancel
updated_atstringRequiredRFC3339 timestamp.
versionintegerRequiredCurrent version of this resource's owned state. Send it as `expected_version` when changing the resource to reject a stale write.
{
"created_at": "2026-09-07T12:00:00Z",
"gift_card_id": "gc_01KEZF7C00Z8CQGX4BKKBJ3B5S",
"gift_card_notification_id": "gcn_01J00000000000000000000000",
"recipient": {
"email": "alex@example.com",
"name": "Alex Morgan"
},
"status": "pending",
"status_reason": null,
"supported_actions": [
"cancel"
],
"updated_at": "2026-09-07T12:00:00Z",
"version": 1
}The Gift card redemption object#
Independent redemption resource. Operational reservations are separate from immutable posted transactions. Refund captured value with POST /v1/refunds, using a tender_allocations entry with tender_type gift_card_redemption and this redemption's ID. Refunds keep the redemption succeeded and increase refunded_money.
Returned by GET /v1/gift-card-redemptions/{gift_card_redemption_id} and carried by the endpoints below.
Attributes
capture_modeenumRequiredWhether the redemption spends the value now or reserves it to capture later.
automaticmanual
captured_moneyobjectRequiredThe value captured from the card so far.
amountintegerRequiredAmount in the currency's minor unit, such as cents for USD.
currencystringRequiredISO 4217 currency code for this amount.
created_atstringRequiredRFC3339 timestamp.
expires_atstring or nullRequiredWhen an uncaptured manual reservation expires. `null` when `capture_mode` is `automatic`, which posts immediately.
gift_card_idstringRequiredID of the gift card the value is spent from.
gift_card_redemption_idstringRequiredUnique identifier for this gift card redemption, prefixed `gcr_`.
idempotency_keystring or nullRequiredYour Idempotency-Key for the command that created this record. `null` when Flint created it or no key was sent.
order_idstring or nullRequiredID of the Flint order the redemption pays for. `null` when `source_type` is `external`.
order_payment_attempt_idstring or nullRequiredThe order payment attempt the redemption belongs to. Set for source_type flint_order. `null` when `source_type` is `external`.
refunded_moneyobjectRequiredTotal refunded against this redemption across all refunds. Each refund lists its share in `tender_allocations`.
amountintegerRequiredAmount in the currency's minor unit, such as cents for USD.
currencystringRequiredISO 4217 currency code for this amount.
remaining_refundable_moneyobjectRequiredCaptured value not yet refunded. A refund allocation to this redemption can be at most this amount. Zero while the redemption is reserved, canceled, or expired.
amountintegerRequiredAmount in the currency's minor unit, such as cents for USD.
currencystringRequiredISO 4217 currency code for this amount.
requested_moneyobjectRequiredThe amount requested when the redemption was created.
amountintegerRequiredAmount in the currency's minor unit, such as cents for USD.
currencystringRequiredISO 4217 currency code for this amount.
reserved_moneyobjectRequiredThe value held on the card for this redemption while it is reserved.
amountintegerRequiredAmount in the currency's minor unit, such as cents for USD.
currencystringRequiredISO 4217 currency code for this amount.
sale_referencestring or nullRequiredYour reference for the sale the redemption pays for. Set for source_type external. `null` when `source_type` is `flint_order`.
source_typeenumRequiredWhat the redemption pays for: a sale you record, or a Flint order's payment.
externalflint_order
statusenumRequiredWhere the redemption is in its lifecycle.
reservedsucceededcanceledexpired
supported_actionsarray of enumRequiredLifecycle actions accepted for the stored redemption, independent of the caller's credentials. capture is available only before expires_at; cancel remains available until the reservation is resolved. Reservations for Flint orders are resolved through their payment attempt and list no actions.
capturecancel
updated_atstringRequiredRFC3339 timestamp.
versionintegerRequiredCurrent version of this resource's owned state. Send it as `expected_version` when changing the resource to reject a stale write.
{
"capture_mode": "manual",
"captured_money": {
"amount": 0,
"currency": "USD"
},
"created_at": "2026-09-07T12:01:00Z",
"expires_at": "2026-09-07T12:16:00Z",
"gift_card_id": "gc_01KEZF7C00Z8CQGX4BKKBJ3B5S",
"gift_card_redemption_id": "gcr_01KEZF7C001PMCPZ9NFHJA7A7A",
"idempotency_key": "gift-card-reserve-1842",
"order_id": null,
"order_payment_attempt_id": null,
"refunded_money": {
"amount": 0,
"currency": "USD"
},
"remaining_refundable_money": {
"amount": 0,
"currency": "USD"
},
"requested_money": {
"amount": 1000,
"currency": "USD"
},
"reserved_money": {
"amount": 1000,
"currency": "USD"
},
"sale_reference": "pos-sale-1842",
"source_type": "external",
"status": "reserved",
"supported_actions": [
"cancel"
],
"updated_at": "2026-09-07T12:01:00Z",
"version": 1
}List gift card funding dispositions#
/v1/gift-card-funding-dispositionsRequires scope commerce.gift_cards.adjustments.write or commerce.gift_cards.read or commerce.gift_cards.redemptions.write or commerce.gift_cards.secrets.write or commerce.gift_cards.write
Rate limit: read
Lists funding dispositions in descending ID order within the authenticated merchant and environment. Filter by idempotency_key to recover a committed command. Default order: gift_card_funding_disposition_id descending; this key uniquely orders the results.
Query parameters
created_afterstringInclusive lower bound on created_at.
created_beforestringExclusive upper bound on created_at.
dispute_idstringExact, case-sensitive filter.
idempotency_keystringFilter by the original Idempotency-Key, after trimming surrounding whitespace. Matching is exact and case-sensitive. Returns current authorized resources, not the recorded response. A pending resource does not prove that the operation succeeded, and an empty list does not prove that it had no effect.
page_sizeintegerMaximum number of results to return, from 1 to 100. Defaults to 20.
page_tokenstringOpaque next_page_token from the previous response. Omit on the first request. You may change `page_size` between pages. Reuse it with the same endpoint, filters, sort, and request context. Do not parse or construct tokens. An invalid, expired, or mismatched token returns a validation error.
Response · 200
The gift card resource or committed command result.
dataarray of objectRequiredResource, collection, or operation result returned by this request.
created_atstringRequiredWhen the disposition was created.
dispositionenumRequiredHow Flint handles the lost funding. honor_value keeps the affected cards' unspent value spendable and removes the freeze this dispute placed on them.
honor_value
dispute_amount_moneyobjectRequiredThe whole disputed payment amount, which can include consideration for other purchases. It is separate from the original gift card consideration and honored face value.
dispute_idstringRequiredThe lost dispute this disposition resolves.
gift_card_funding_disposition_idstringRequiredStable identifier of the disposition.
gift_card_idsarray of stringRequiredGift cards whose value this disposition honors, including replacement cards that received value from the disputed funding.
honored_value_moneyobjectRequiredUnspent value that stays spendable under this disposition, summed across the affected cards, including replacement cards that received value from the disputed funding.
idempotency_keystringRequiredThe Idempotency-Key sent with the request that created this disposition.
original_gift_card_consideration_moneyobjectRequiredWhat the buyer paid for the gift card value the disputed payment funded, summed across its funding loads.
payment_intent_idstringRequiredThe disputed payment that funded the gift card value.
preserved_reserved_value_moneyobjectRequiredPart of honored_value_money that pending redemptions held when the disposition was created. It stays reserved for them.
reason_messagestringRequiredYour reason for honoring the value, from the create request.
metaobjectAdditional information about this response.
api_versionstringAPI version used to produce this response.
idempotency_replayedbooleanWhether this response replays a stored result for the supplied Idempotency-Key.
trace_idstringTrace identifier to include when contacting Flint about this request.
warningsarray of objectConditions that need attention even though the request succeeded.
next_page_tokenstringOpaque token to send as `page_token` to retrieve the next page. Omitted when there is no next page.
request_idstringRequiredIdentifier of this API request, used to correlate logs and support requests.
curl https://api.withflintpay.com/v1/gift-card-funding-dispositions \
-H "Flint-Version: 2026-09-07" \
-H "Authorization: Bearer YOUR_API_KEY"The gift card resource or committed command result.
{
"data": [
{
"created_at": "2026-09-07T12:01:00Z",
"disposition": "honor_value",
"dispute_amount_money": {
"amount": 5000,
"currency": "USD"
},
"dispute_id": "du_01KEZF7C00329MTHSY5GX1VZJR",
"gift_card_funding_disposition_id": "gfd_01KEZF7C0077Q8RK3Q4FD2DTW8",
"gift_card_ids": [
"gc_01KEZF7C00Z8CQGX4BKKBJ3B5S"
],
"honored_value_money": {
"amount": 5000,
"currency": "USD"
},
"idempotency_key": "gift-card-honor-1842",
"original_gift_card_consideration_money": {
"amount": 5000,
"currency": "USD"
},
"payment_intent_id": "pi_01KEZF7C0050JFFB0HNCWWV1G3",
"preserved_reserved_value_money": {
"amount": 0,
"currency": "USD"
},
"reason_message": "The merchant will honor the remaining gift card value."
}
],
"meta": {
"api_version": "2026-09-07"
},
"request_id": "req_01KWM6WAHG3N9Q8T2V5XRZ7C4D"
}Create a gift card funding disposition#
/v1/gift-card-funding-dispositionsKey requiredRequires scope commerce.gift_cards.adjustments.write
Rate limit: sensitive_write
Accepts a confirmed funding dispute loss and honors all gift card value funded by that payment, including value restored to replacement cards. Records the dispute amount, original gift card consideration, honored value and preserved reservations. Clears only this dispute restriction; balances, unrelated restrictions and unresolved payment reservations remain intact. Requires gift card adjustment authority and a durable idempotency key.
Request body
dispositionenumWhat the merchant decided about the card's value after the funding payment lost a dispute.
honor_value
dispute_idstringRequiredThe lost dispute on the payment that funded the gift card value.
reason_messagestringRequiredYour reason for honoring the gift card value despite the confirmed funding loss.
Response · 201
The created gift card funding disposition.
dataobjectRequiredResource, collection, or operation result returned by this request.
created_atstringRequiredWhen the disposition was created.
dispositionenumRequiredHow Flint handles the lost funding. honor_value keeps the affected cards' unspent value spendable and removes the freeze this dispute placed on them.
honor_value
dispute_amount_moneyobjectRequiredThe whole disputed payment amount, which can include consideration for other purchases. It is separate from the original gift card consideration and honored face value.
dispute_idstringRequiredThe lost dispute this disposition resolves.
gift_card_funding_disposition_idstringRequiredStable identifier of the disposition.
gift_card_idsarray of stringRequiredGift cards whose value this disposition honors, including replacement cards that received value from the disputed funding.
honored_value_moneyobjectRequiredUnspent value that stays spendable under this disposition, summed across the affected cards, including replacement cards that received value from the disputed funding.
idempotency_keystringRequiredThe Idempotency-Key sent with the request that created this disposition.
original_gift_card_consideration_moneyobjectRequiredWhat the buyer paid for the gift card value the disputed payment funded, summed across its funding loads.
payment_intent_idstringRequiredThe disputed payment that funded the gift card value.
preserved_reserved_value_moneyobjectRequiredPart of honored_value_money that pending redemptions held when the disposition was created. It stays reserved for them.
reason_messagestringRequiredYour reason for honoring the value, from the create request.
metaobjectAdditional information about this response.
api_versionstringAPI version used to produce this response.
idempotency_replayedbooleanWhether this response replays a stored result for the supplied Idempotency-Key.
trace_idstringTrace identifier to include when contacting Flint about this request.
warningsarray of objectConditions that need attention even though the request succeeded.
request_idstringRequiredIdentifier of this API request, used to correlate logs and support requests.
curl -X POST https://api.withflintpay.com/v1/gift-card-funding-dispositions \
-H "Flint-Version: 2026-09-07" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: a-unique-key" \
-d '{
"disposition": "honor_value",
"dispute_id": "du_01KEZF7C00329MTHSY5GX1VZJR",
"reason_message": "The merchant will honor the remaining gift card value."
}'Get a gift card funding disposition#
/v1/gift-card-funding-dispositions/{gift_card_funding_disposition_id}Requires scope commerce.gift_cards.adjustments.write or commerce.gift_cards.read or commerce.gift_cards.redemptions.write or commerce.gift_cards.secrets.write or commerce.gift_cards.write
Rate limit: read
Retrieves a committed funding disposition within the authenticated merchant and environment.
Path parameters
gift_card_funding_disposition_idstringRequiredFlint resource ID.
Response · 200
The gift card resource or committed command result.
Same response as Create a gift card funding disposition.
curl https://api.withflintpay.com/v1/gift-card-funding-dispositions/gfd_01KEZF7C0077Q8RK3Q4FD2DTW8 \
-H "Flint-Version: 2026-09-07" \
-H "Authorization: Bearer YOUR_API_KEY"The gift card resource or committed command result.
{
"data": {
"created_at": "2026-09-07T12:01:00Z",
"disposition": "honor_value",
"dispute_amount_money": {
"amount": 5000,
"currency": "USD"
},
"dispute_id": "du_01KEZF7C00329MTHSY5GX1VZJR",
"gift_card_funding_disposition_id": "gfd_01KEZF7C0077Q8RK3Q4FD2DTW8",
"gift_card_ids": [
"gc_01KEZF7C00Z8CQGX4BKKBJ3B5S"
],
"honored_value_money": {
"amount": 5000,
"currency": "USD"
},
"idempotency_key": "gift-card-honor-1842",
"original_gift_card_consideration_money": {
"amount": 5000,
"currency": "USD"
},
"payment_intent_id": "pi_01KEZF7C0050JFFB0HNCWWV1G3",
"preserved_reserved_value_money": {
"amount": 0,
"currency": "USD"
},
"reason_message": "The merchant will honor the remaining gift card value."
},
"meta": {
"api_version": "2026-09-07"
},
"request_id": "req_01KWM6WAHG3N9Q8T2V5XRZ7C4D"
}List gift card loads#
/v1/gift-card-loadsRequires scope commerce.gift_cards.adjustments.write or commerce.gift_cards.read or commerce.gift_cards.redemptions.write or commerce.gift_cards.secrets.write or commerce.gift_cards.write
Rate limit: read
Lists funding lots in descending ID order. Consideration may be null for imported balances whose original purchase price is unknown. The idempotency_key filter recovers a load after a lost command response. Default order: gift_card_load_id descending; this key uniquely orders the results.
Query parameters
created_afterstringInclusive lower bound on created_at.
created_beforestringExclusive upper bound on created_at.
funding_source_typearray of enumExact, case-sensitive filter. Values are trimmed and deduplicated in first-seen order; empty or unknown entries are rejected. Values within this filter are ORed; separate filters are ANDed.
adjustmentexternal_paymentflint_manual_paymentflint_paymentgift_card_purchase_refund_recoverygift_card_refundimportstore_credit
gift_card_idstringExact, case-sensitive filter.
idempotency_keystringFilter by the original Idempotency-Key, after trimming surrounding whitespace. Matching is exact and case-sensitive. Returns current authorized resources, not the recorded response. A pending resource does not prove that the operation succeeded, and an empty list does not prove that it had no effect.
order_idstringExact, case-sensitive filter.
page_sizeintegerMaximum number of results to return, from 1 to 100. Defaults to 20.
page_tokenstringOpaque next_page_token from the previous response. Omit on the first request. You may change `page_size` between pages. Reuse it with the same endpoint, filters, sort, and request context. Do not parse or construct tokens. An invalid, expired, or mismatched token returns a validation error.
source_external_reference_idstringExact, case-sensitive reference for the payment or import record that funded this value.
Response · 200
The gift card resource or committed command result.
dataarray of objectRequiredResource, collection, or operation result returned by this request.
consideration_moneyobject or nullRequiredWhat the buyer paid for the value, separate from `value_money`. `null` when no payment amount is recorded.
created_atstringRequiredRFC3339 timestamp.
funding_disputesarray of objectRequiredRestrictions tied to original funding, including value restored to replacement cards. A win clears only its own restriction. A loss keeps spending restricted until you create a gift card funding disposition.
gift_card_idstringRequiredID of the gift card the load added value to.
gift_card_load_idstringRequiredUnique identifier for this gift card load, prefixed `gcl_`.
idempotency_keystring or nullRequiredYour Idempotency-Key for the command that created this record. `null` when Flint created it or no key was sent.
purchase_refund_value_holdsarray of objectPending original cash refunds holding unspent value on this descendant funding lot. Unknown provider outcomes retain these holds.
purchase_refundsarray of objectRequiredCash refunds and manual payment reversals against this original funding load. Pending refunds reserve their value; confirmed success removes it, and confirmed failure releases the hold.
purchase_restorationobjectLinks a gift card load to the original card and load it restores value to after a purchase refund, for one unit of an order line item.
refund_provenanceobjectTraces a load made by a refund back to its original funding. `null` when the load wasn't made by a refund.
refund_transferred_moneyobjectMonetary amount represented as integer minor units plus an ISO 4217 currency code.
remaining_moneyobjectRequiredMonetary amount represented as integer minor units plus an ISO 4217 currency code.
reversed_moneyobjectRequiredMonetary amount represented as integer minor units plus an ISO 4217 currency code.
sourceone ofRequiredWhere the value came from, with your reference for it.
source_created_atstring or nullRequiredRFC3339 timestamp. `null` when no source time was recorded.
value_moneyobjectRequiredThe face value the load adds to the card.
versionintegerRequiredCurrent version of this resource's owned state. Send it as `expected_version` when changing the resource to reject a stale write.
metaobjectAdditional information about this response.
api_versionstringAPI version used to produce this response.
idempotency_replayedbooleanWhether this response replays a stored result for the supplied Idempotency-Key.
trace_idstringTrace identifier to include when contacting Flint about this request.
warningsarray of objectConditions that need attention even though the request succeeded.
next_page_tokenstringOpaque token to send as `page_token` to retrieve the next page. Omitted when there is no next page.
request_idstringRequiredIdentifier of this API request, used to correlate logs and support requests.
curl https://api.withflintpay.com/v1/gift-card-loads \
-H "Flint-Version: 2026-09-07" \
-H "Authorization: Bearer YOUR_API_KEY"The gift card resource or committed command result.
{
"data": [
{
"consideration_money": null,
"created_at": "2026-09-07T12:00:00Z",
"funding_disputes": [],
"gift_card_id": "gc_01KEZF7C00Z8CQGX4BKKBJ3B5S",
"gift_card_load_id": "gcl_01KEZF7C00HYJ6X0YSQMT751AP",
"idempotency_key": "gift-card-import-1842",
"purchase_refunds": [],
"remaining_money": {
"amount": 5000,
"currency": "USD"
},
"reversed_money": {
"amount": 0,
"currency": "USD"
},
"source": {
"customer_id": "cus_01KEZF7C003ACYXT6Q5EQZ78EE",
"external_reference_id": "legacy-card-1842",
"funding_source_type": "import"
},
"source_created_at": "2026-07-01T10:00:00Z",
"value_money": {
"amount": 5000,
"currency": "USD"
},
"version": 1
}
],
"meta": {
"api_version": "2026-09-07"
},
"request_id": "req_01KWM6WAHG3N9Q8T2V5XRZ7C4D"
}Load a gift card#
/v1/gift-card-loadsKey requiredRequires scope commerce.gift_cards.write
Rate limit: sensitive_write
Adds positive value with separately recorded consideration and funding provenance. Limits apply to externally funded value and imports as well as Flint-funded sales. Loading a pending card activates it; loading a frozen card does not remove its restrictions. expected_gift_card_version fences the gift card version.
Request body
consideration_moneyobject or nullWhat the buyer paid for the value, separate from `value_money`. `null` when no payment amount is recorded.
amountintegerRequiredAmount in the currency's minor unit, such as cents for USD.
currencystringRequiredISO 4217 currency code for this amount.
expected_gift_card_versionintegerThe gift card version last read. The command changes this card only when its current version matches.
gift_card_idstringRequiredThe gift card to load.
sourceone ofRequiredWhere the value came from, with your reference for it.
Send exactly one of these
The `external_payment` variant of `GiftCardFundingSource`.
customer_idstringRequiredID of the customer the funding is attributed to. Required for `external_payment` and `flint_manual_payment`; optional for `import`.
external_reference_idstringRequiredYour reference for the payment or import record that funded this value, such as a POS sale ID. Required; 1 to 255 characters.
funding_source_typeenumRequiredWhere the value came from.
external_payment
refund_idstringRefund that issued this value. Present only when funding_source_type is store_credit.
source_created_atstringRFC3339 timestamp.
value_moneyobjectRequiredThe face value the load adds to the card.
amountintegerRequiredAmount in the currency's minor unit, such as cents for USD.
currencystringRequiredISO 4217 currency code for this amount.
Response · 201
The gift card resource or committed command result.
dataobjectRequiredResource, collection, or operation result returned by this request.
gift_cardobjectRequiredThe gift card after the command.
gift_card_loadobjectRequiredThe load the command created.
gift_card_transactionsarray of objectRequiredThe transactions the command posted to the card.
metaobjectAdditional information about this response.
api_versionstringAPI version used to produce this response.
idempotency_replayedbooleanWhether this response replays a stored result for the supplied Idempotency-Key.
trace_idstringTrace identifier to include when contacting Flint about this request.
warningsarray of objectConditions that need attention even though the request succeeded.
request_idstringRequiredIdentifier of this API request, used to correlate logs and support requests.
curl -X POST https://api.withflintpay.com/v1/gift-card-loads \
-H "Flint-Version: 2026-09-07" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: a-unique-key" \
-d '{
"expected_gift_card_version": 1,
"gift_card_id": "gc_01KEZF7C00Z8CQGX4BKKBJ3B5S",
"source": {
"customer_id": "cus_01KEZF7C003ACYXT6Q5EQZ78EE",
"external_reference_id": "legacy-card-1842",
"funding_source_type": "import"
},
"source_created_at": "2026-07-01T10:00:00Z",
"value_money": {
"amount": 5000,
"currency": "USD"
}
}'Get a gift card load#
/v1/gift-card-loads/{gift_card_load_id}Requires scope commerce.gift_cards.adjustments.write or commerce.gift_cards.read or commerce.gift_cards.redemptions.write or commerce.gift_cards.secrets.write or commerce.gift_cards.write
Rate limit: read
Retrieves original value, consideration, funding provenance and remaining attributable value for one load.
Path parameters
gift_card_load_idstringRequiredFlint resource ID.
Response · 200
The gift card resource or committed command result.
dataobjectRequiredResource, collection, or operation result returned by this request.
consideration_moneyobject or nullRequiredWhat the buyer paid for the value, separate from `value_money`. `null` when no payment amount is recorded.
created_atstringRequiredRFC3339 timestamp.
funding_disputesarray of objectRequiredRestrictions tied to original funding, including value restored to replacement cards. A win clears only its own restriction. A loss keeps spending restricted until you create a gift card funding disposition.
gift_card_idstringRequiredID of the gift card the load added value to.
gift_card_load_idstringRequiredUnique identifier for this gift card load, prefixed `gcl_`.
idempotency_keystring or nullRequiredYour Idempotency-Key for the command that created this record. `null` when Flint created it or no key was sent.
purchase_refund_value_holdsarray of objectPending original cash refunds holding unspent value on this descendant funding lot. Unknown provider outcomes retain these holds.
purchase_refundsarray of objectRequiredCash refunds and manual payment reversals against this original funding load. Pending refunds reserve their value; confirmed success removes it, and confirmed failure releases the hold.
purchase_restorationobjectLinks a gift card load to the original card and load it restores value to after a purchase refund, for one unit of an order line item.
refund_provenanceobjectTraces a load made by a refund back to its original funding. `null` when the load wasn't made by a refund.
refund_transferred_moneyobjectMonetary amount represented as integer minor units plus an ISO 4217 currency code.
remaining_moneyobjectRequiredMonetary amount represented as integer minor units plus an ISO 4217 currency code.
reversed_moneyobjectRequiredMonetary amount represented as integer minor units plus an ISO 4217 currency code.
sourceone ofRequiredWhere the value came from, with your reference for it.
source_created_atstring or nullRequiredRFC3339 timestamp. `null` when no source time was recorded.
value_moneyobjectRequiredThe face value the load adds to the card.
versionintegerRequiredCurrent version of this resource's owned state. Send it as `expected_version` when changing the resource to reject a stale write.
metaobjectAdditional information about this response.
api_versionstringAPI version used to produce this response.
idempotency_replayedbooleanWhether this response replays a stored result for the supplied Idempotency-Key.
trace_idstringTrace identifier to include when contacting Flint about this request.
warningsarray of objectConditions that need attention even though the request succeeded.
request_idstringRequiredIdentifier of this API request, used to correlate logs and support requests.
curl https://api.withflintpay.com/v1/gift-card-loads/gcl_01KEZF7C00YJED2857SE0J6KWC \
-H "Flint-Version: 2026-09-07" \
-H "Authorization: Bearer YOUR_API_KEY"The gift card resource or committed command result.
{
"data": {
"consideration_money": null,
"created_at": "2026-09-07T12:00:00Z",
"funding_disputes": [],
"gift_card_id": "gc_01KEZF7C00Z8CQGX4BKKBJ3B5S",
"gift_card_load_id": "gcl_01KEZF7C00HYJ6X0YSQMT751AP",
"idempotency_key": "gift-card-import-1842",
"purchase_refunds": [],
"remaining_money": {
"amount": 5000,
"currency": "USD"
},
"reversed_money": {
"amount": 0,
"currency": "USD"
},
"source": {
"customer_id": "cus_01KEZF7C003ACYXT6Q5EQZ78EE",
"external_reference_id": "legacy-card-1842",
"funding_source_type": "import"
},
"source_created_at": "2026-07-01T10:00:00Z",
"value_money": {
"amount": 5000,
"currency": "USD"
},
"version": 1
},
"meta": {
"api_version": "2026-09-07"
},
"request_id": "req_01KWM6WAHG3N9Q8T2V5XRZ7C4D"
}List gift card notifications#
/v1/gift-card-notificationsRequires scope commerce.gift_cards.adjustments.write or commerce.gift_cards.read or commerce.gift_cards.redemptions.write or commerce.gift_cards.secrets.write or commerce.gift_cards.write
Rate limit: read
Lists recipient notification identities, schedules and delivery outcomes. No redemption codes or recipient access tokens are returned. Default order: gift_card_notification_id descending; this key uniquely orders the results.
Query parameters
created_afterstringInclusive lower bound on created_at.
created_beforestringExclusive upper bound on created_at.
gift_card_idstringExact, case-sensitive filter.
page_sizeintegerMaximum number of results to return, from 1 to 100. Defaults to 20.
page_tokenstringOpaque next_page_token from the previous response. Omit on the first request. You may change `page_size` between pages. Reuse it with the same endpoint, filters, sort, and request context. Do not parse or construct tokens. An invalid, expired, or mismatched token returns a validation error.
statusarray of enumExact, case-sensitive filter. Values are trimmed and deduplicated in first-seen order; empty or unknown entries are rejected. Values within this filter are ORed; separate filters are ANDed.
canceledfailedpendingscheduledsentunconfirmed
Response · 200
The gift card resource or committed command result.
dataarray of objectRequiredResource, collection, or operation result returned by this request.
created_atstringRequiredRFC3339 timestamp.
deliveryobjectIncluded on notification retrieval. Contains the most recent sending attempts and delivery events, newest first. A failed attempt describes the send call; use notification.status to determine whether acceptance remains unconfirmed.
gift_card_idstringRequiredID of the gift card the notification is about.
gift_card_notification_idstringRequiredUnique identifier for this gift card notification, prefixed `gcn_`.
recipientobjectRequiredWho the notification is sent to.
resend_of_notification_idstringID of the earlier notification this one sends again.
sent_atstringRFC3339 timestamp.
statusenumRequiredscheduledpendingsentfailedunconfirmedcanceled
status_reasonenum or nullRequiredWhy the notification has its current status. credential_rotated means code rotation canceled an unsent notification for the previous code. Null when no reason applies.
credential_rotatednull
supported_actionsarray of enumRequiredLifecycle actions accepted for this notification's stored state, independent of the caller's credentials. Empty when none are available.
cancel
updated_atstringRequiredRFC3339 timestamp.
versionintegerRequiredCurrent version of this resource's owned state. Send it as `expected_version` when changing the resource to reject a stale write.
metaobjectAdditional information about this response.
api_versionstringAPI version used to produce this response.
idempotency_replayedbooleanWhether this response replays a stored result for the supplied Idempotency-Key.
trace_idstringTrace identifier to include when contacting Flint about this request.
warningsarray of objectConditions that need attention even though the request succeeded.
next_page_tokenstringOpaque token to send as `page_token` to retrieve the next page. Omitted when there is no next page.
request_idstringRequiredIdentifier of this API request, used to correlate logs and support requests.
curl https://api.withflintpay.com/v1/gift-card-notifications \
-H "Flint-Version: 2026-09-07" \
-H "Authorization: Bearer YOUR_API_KEY"The gift card resource or committed command result.
{
"data": [
{
"created_at": "2026-09-07T12:00:00Z",
"gift_card_id": "gc_01KEZF7C00Z8CQGX4BKKBJ3B5S",
"gift_card_notification_id": "gcn_01J00000000000000000000000",
"recipient": {
"email": "alex@example.com",
"name": "Alex Morgan"
},
"status": "pending",
"status_reason": null,
"supported_actions": [
"cancel"
],
"updated_at": "2026-09-07T12:00:00Z",
"version": 1
}
],
"meta": {
"api_version": "2026-09-07"
},
"request_id": "req_01KWM6WAHG3N9Q8T2V5XRZ7C4D"
}Send a gift card notification#
/v1/gift-card-notificationsIdempotentRequires scope commerce.gift_cards.secrets.write
Rate limit: sensitive_write
Creates a recipient email notification, immediately or up to 90 days from now. A resend creates a new resource with resend_of_notification_id. An unconfirmed send must be resolved before another send is requested. Sending does not change gift card value or order fulfillment.
Request body
gift_card_idstringRequiredID of the gift card the notification is about.
recipientobjectRequiredWho the notification is sent to.
emailstringRequiredEmail address the notification is sent to.
messagestringMessage included in the notification.
namestringName of the person the notification is addressed to.
send_atstringOptional whole-second send time between now and 90 days from now.
resend_of_notification_idstringID of the earlier notification this one sends again.
Response · 201
The gift card resource or committed command result.
dataobjectRequiredResource, collection, or operation result returned by this request.
created_atstringRequiredRFC3339 timestamp.
deliveryobjectIncluded on notification retrieval. Contains the most recent sending attempts and delivery events, newest first. A failed attempt describes the send call; use notification.status to determine whether acceptance remains unconfirmed.
gift_card_idstringRequiredID of the gift card the notification is about.
gift_card_notification_idstringRequiredUnique identifier for this gift card notification, prefixed `gcn_`.
recipientobjectRequiredWho the notification is sent to.
resend_of_notification_idstringID of the earlier notification this one sends again.
sent_atstringRFC3339 timestamp.
statusenumRequiredscheduledpendingsentfailedunconfirmedcanceled
status_reasonenum or nullRequiredWhy the notification has its current status. credential_rotated means code rotation canceled an unsent notification for the previous code. Null when no reason applies.
credential_rotatednull
supported_actionsarray of enumRequiredLifecycle actions accepted for this notification's stored state, independent of the caller's credentials. Empty when none are available.
cancel
updated_atstringRequiredRFC3339 timestamp.
versionintegerRequiredCurrent version of this resource's owned state. Send it as `expected_version` when changing the resource to reject a stale write.
metaobjectAdditional information about this response.
api_versionstringAPI version used to produce this response.
idempotency_replayedbooleanWhether this response replays a stored result for the supplied Idempotency-Key.
trace_idstringTrace identifier to include when contacting Flint about this request.
warningsarray of objectConditions that need attention even though the request succeeded.
request_idstringRequiredIdentifier of this API request, used to correlate logs and support requests.
curl -X POST https://api.withflintpay.com/v1/gift-card-notifications \
-H "Flint-Version: 2026-09-07" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: a-unique-key" \
-d '{
"gift_card_id": "gc_01KEZF7C00Z8CQGX4BKKBJ3B5S",
"recipient": {
"email": "alex@example.com",
"name": "Alex Morgan"
}
}'Get a gift card notification#
/v1/gift-card-notifications/{gift_card_notification_id}Requires scope commerce.gift_cards.adjustments.write or commerce.gift_cards.read or commerce.gift_cards.redemptions.write or commerce.gift_cards.secrets.write or commerce.gift_cards.write
Rate limit: read
Retrieves a notification and its sending outcome. Sent means the sending provider accepted the message; it does not mean the recipient read it.
Path parameters
gift_card_notification_idstringRequiredFlint resource ID.
Response · 200
The gift card resource or committed command result.
Same response as Send a gift card notification.
curl https://api.withflintpay.com/v1/gift-card-notifications/gcn_01KEZF7C0023FN0HF9GH34RZA1 \
-H "Flint-Version: 2026-09-07" \
-H "Authorization: Bearer YOUR_API_KEY"The gift card resource or committed command result.
{
"data": {
"created_at": "2026-09-07T12:00:00Z",
"gift_card_id": "gc_01KEZF7C00Z8CQGX4BKKBJ3B5S",
"gift_card_notification_id": "gcn_01J00000000000000000000000",
"recipient": {
"email": "alex@example.com",
"name": "Alex Morgan"
},
"status": "pending",
"status_reason": null,
"supported_actions": [
"cancel"
],
"updated_at": "2026-09-07T12:00:00Z",
"version": 1
},
"meta": {
"api_version": "2026-09-07"
},
"request_id": "req_01KWM6WAHG3N9Q8T2V5XRZ7C4D"
}Cancel a gift card notification#
/v1/gift-card-notifications/{gift_card_notification_id}/cancelIdempotentRequires scope commerce.gift_cards.secrets.write
Rate limit: sensitive_write
Cancels a notification before sending starts or after confirmed failure. A sending or unconfirmed notification cannot be canceled. Gift card value is preserved.
Path parameters
gift_card_notification_idstringRequiredFlint resource ID.
Response · 200
The gift card resource or committed command result.
Same response as Send a gift card notification.
curl -X POST https://api.withflintpay.com/v1/gift-card-notifications/gcn_01KEZF7C0023FN0HF9GH34RZA1/cancel \
-H "Flint-Version: 2026-09-07" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: a-unique-key" \
-d '{}'List gift card redemptions#
/v1/gift-card-redemptionsRequires scope commerce.gift_cards.adjustments.write or commerce.gift_cards.read or commerce.gift_cards.redemptions.write or commerce.gift_cards.secrets.write or commerce.gift_cards.write
Rate limit: read
Lists reservations and captured redemptions in descending ID order. Retrieve by idempotency_key to recover an operation after a lost response. Default order: gift_card_redemption_id descending; this key uniquely orders the results.
Query parameters
created_afterstringInclusive lower bound on created_at.
created_beforestringExclusive upper bound on created_at.
gift_card_idstringExact, case-sensitive filter.
idempotency_keystringFilter by the original Idempotency-Key, after trimming surrounding whitespace. Matching is exact and case-sensitive. Returns current authorized resources, not the recorded response. A pending resource does not prove that the operation succeeded, and an empty list does not prove that it had no effect.
order_idstringExact, case-sensitive filter.
page_sizeintegerMaximum number of results to return, from 1 to 100. Defaults to 20.
page_tokenstringOpaque next_page_token from the previous response. Omit on the first request. You may change `page_size` between pages. Reuse it with the same endpoint, filters, sort, and request context. Do not parse or construct tokens. An invalid, expired, or mismatched token returns a validation error.
sale_referencestringExact, case-sensitive filter on your reference for the sale. Matches only external redemptions.
source_typearray of enumExact, case-sensitive filter. Values are trimmed and deduplicated in first-seen order; empty or unknown entries are rejected. Values within this filter are ORed; separate filters are ANDed.
externalflint_order
statusarray of enumExact, case-sensitive filter. Values are trimmed and deduplicated in first-seen order; empty or unknown entries are rejected. Values within this filter are ORed; separate filters are ANDed.
canceledexpiredreservedsucceeded
Response · 200
The gift card resource or committed command result.
dataarray of objectRequiredResource, collection, or operation result returned by this request.
capture_modeenumRequiredWhether the redemption spends the value now or reserves it to capture later.
automaticmanual
captured_moneyobjectRequiredThe value captured from the card so far.
created_atstringRequiredRFC3339 timestamp.
expires_atstring or nullRequiredWhen an uncaptured manual reservation expires. `null` when `capture_mode` is `automatic`, which posts immediately.
gift_card_idstringRequiredID of the gift card the value is spent from.
gift_card_redemption_idstringRequiredUnique identifier for this gift card redemption, prefixed `gcr_`.
idempotency_keystring or nullRequiredYour Idempotency-Key for the command that created this record. `null` when Flint created it or no key was sent.
order_idstring or nullRequiredID of the Flint order the redemption pays for. `null` when `source_type` is `external`.
order_payment_attempt_idstring or nullRequiredThe order payment attempt the redemption belongs to. Set for source_type flint_order. `null` when `source_type` is `external`.
refunded_moneyobjectRequiredTotal refunded against this redemption across all refunds. Each refund lists its share in `tender_allocations`.
remaining_refundable_moneyobjectRequiredCaptured value not yet refunded. A refund allocation to this redemption can be at most this amount. Zero while the redemption is reserved, canceled, or expired.
requested_moneyobjectRequiredThe amount requested when the redemption was created.
reserved_moneyobjectRequiredThe value held on the card for this redemption while it is reserved.
sale_referencestring or nullRequiredYour reference for the sale the redemption pays for. Set for source_type external. `null` when `source_type` is `flint_order`.
source_typeenumRequiredWhat the redemption pays for: a sale you record, or a Flint order's payment.
externalflint_order
statusenumRequiredWhere the redemption is in its lifecycle.
reservedsucceededcanceledexpired
supported_actionsarray of enumRequiredLifecycle actions accepted for the stored redemption, independent of the caller's credentials. capture is available only before expires_at; cancel remains available until the reservation is resolved. Reservations for Flint orders are resolved through their payment attempt and list no actions.
capturecancel
updated_atstringRequiredRFC3339 timestamp.
versionintegerRequiredCurrent version of this resource's owned state. Send it as `expected_version` when changing the resource to reject a stale write.
metaobjectAdditional information about this response.
api_versionstringAPI version used to produce this response.
idempotency_replayedbooleanWhether this response replays a stored result for the supplied Idempotency-Key.
trace_idstringTrace identifier to include when contacting Flint about this request.
warningsarray of objectConditions that need attention even though the request succeeded.
next_page_tokenstringOpaque token to send as `page_token` to retrieve the next page. Omitted when there is no next page.
request_idstringRequiredIdentifier of this API request, used to correlate logs and support requests.
curl https://api.withflintpay.com/v1/gift-card-redemptions \
-H "Flint-Version: 2026-09-07" \
-H "Authorization: Bearer YOUR_API_KEY"The gift card resource or committed command result.
{
"data": [
{
"capture_mode": "manual",
"captured_money": {
"amount": 0,
"currency": "USD"
},
"created_at": "2026-09-07T12:01:00Z",
"expires_at": "2026-09-07T12:16:00Z",
"gift_card_id": "gc_01KEZF7C00Z8CQGX4BKKBJ3B5S",
"gift_card_redemption_id": "gcr_01KEZF7C001PMCPZ9NFHJA7A7A",
"idempotency_key": "gift-card-reserve-1842",
"order_id": null,
"order_payment_attempt_id": null,
"refunded_money": {
"amount": 0,
"currency": "USD"
},
"remaining_refundable_money": {
"amount": 0,
"currency": "USD"
},
"requested_money": {
"amount": 1000,
"currency": "USD"
},
"reserved_money": {
"amount": 1000,
"currency": "USD"
},
"sale_reference": "pos-sale-1842",
"source_type": "external",
"status": "reserved",
"supported_actions": [
"cancel"
],
"updated_at": "2026-09-07T12:01:00Z",
"version": 1
}
],
"meta": {
"api_version": "2026-09-07"
},
"request_id": "req_01KWM6WAHG3N9Q8T2V5XRZ7C4D"
}Redeem gift card value#
/v1/gift-card-redemptionsKey requiredRequires scope commerce.gift_cards.redemptions.write
Rate limit: sensitive_write
Posts an exact amount automatically or reserves it for one full manual capture. Insufficient funds are rejected without a partial debit. Manual reservations default to 15 minutes and may be bounded up to 24 hours. External integrations coordinate and compensate their other tenders themselves. expected_gift_card_version fences the version of the card in gift_card_id.
Request body
Send exactly one of these
The `automatic` variant of `CreateGiftCardRedemptionRequest`.
amount_moneyobjectRequiredThe amount to redeem from the card.
amountintegerRequiredAmount in the currency's minor unit, such as cents for USD.
currencystringRequiredISO 4217 currency code for this amount.
capture_modeenumRequiredWhether the redemption spends the value now or reserves it to capture later.
automatic
expected_gift_card_versionintegerThe gift card version last read. The command changes this card only when its current version matches.
gift_card_idstringRequiredID of the gift card the value is spent from.
sale_referencestringRequiredYour reference for the sale the redemption pays for. Required; 1 to 255 characters. The value is preserved exactly as sent.
The `manual` variant of `CreateGiftCardRedemptionRequest`.
amount_moneyobjectRequiredThe amount to redeem from the card.
amountintegerRequiredAmount in the currency's minor unit, such as cents for USD.
currencystringRequiredISO 4217 currency code for this amount.
capture_modeenumRequiredWhether the redemption spends the value now or reserves it to capture later.
manual
expected_gift_card_versionintegerThe gift card version last read. The command changes this card only when its current version matches.
expires_atstringRFC3339 timestamp.
gift_card_idstringRequiredID of the gift card the value is spent from.
sale_referencestringRequiredYour reference for the sale the redemption pays for. Required; 1 to 255 characters. The value is preserved exactly as sent.
Response · 201
The gift card resource or committed command result.
dataobjectRequiredResource, collection, or operation result returned by this request.
gift_cardobjectRequiredThe gift card after the command.
gift_card_redemptionobjectRequiredThe redemption the command created or changed.
gift_card_transactionsarray of objectRequiredThe transactions the command posted to the card.
metaobjectAdditional information about this response.
api_versionstringAPI version used to produce this response.
idempotency_replayedbooleanWhether this response replays a stored result for the supplied Idempotency-Key.
trace_idstringTrace identifier to include when contacting Flint about this request.
warningsarray of objectConditions that need attention even though the request succeeded.
request_idstringRequiredIdentifier of this API request, used to correlate logs and support requests.
curl -X POST https://api.withflintpay.com/v1/gift-card-redemptions \
-H "Flint-Version: 2026-09-07" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: a-unique-key" \
-d '{
"amount_money": {
"amount": 1000,
"currency": "USD"
},
"capture_mode": "manual",
"expected_gift_card_version": 2,
"gift_card_id": "gc_01KEZF7C00Z8CQGX4BKKBJ3B5S",
"sale_reference": "pos-sale-1842"
}'Get a gift card redemption#
/v1/gift-card-redemptions/{gift_card_redemption_id}Requires scope commerce.gift_cards.adjustments.write or commerce.gift_cards.read or commerce.gift_cards.redemptions.write or commerce.gift_cards.secrets.write or commerce.gift_cards.write
Rate limit: read
Retrieves requested, reserved, captured, refunded and remaining refundable value with the current reservation status.
Path parameters
gift_card_redemption_idstringRequiredFlint resource ID.
Response · 200
The gift card resource or committed command result.
dataobjectRequiredResource, collection, or operation result returned by this request.
capture_modeenumRequiredWhether the redemption spends the value now or reserves it to capture later.
automaticmanual
captured_moneyobjectRequiredThe value captured from the card so far.
created_atstringRequiredRFC3339 timestamp.
expires_atstring or nullRequiredWhen an uncaptured manual reservation expires. `null` when `capture_mode` is `automatic`, which posts immediately.
gift_card_idstringRequiredID of the gift card the value is spent from.
gift_card_redemption_idstringRequiredUnique identifier for this gift card redemption, prefixed `gcr_`.
idempotency_keystring or nullRequiredYour Idempotency-Key for the command that created this record. `null` when Flint created it or no key was sent.
order_idstring or nullRequiredID of the Flint order the redemption pays for. `null` when `source_type` is `external`.
order_payment_attempt_idstring or nullRequiredThe order payment attempt the redemption belongs to. Set for source_type flint_order. `null` when `source_type` is `external`.
refunded_moneyobjectRequiredTotal refunded against this redemption across all refunds. Each refund lists its share in `tender_allocations`.
remaining_refundable_moneyobjectRequiredCaptured value not yet refunded. A refund allocation to this redemption can be at most this amount. Zero while the redemption is reserved, canceled, or expired.
requested_moneyobjectRequiredThe amount requested when the redemption was created.
reserved_moneyobjectRequiredThe value held on the card for this redemption while it is reserved.
sale_referencestring or nullRequiredYour reference for the sale the redemption pays for. Set for source_type external. `null` when `source_type` is `flint_order`.
source_typeenumRequiredWhat the redemption pays for: a sale you record, or a Flint order's payment.
externalflint_order
statusenumRequiredWhere the redemption is in its lifecycle.
reservedsucceededcanceledexpired
supported_actionsarray of enumRequiredLifecycle actions accepted for the stored redemption, independent of the caller's credentials. capture is available only before expires_at; cancel remains available until the reservation is resolved. Reservations for Flint orders are resolved through their payment attempt and list no actions.
capturecancel
updated_atstringRequiredRFC3339 timestamp.
versionintegerRequiredCurrent version of this resource's owned state. Send it as `expected_version` when changing the resource to reject a stale write.
metaobjectAdditional information about this response.
api_versionstringAPI version used to produce this response.
idempotency_replayedbooleanWhether this response replays a stored result for the supplied Idempotency-Key.
trace_idstringTrace identifier to include when contacting Flint about this request.
warningsarray of objectConditions that need attention even though the request succeeded.
request_idstringRequiredIdentifier of this API request, used to correlate logs and support requests.
curl https://api.withflintpay.com/v1/gift-card-redemptions/gcr_01KEZF7C002YD2G2J734RRZTWT \
-H "Flint-Version: 2026-09-07" \
-H "Authorization: Bearer YOUR_API_KEY"The gift card resource or committed command result.
{
"data": {
"capture_mode": "manual",
"captured_money": {
"amount": 0,
"currency": "USD"
},
"created_at": "2026-09-07T12:01:00Z",
"expires_at": "2026-09-07T12:16:00Z",
"gift_card_id": "gc_01KEZF7C00Z8CQGX4BKKBJ3B5S",
"gift_card_redemption_id": "gcr_01KEZF7C001PMCPZ9NFHJA7A7A",
"idempotency_key": "gift-card-reserve-1842",
"order_id": null,
"order_payment_attempt_id": null,
"refunded_money": {
"amount": 0,
"currency": "USD"
},
"remaining_refundable_money": {
"amount": 0,
"currency": "USD"
},
"requested_money": {
"amount": 1000,
"currency": "USD"
},
"reserved_money": {
"amount": 1000,
"currency": "USD"
},
"sale_reference": "pos-sale-1842",
"source_type": "external",
"status": "reserved",
"supported_actions": [
"cancel"
],
"updated_at": "2026-09-07T12:01:00Z",
"version": 1
},
"meta": {
"api_version": "2026-09-07"
},
"request_id": "req_01KWM6WAHG3N9Q8T2V5XRZ7C4D"
}Cancel a gift card reservation#
/v1/gift-card-redemptions/{gift_card_redemption_id}/cancelIdempotentRequires scope commerce.gift_cards.redemptions.write
Rate limit: sensitive_write
Releases an uncaptured standalone reservation without posting a debit or refund. Flint order reservations cannot be released while a processor outcome is unresolved. expected_version fences the redemption version.
Path parameters
gift_card_redemption_idstringRequiredFlint resource ID.
Request body
expected_versionintegerThe redemption version last read. Capture or cancel changes the redemption only when its current version matches.
Response · 200
The gift card resource or committed command result.
Same response as Redeem gift card value.
curl -X POST https://api.withflintpay.com/v1/gift-card-redemptions/gcr_01KEZF7C002YD2G2J734RRZTWT/cancel \
-H "Flint-Version: 2026-09-07" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: a-unique-key" \
-d '{
"expected_version": 1
}'Capture a gift card reservation#
/v1/gift-card-redemptions/{gift_card_redemption_id}/captureIdempotentRequires scope commerce.gift_cards.redemptions.write
Rate limit: sensitive_write
Posts the full reserved amount before the manual reservation expires. Capturing and expiry use the same concurrency fence. Flint order reservations are resolved by their payment attempt and cannot be captured through this standalone operation. expected_version fences the redemption version.
Path parameters
gift_card_redemption_idstringRequiredFlint resource ID.
Request body
expected_versionintegerThe redemption version last read. Capture or cancel changes the redemption only when its current version matches.
Response · 200
The gift card resource or committed command result.
Same response as Redeem gift card value.
curl -X POST https://api.withflintpay.com/v1/gift-card-redemptions/gcr_01KEZF7C002YD2G2J734RRZTWT/capture \
-H "Flint-Version: 2026-09-07" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: a-unique-key" \
-d '{
"expected_version": 1
}'List gift card transactions#
/v1/gift-card-transactionsRequires scope commerce.gift_cards.adjustments.write or commerce.gift_cards.read or commerce.gift_cards.redemptions.write or commerce.gift_cards.secrets.write or commerce.gift_cards.write
Rate limit: read
Lists immutable financial entries across the merchant in ascending merchant_sequence order. Per-card sequences and balance snapshots support reconciliation. Reservations and code replacement never create financial debits. Default order: merchant_sequence ascending; this key uniquely orders the results.
Query parameters
cash_out_referencestringExact, case-sensitive filter on your reference for the cash paid to the buyer outside Flint. Matches only cash_out transactions.
gift_card_idstringExact, case-sensitive filter.
idempotency_keystringFilter by the original Idempotency-Key, after trimming surrounding whitespace. Matching is exact and case-sensitive. Returns current authorized resources, not the recorded response. A pending resource does not prove that the operation succeeded, and an empty list does not prove that it had no effect.
order_idstringExact, case-sensitive filter.
page_sizeintegerMaximum number of results to return, from 1 to 100. Defaults to 20.
page_tokenstringOpaque next_page_token from the previous response. Omit on the first request. You may change `page_size` between pages. Reuse it with the same endpoint, filters, sort, and request context. Do not parse or construct tokens. An invalid, expired, or mismatched token returns a validation error.
posted_afterstringInclusive lower bound on posted_at.
posted_beforestringExclusive upper bound on posted_at.
source_idstringExact, case-sensitive filter.
source_typearray of enumExact, case-sensitive filter. Values are trimmed and deduplicated in first-seen order; empty or unknown entries are rejected. Values within this filter are ORed; separate filters are ANDed.
gift_card_funding_dispositiongift_card_loadgift_card_redemptionpurchase_refund_allocationrefundrefund_allocation
transaction_typearray of enumFilter by transaction_type. Values are trimmed and deduplicated in first-seen order; empty or unknown entries are rejected. Values within this filter are ORed; separate filters are ANDed.
loadimportredeemrefundrefund_transferadjustmentcash_outpurchase_reversalfunding_loss_acceptedpurchase_refund_recoverypurchase_refund_recovery_transfer
Response · 200
The gift card resource or committed command result.
dataarray of objectRequiredResource, collection, or operation result returned by this request.
amount_moneyobjectRequiredSigned change to the card's balance: positive amounts add value and negative amounts remove it. balance_after_money is balance_before_money plus this amount; funding_loss_accepted records a decision and moves 0.
balance_after_moneyobjectRequiredThe card's balance immediately after this transaction.
balance_before_moneyobjectRequiredThe card's balance immediately before this transaction.
cash_out_referencestring or nullRequiredYour reference for the cash you paid the buyer outside Flint. `null` when the transaction is not a cash_out.
gift_card_idstringRequiredGift card whose balance this transaction changed.
gift_card_transaction_idstringRequiredStable identifier of the transaction.
idempotency_keystring or nullRequiredYour Idempotency-Key for the command that created this record. `null` when Flint created it or no key was sent.
merchant_sequenceintegerRequiredPosition of this transaction among all of your gift card transactions in this environment. It increases by one with each posted transaction, and the transaction list is ordered by it.
order_idstringOrder this transaction belongs to, when there is one.
posted_atstringRequiredWhen the transaction was posted to the card.
reasonenum or nullRequiredYour adjustment reason on adjustment transactions, and customer_request on cash_out. `null` when the transaction is any other type.
complimentarybalance_accidentally_decreasedsupport_issuesuspicious_activitybalance_accidentally_increasedcustomer_requestnull
sequenceintegerRequiredPosition of this transaction in the card's history. It increases by one with each transaction posted to the card.
sourceobject or nullRequiredThe resource that caused this transaction, such as a gift_card_load, gift_card_redemption, refund, or gift_card_funding_disposition. `null` when the cause has no public resource.
transaction_typeenumRequiredKind of movement, such as load, redeem, refund, adjustment, or cash_out.
loadimportredeemrefundrefund_transferadjustmentcash_outpurchase_reversalfunding_loss_acceptedpurchase_refund_recoverypurchase_refund_recovery_transfer
metaobjectAdditional information about this response.
api_versionstringAPI version used to produce this response.
idempotency_replayedbooleanWhether this response replays a stored result for the supplied Idempotency-Key.
trace_idstringTrace identifier to include when contacting Flint about this request.
warningsarray of objectConditions that need attention even though the request succeeded.
next_page_tokenstringOpaque token to send as `page_token` to retrieve the next page. Omitted when there is no next page.
request_idstringRequiredIdentifier of this API request, used to correlate logs and support requests.
curl https://api.withflintpay.com/v1/gift-card-transactions \
-H "Flint-Version: 2026-09-07" \
-H "Authorization: Bearer YOUR_API_KEY"The gift card resource or committed command result.
{
"data": [
{
"amount_money": {
"amount": 5000,
"currency": "USD"
},
"balance_after_money": {
"amount": 5000,
"currency": "USD"
},
"balance_before_money": {
"amount": 0,
"currency": "USD"
},
"cash_out_reference": null,
"gift_card_id": "gc_01KEZF7C00Z8CQGX4BKKBJ3B5S",
"gift_card_transaction_id": "gct_01KEZF7C003RB1EP8BHZM729ZK",
"idempotency_key": "gift-card-import-1842",
"merchant_sequence": 1,
"posted_at": "2026-09-07T12:00:00Z",
"reason": null,
"sequence": 1,
"source": null,
"transaction_type": "import"
}
],
"meta": {
"api_version": "2026-09-07"
},
"request_id": "req_01KWM6WAHG3N9Q8T2V5XRZ7C4D"
}List gift cards#
/v1/gift-cardsRequires scope commerce.gift_cards.adjustments.write or commerce.gift_cards.read or commerce.gift_cards.redemptions.write or commerce.gift_cards.secrets.write or commerce.gift_cards.write
Rate limit: read
Lists gift cards in descending ID order within the authenticated merchant and environment. Reads include masked codes, posted balance, reserved value and available value. Purchased cards have no expiry or service fees. Default order: gift_card_id descending; this key uniquely orders the results.
Query parameters
created_afterstringInclusive lower bound on created_at.
created_beforestringExclusive upper bound on created_at.
customer_idstringExact, case-sensitive filter on the customer stored on the gift card. An unknown customer returns an empty page.
external_reference_idstringExact, case-sensitive filter.
idempotency_keystringFilter by the original Idempotency-Key, after trimming surrounding whitespace. Matching is exact and case-sensitive. Returns current authorized resources, not the recorded response. A pending resource does not prove that the operation succeeded, and an empty list does not prove that it had no effect.
page_sizeintegerMaximum number of results to return, from 1 to 100. Defaults to 20.
page_tokenstringOpaque next_page_token from the previous response. Omit on the first request. You may change `page_size` between pages. Reuse it with the same endpoint, filters, sort, and request context. Do not parse or construct tokens. An invalid, expired, or mismatched token returns a validation error.
statusarray of enumExact, case-sensitive filter. Values are trimmed and deduplicated in first-seen order; empty or unknown entries are rejected. Values within this filter are ORed; separate filters are ANDed.
activeclosedfrozenpending
Response · 200
The gift card resource or committed command result.
dataarray of objectRequiredResource, collection, or operation result returned by this request.
available_moneyobjectRequiredThe balance minus reserved value: what can be spent now.
balance_moneyobjectRequiredThe posted balance, including value reserved for redemptions in progress.
code_sourceenumRequiredOrigin of the current code: generated means Flint issued a random code; imported means the merchant supplied an existing code during import. Rotating the code resets this to generated.
generatedimported
created_atstringRequiredRFC3339 timestamp.
currencyenumRequiredISO 4217 currency code.
USD
customer_idstring or nullRequiredID of the customer associated with the card. `null` when no customer is associated.
external_reference_idstring or nullRequiredCaller-owned identifier for this resource in an external system. `null` when none is set.
gift_card_idstringRequiredUnique identifier for this gift card, prefixed `gc_`.
last4stringRequiredLast four characters of the card's current code.
last_loaded_atstring or nullRequiredRFC3339 timestamp. `null` when no value has been loaded onto the card.
last_redeemed_atstring or nullRequiredRFC3339 timestamp. `null` when the card has never been redeemed.
merchant_idstringRequiredID of the merchant this resource belongs to.
reserved_moneyobjectRequiredValue held for redemptions in progress. It isn't available to other payments until the redemption succeeds or is released.
restrictionsarray of objectRequiredThe restrictions that keep the card frozen. unfreeze is supported only when every restriction is merchant_freeze. A funding_dispute with dispute_status lost needs a gift card funding disposition.
statusenumRequiredWhere the card is in its lifecycle. Only an `active` card can be spent.
pendingactivefrozenclosed
supported_actionsarray of enumRequiredLifecycle actions accepted for the stored card state, independent of the caller's credentials. Empty when no action is available.
adjust_balancecash_outclosefreezeunfreeze
updated_atstringRequiredRFC3339 timestamp.
versionintegerRequiredCurrent version of this resource's owned state. Send it as `expected_version` when changing the resource to reject a stale write.
metaobjectAdditional information about this response.
api_versionstringAPI version used to produce this response.
idempotency_replayedbooleanWhether this response replays a stored result for the supplied Idempotency-Key.
trace_idstringTrace identifier to include when contacting Flint about this request.
warningsarray of objectConditions that need attention even though the request succeeded.
next_page_tokenstringOpaque token to send as `page_token` to retrieve the next page. Omitted when there is no next page.
request_idstringRequiredIdentifier of this API request, used to correlate logs and support requests.
curl https://api.withflintpay.com/v1/gift-cards \
-H "Flint-Version: 2026-09-07" \
-H "Authorization: Bearer YOUR_API_KEY"The gift card resource or committed command result.
{
"data": [
{
"available_money": {
"amount": 5000,
"currency": "USD"
},
"balance_money": {
"amount": 5000,
"currency": "USD"
},
"code_source": "generated",
"created_at": "2026-09-07T12:00:00Z",
"currency": "USD",
"customer_id": "cus_01KEZF7C003ACYXT6Q5EQZ78EE",
"external_reference_id": null,
"gift_card_id": "gc_01KEZF7C00Z8CQGX4BKKBJ3B5S",
"last4": "1234",
"last_loaded_at": "2026-09-07T12:00:00Z",
"last_redeemed_at": null,
"merchant_id": "mer_01KEZF7C00MPP0T9S0KH5BB4CC",
"reserved_money": {
"amount": 0,
"currency": "USD"
},
"restrictions": [],
"status": "active",
"supported_actions": [
"freeze",
"adjust_balance",
"cash_out"
],
"updated_at": "2026-09-07T12:00:00Z",
"version": 2
}
],
"meta": {
"api_version": "2026-09-07"
},
"request_id": "req_01KWM6WAHG3N9Q8T2V5XRZ7C4D"
}Create a gift card#
/v1/gift-cardsKey requiredRequires scope commerce.gift_cards.write
Rate limit: sensitive_write
Creates a merchant-issued USD gift card with optional paid funding or imported opening value. External funding is merchant-attested and does not collect a payment. The full code is returned only by issuance or code replacement and their authorized retries for 24 hours, while that code remains current. Replacing a code ends recovery of that code. Financial command identity is retained for the lifetime of the ledger.
Request body
codestringExisting gift card code, accepted only with funding.source.funding_source_type import. Must contain 16 gift card alphabet characters after removing spaces and hyphens; O maps to 0 and I/L to 1. The supplied code is never returned.
currencyenumRequiredISO 4217 currency code.
USD
customer_idstringID of the customer to associate with the card.
external_reference_idstringCaller-owned identifier for this resource in an external system.
fundingobject or nullThe card's initial value and where it came from. Omit it to create an unfunded `pending` card.
consideration_moneyobject or nullWhat the buyer paid for the value, separate from `value_money`. `null` when no payment amount is recorded.
sourceone ofRequiredWhere the value came from, with your reference for it.
source_created_atstringRFC3339 timestamp.
value_moneyobjectRequiredThe face value the load adds to the card.
notificationobjectOptional recipient notification recorded with issuance. Requires commerce.gift_cards.secrets.write in addition to issuance authority.
emailstringRequiredEmail address the notification is sent to.
messagestringMessage included in the notification.
namestringName of the person the notification is addressed to.
send_atstringOptional whole-second send time between now and 90 days from now.
Response · 201
The gift card resource or committed command result.
dataobjectRequiredResource, collection, or operation result returned by this request.
codestringThe full current code. Omitted after the 24-hour recovery window or when this code has been replaced.
code_recovery_expires_atstringWhen recovery of this code expires. Omitted when the code cannot be recovered.
gift_cardobjectRequiredThe gift card after the command.
gift_card_loadobjectThe load the command created.
gift_card_notificationobjectA message sent to a gift card recipient.
gift_card_transactionsarray of objectRequiredThe transactions the command posted to the card.
metaobjectAdditional information about this response.
api_versionstringAPI version used to produce this response.
idempotency_replayedbooleanWhether this response replays a stored result for the supplied Idempotency-Key.
trace_idstringTrace identifier to include when contacting Flint about this request.
warningsarray of objectConditions that need attention even though the request succeeded.
request_idstringRequiredIdentifier of this API request, used to correlate logs and support requests.
curl -X POST https://api.withflintpay.com/v1/gift-cards \
-H "Flint-Version: 2026-09-07" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: a-unique-key" \
-d '{
"currency": "USD",
"customer_id": "cus_01KEZF7C003ACYXT6Q5EQZ78EE",
"funding": {
"source": {
"customer_id": "cus_01KEZF7C003ACYXT6Q5EQZ78EE",
"external_reference_id": "legacy-card-1842",
"funding_source_type": "import"
},
"source_created_at": "2026-07-01T10:00:00Z",
"value_money": {
"amount": 5000,
"currency": "USD"
}
}
}'Get a gift card#
/v1/gift-cards/{gift_card_id}Requires scope commerce.gift_cards.adjustments.write or commerce.gift_cards.read or commerce.gift_cards.redemptions.write or commerce.gift_cards.secrets.write or commerce.gift_cards.write
Rate limit: read
Retrieves the current gift card, including supported lifecycle actions and balance projections. A gift card ID does not authorize a buyer to spend it.
Path parameters
gift_card_idstringRequiredFlint resource ID.
Response · 200
The gift card resource or committed command result.
dataobjectRequiredResource, collection, or operation result returned by this request.
available_moneyobjectRequiredThe balance minus reserved value: what can be spent now.
balance_moneyobjectRequiredThe posted balance, including value reserved for redemptions in progress.
code_sourceenumRequiredOrigin of the current code: generated means Flint issued a random code; imported means the merchant supplied an existing code during import. Rotating the code resets this to generated.
generatedimported
created_atstringRequiredRFC3339 timestamp.
currencyenumRequiredISO 4217 currency code.
USD
customer_idstring or nullRequiredID of the customer associated with the card. `null` when no customer is associated.
external_reference_idstring or nullRequiredCaller-owned identifier for this resource in an external system. `null` when none is set.
gift_card_idstringRequiredUnique identifier for this gift card, prefixed `gc_`.
last4stringRequiredLast four characters of the card's current code.
last_loaded_atstring or nullRequiredRFC3339 timestamp. `null` when no value has been loaded onto the card.
last_redeemed_atstring or nullRequiredRFC3339 timestamp. `null` when the card has never been redeemed.
merchant_idstringRequiredID of the merchant this resource belongs to.
reserved_moneyobjectRequiredValue held for redemptions in progress. It isn't available to other payments until the redemption succeeds or is released.
restrictionsarray of objectRequiredThe restrictions that keep the card frozen. unfreeze is supported only when every restriction is merchant_freeze. A funding_dispute with dispute_status lost needs a gift card funding disposition.
statusenumRequiredWhere the card is in its lifecycle. Only an `active` card can be spent.
pendingactivefrozenclosed
supported_actionsarray of enumRequiredLifecycle actions accepted for the stored card state, independent of the caller's credentials. Empty when no action is available.
adjust_balancecash_outclosefreezeunfreeze
updated_atstringRequiredRFC3339 timestamp.
versionintegerRequiredCurrent version of this resource's owned state. Send it as `expected_version` when changing the resource to reject a stale write.
metaobjectAdditional information about this response.
api_versionstringAPI version used to produce this response.
idempotency_replayedbooleanWhether this response replays a stored result for the supplied Idempotency-Key.
trace_idstringTrace identifier to include when contacting Flint about this request.
warningsarray of objectConditions that need attention even though the request succeeded.
request_idstringRequiredIdentifier of this API request, used to correlate logs and support requests.
curl https://api.withflintpay.com/v1/gift-cards/gc_01KEZF7C00RT1618WYBM1Y94CG \
-H "Flint-Version: 2026-09-07" \
-H "Authorization: Bearer YOUR_API_KEY"The gift card resource or committed command result.
{
"data": {
"available_money": {
"amount": 5000,
"currency": "USD"
},
"balance_money": {
"amount": 5000,
"currency": "USD"
},
"code_source": "generated",
"created_at": "2026-09-07T12:00:00Z",
"currency": "USD",
"customer_id": "cus_01KEZF7C003ACYXT6Q5EQZ78EE",
"external_reference_id": null,
"gift_card_id": "gc_01KEZF7C00Z8CQGX4BKKBJ3B5S",
"last4": "1234",
"last_loaded_at": "2026-09-07T12:00:00Z",
"last_redeemed_at": null,
"merchant_id": "mer_01KEZF7C00MPP0T9S0KH5BB4CC",
"reserved_money": {
"amount": 0,
"currency": "USD"
},
"restrictions": [],
"status": "active",
"supported_actions": [
"freeze",
"adjust_balance",
"cash_out"
],
"updated_at": "2026-09-07T12:00:00Z",
"version": 2
},
"meta": {
"api_version": "2026-09-07"
},
"request_id": "req_01KWM6WAHG3N9Q8T2V5XRZ7C4D"
}Update a gift card#
/v1/gift-cards/{gift_card_id}IdempotentRequires scope commerce.gift_cards.write
Rate limit: write
Updates descriptive associations. Omitted fields are preserved; null clears external_reference_id or customer_id. This operation cannot change balances, currency, code or status. expected_version fences the gift card version.
Path parameters
gift_card_idstringRequiredFlint resource ID.
Request body
customer_idstring or nullOmission preserves the association; null clears it.
expected_versionintegerThe gift card version last read. The command changes this card only when its current version matches.
external_reference_idstring or nullCaller-owned identifier for this resource in an external system. Omission preserves the association; null clears it.
curl -X PATCH https://api.withflintpay.com/v1/gift-cards/gc_01KEZF7C00RT1618WYBM1Y94CG \
-H "Flint-Version: 2026-09-07" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: a-unique-key" \
-d '{
"customer_id": "cus_01KEZF7C003ACYXT6Q5EQZ78EE",
"expected_version": 2
}'Adjust gift card value#
/v1/gift-cards/{gift_card_id}/adjust-balanceKey requiredRequires scope commerce.gift_cards.adjustments.write
Rate limit: sensitive_write
Posts a relative correction with a typed reason and separate administrative authority. Corrections cannot consume reserved funds, exceed funding limits, or replace linked refunds and purchase reversals. expected_version fences the gift card version.
Path parameters
gift_card_idstringRequiredFlint resource ID.
Request body
amount_moneyobjectRequiredNonzero USD amount to change the card's value by: positive adds value and negative removes it.
amountintegerRequiredSigned amount in the currency's minor unit, such as cents for USD.
currencystringRequiredISO 4217 currency code for this amount.
expected_versionintegerThe gift card version last read. The command changes this card only when its current version matches.
reasonenumRequiredWhy you're adjusting the value. A negative amount_money takes suspicious_activity, balance_accidentally_increased, or support_issue; a positive one takes complimentary, balance_accidentally_decreased, or support_issue.
complimentarybalance_accidentally_decreasedsupport_issuesuspicious_activitybalance_accidentally_increased
Response · 200
The gift card resource or committed command result.
dataobjectRequiredResource, collection, or operation result returned by this request.
gift_cardobjectRequiredThe gift card after the command.
gift_card_loadobjectThe load the command created.
gift_card_transactionsarray of objectRequiredThe transactions the command posted to the card.
metaobjectAdditional information about this response.
api_versionstringAPI version used to produce this response.
idempotency_replayedbooleanWhether this response replays a stored result for the supplied Idempotency-Key.
trace_idstringTrace identifier to include when contacting Flint about this request.
warningsarray of objectConditions that need attention even though the request succeeded.
request_idstringRequiredIdentifier of this API request, used to correlate logs and support requests.
curl -X POST https://api.withflintpay.com/v1/gift-cards/gc_01KEZF7C00RT1618WYBM1Y94CG/adjust-balance \
-H "Flint-Version: 2026-09-07" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: a-unique-key" \
-d '{
"amount_money": {
"amount": 500,
"currency": "USD"
},
"expected_version": 2,
"reason": "complimentary"
}'Record a cash-out#
/v1/gift-cards/{gift_card_id}/cash-outKey requiredRequires scope commerce.gift_cards.adjustments.write
Rate limit: sensitive_write
Records cash that the merchant attests it paid to the cardholder. Flint does not send cash. A freeze, restriction, or unresolved funding dispute blocks cash-out with ACTION_NOT_ALLOWED and reason restricted; remove the restriction before retrying. The amount cannot exceed unreserved value or consume payment reservations; cash_out_reference identifies the cash disbursement the merchant made outside Flint. expected_version fences the gift card version.
Path parameters
gift_card_idstringRequiredFlint resource ID.
Request body
amount_moneyobjectRequiredAmount of cash you paid the buyer outside Flint, taken off the gift card's balance. Above zero, in the card's currency, and not more than the card's unreserved value.
amountintegerRequiredAmount in the currency's minor unit, such as cents for USD.
currencystringRequiredISO 4217 currency code for this amount.
cash_out_referencestringRequiredYour reference for the cash you paid the buyer outside Flint, such as a receipt number. Required; 1 to 255 characters. The value is preserved exactly as sent.
expected_versionintegerThe gift card version last read. The command changes this card only when its current version matches.
Response · 200
The gift card resource or committed command result.
dataobjectRequiredResource, collection, or operation result returned by this request.
gift_cardobjectRequiredThe gift card after the cash-out.
gift_card_transactionsarray of objectRequiredThe transactions the cash-out posted to the card.
metaobjectAdditional information about this response.
api_versionstringAPI version used to produce this response.
idempotency_replayedbooleanWhether this response replays a stored result for the supplied Idempotency-Key.
trace_idstringTrace identifier to include when contacting Flint about this request.
warningsarray of objectConditions that need attention even though the request succeeded.
request_idstringRequiredIdentifier of this API request, used to correlate logs and support requests.
curl -X POST https://api.withflintpay.com/v1/gift-cards/gc_01KEZF7C00RT1618WYBM1Y94CG/cash-out \
-H "Flint-Version: 2026-09-07" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: a-unique-key" \
-d '{
"amount_money": {
"amount": 500,
"currency": "USD"
},
"cash_out_reference": "cash-receipt-1842",
"expected_version": 2
}'Close a gift card#
/v1/gift-cards/{gift_card_id}/closeIdempotentRequires scope commerce.gift_cards.write
Rate limit: sensitive_write
Permanently closes a card with zero balance, no reservations, no unresolved restrictions and no pending purchase refunds. expected_version fences the gift card version.
Path parameters
gift_card_idstringRequiredFlint resource ID.
Request body
expected_versionintegerThe gift card version last read. The command changes this card only when its current version matches.
curl -X POST https://api.withflintpay.com/v1/gift-cards/gc_01KEZF7C00RT1618WYBM1Y94CG/close \
-H "Flint-Version: 2026-09-07" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: a-unique-key" \
-d '{
"expected_version": 1
}'Freeze a gift card#
/v1/gift-cards/{gift_card_id}/freezeIdempotentRequires scope commerce.gift_cards.write
Rate limit: sensitive_write
Freezes spending on an active or frozen card with a merchant reason. Accepted payment reservations remain intact. expected_version fences the gift card version.
Path parameters
gift_card_idstringRequiredFlint resource ID.
Request body
expected_versionintegerThe gift card version last read. The command changes this card only when its current version matches.
reasonenumRequiredWhy the merchant is freezing spending.
suspicious_activitycustomer_requestsupport_issue
curl -X POST https://api.withflintpay.com/v1/gift-cards/gc_01KEZF7C00RT1618WYBM1Y94CG/freeze \
-H "Flint-Version: 2026-09-07" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: a-unique-key" \
-d '{
"expected_version": 2,
"reason": "customer_request"
}'Replace a gift card code#
/v1/gift-cards/{gift_card_id}/rotate-codeIdempotentRequires scope commerce.gift_cards.secrets.write
Rate limit: sensitive_write
Invalidates the old bearer credential and generates a new code for the same gift card. Balances, funding, reservations and refund history are preserved. Requires commerce.gift_cards.secrets.write. Include notification to send the new private recipient link. Retired links cannot open the current code. The new full code is available in this response and authorized retries only within 24 hours, while that code remains current. expected_version fences the gift card version.
Path parameters
gift_card_idstringRequiredFlint resource ID.
Request body
expected_versionintegerThe gift card version last read. The command changes this card only when its current version matches.
notificationobjectExplicitly send or schedule the replacement code through private recipient access. Requires commerce.gift_cards.secrets.write.
emailstringRequiredEmail address the notification is sent to.
messagestringMessage included in the notification.
namestringName of the person the notification is addressed to.
send_atstringOptional whole-second send time between now and 90 days from now.
Response · 200
The gift card resource or committed command result.
dataobjectRequiredResource, collection, or operation result returned by this request.
codestringThe full current code. Omitted after the 24-hour recovery window or when this code has been replaced.
code_recovery_expires_atstringWhen recovery of this code expires. Omitted when the code cannot be recovered.
gift_cardobjectRequiredThe gift card after the command.
gift_card_notificationobjectA message sent to a gift card recipient.
metaobjectAdditional information about this response.
api_versionstringAPI version used to produce this response.
idempotency_replayedbooleanWhether this response replays a stored result for the supplied Idempotency-Key.
trace_idstringTrace identifier to include when contacting Flint about this request.
warningsarray of objectConditions that need attention even though the request succeeded.
request_idstringRequiredIdentifier of this API request, used to correlate logs and support requests.
curl -X POST https://api.withflintpay.com/v1/gift-cards/gc_01KEZF7C00RT1618WYBM1Y94CG/rotate-code \
-H "Flint-Version: 2026-09-07" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: a-unique-key" \
-d '{
"expected_version": 2
}'Unfreeze a gift card#
/v1/gift-cards/{gift_card_id}/unfreezeIdempotentRequires scope commerce.gift_cards.write
Rate limit: sensitive_write
Removes a merchant freeze and restores spending. Unresolved funding-dispute restrictions refuse this action. expected_version fences the gift card version.
Path parameters
gift_card_idstringRequiredFlint resource ID.
Request body
expected_versionintegerThe gift card version last read. The command changes this card only when its current version matches.
curl -X POST https://api.withflintpay.com/v1/gift-cards/gc_01KEZF7C00RT1618WYBM1Y94CG/unfreeze \
-H "Flint-Version: 2026-09-07" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: a-unique-key" \
-d '{
"expected_version": 3
}'Look up a gift card code#
/v1/gift-cards/lookupRequires scope commerce.gift_cards.adjustments.write or commerce.gift_cards.read or commerce.gift_cards.redemptions.write or commerce.gift_cards.secrets.write or commerce.gift_cards.write
Rate limit: read
Evaluates a full bearer code in a request body. Codes contain 16 ASCII Crockford base32 characters, accept lowercase and hyphens, and normalize O to 0 and I/L to 1. Lookup is side-effect-free and never reserves funds. Unknown, other-merchant and unusable codes return the same error.
Request body
codestringRequiredThe gift card's code. Spaces and hyphens are ignored.
curl -X POST https://api.withflintpay.com/v1/gift-cards/lookup \
-H "Flint-Version: 2026-09-07" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"code": "0123456789AB1234"
}'Was this helpful?
