Skip to content

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.

A load's purchase_restoration names the original purchase's required order_id beside order_line_item_id, including previously stored loads. It identifies the order that sold that unit of the gift card.

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:

JSON
{ "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.

Generated and imported codes can be saved. Incorrect codes share a one-hour failure budget per buyer, IP address, and merchant environment. A cooldown returns 429 RATE_LIMIT_EXCEEDED with Retry-After. Wait for that many seconds before retrying; a new customer session does not reset the budget. Private recipient links remain usable during a code cooldown.

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 cards assigned to the buyer by customer_id, including refund and Return store credit, alongside cards with current saved access. Each card appears once. GET /v1/me/gift-cards/{gift_card_id} returns the card's masked identifier, status, balance, reserved amount, available amount, and timestamps. Both reads return can_remove. It is true when the buyer has current saved access and the card belongs to someone else or has no assigned customer.

Owned cards remain visible after code rotation. For saved cards without ownership, replacing the code ends access until the buyer saves again with fresh proof. Freezing or closing a card, or letting the original private link expire, preserves current saved access.

GET /v1/me/gift-card-transactions?gift_card_id={gift_card_id} returns the full anonymous balance-change history for an owned or currently saved card, including changes made by other holders. Detail and history reads return 404 when the buyer has neither form of access. 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, or creation time for owned cards without current saved access, then by 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 credential version.

DELETE /v1/me/gift-cards/{gift_card_id} removes only that buyer's saved access. Save returns 201. Remove returns 200 with the card snapshot and can_remove: false. A duplicate save returns the card without adding another entry. Remove returns 404 for owned cards, cards without current saved access, and repeated removals without the original idempotency key. Both writes accept an optional Idempotency-Key. 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. An outside sale or import batch can fund several cards with the same reference. Each card accepts that reference once per funding type. Repeating an external_payment or import reference on the same card under a new idempotency key returns 409 ALREADY_EXISTS at source.external_reference_id. Callers with gift card read permission also receive the existing load in details[0].current_resource. Reuse the original idempotency key to retry a load. 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; Scope and lifetime covers who shares a key and how long Flint keeps it. A replay returns the first response, rather than the card's current state. Cards, loads, redemptions, transactions, and funding dispositions can also be listed with an idempotency_key filter, which uses the key you sent. Other gift card writes, such as updates, freeze, unfreeze, close, code rotation, notifications, and redemption capture and cancel, accept an optional key. They keep a lasting record of each command, so a late retry with the same key doesn't run again; without a key, 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. A same-key retry returns the code again under the one-time secret rules, until code_recovery_expires_at. 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:

JSON
{"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.

CommandStatusdataVersion fence
POST /v1/gift-cards201gift_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 codeNone
POST /v1/gift-cards/{gift_card_id}/rotate-code200gift_card, code, code_recovery_expires_at, and gift_card_notification when you send notification. Rotation posts nothing, so there is no gift_card_transactionsexpected_version: data.gift_card.version
POST /v1/gift-card-loads201gift_card_load, gift_card, gift_card_transactionsexpected_gift_card_version: data.gift_card.version
POST /v1/gift-cards/{gift_card_id}/adjust-balance200gift_card, gift_card_transactions, and gift_card_load for a positive adjustmentexpected_version: data.gift_card.version
POST /v1/gift-cards/{gift_card_id}/cash-out200gift_card, gift_card_transactionsexpected_version: data.gift_card.version
POST /v1/gift-card-redemptions201gift_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 /cancel200gift_card_redemption, gift_card, gift_card_transactionsexpected_version: data.gift_card_redemption.version
PATCH /v1/gift-cards/{gift_card_id}, POST /v1/gift-cards/{gift_card_id}/freeze, /unfreeze, or /close200The gift card, which posts nothingexpected_version: data.version
POST /v1/gift-card-notifications201The notificationNone
POST /v1/gift-card-notifications/{gift_card_notification_id}/cancel200The notificationNone

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.

ResourceActionRoute
Gift cardfreezePOST /v1/gift-cards/{gift_card_id}/freeze
Gift cardunfreezePOST /v1/gift-cards/{gift_card_id}/unfreeze
Gift cardclosePOST /v1/gift-cards/{gift_card_id}/close
Gift cardadjust_balancePOST /v1/gift-cards/{gift_card_id}/adjust-balance
Gift cardcash_outPOST /v1/gift-cards/{gift_card_id}/cash-out
RedemptioncapturePOST /v1/gift-card-redemptions/{gift_card_redemption_id}/capture
RedemptioncancelPOST /v1/gift-card-redemptions/{gift_card_redemption_id}/cancel
NotificationcancelPOST /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.

LimitAmount
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 the request again. When remediation.next_steps says the request changed nothing, reuse its Idempotency-Key. Otherwise send a new 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:

JSON
{
  "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:

StatusMeaning
scheduledWaiting for the recipient's chosen send time.
pendingWaiting to send, or sending now. A notification for a pending card waits until the card is funded.
sentFlint's email service accepted the message. This doesn't mean the recipient opened it.
failedSending failed, or the recipient's email service bounced the message.
unconfirmedFlint's email service didn't confirm whether it sent the message. Flint doesn't resend it automatically.
canceledCancellation 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#

GET /v1/gift-cards and GET /v1/gift-card-loads list records newest first by created_at, with descending IDs breaking ties.

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. Each command sends at most one event for each resource it changed, so a capture sends gift_card.updated with the redemption, load, and transaction events, and a notification change leaves the card silent. See gift card 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.

StateRemaining balance eligible on requestConditions and source
CaliforniaLess than $15Operative April 1, 2026. Civil Code 1749.5
Colorado$5 or lessSingle-merchant cards. C.R.S. 6-1-722
ConnecticutLess than $5After a purchase; the statute has exclusions, including some discounted cards and out-of-state retailers. Consumer protection guidance
HawaiiLess than $5Consumer protection guidance
MaineLess than $5After 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 redeemedRetail rights guide, gift certificate guidance
MontanaLess than $5Original value must exceed $5. MCA 30-14-108
New JerseyLess than $5After redemption. Cash balance redemption guidance
New YorkLess than $5Division of Consumer Protection guidance
Oregon$5 or lessMost cards after a purchase; consult the linked guidance for exceptions. Department of Justice guidance
Rhode IslandLess than $1Remaining value after redemption. R.I. Gen. Laws 6-13-12
VermontLess than $18 V.S.A. 2704
WashingtonLess than $5Remaining 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 a headless 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. Granting commerce.gift_cards.secrets.write, accounts.api_keys.write, or accounts.workload_identities.write to an API key, workload identity, CLI login, or partner installation requires verification within the last 300 seconds in every mode; 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 with details[0].verified_at; verify again, get a new token, and retry with the same Idempotency-Key. Refreshing a token alone does not renew verification. Among machine callers, only a full-access key can grant these scopes; a restricted key, CLI login, or workload token gets 403 FORBIDDEN with reason full_access_required, even when it holds the scope.

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_moneyobjectRequired

The balance minus reserved value: what can be spent now.

balance_moneyobjectRequired

The posted balance, including value reserved for redemptions in progress.

code_sourceenumRequired

Origin 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.

  • generated
  • imported
created_atstringRequired

RFC3339 timestamp.

currencyenumRequired

ISO 4217 currency code.

  • USD
customer_idstring or nullRequired

ID of the customer associated with the card. `null` when no customer is associated.

external_reference_idstring or nullRequired

Caller-owned identifier for this resource in an external system. `null` when none is set.

gift_card_idstringRequired

Unique identifier for this gift card, prefixed `gc_`.

idempotency_keystring or nullRequired

The Idempotency-Key of the request that created this resource. `null` when that request sent no key, Flint created the resource, the reader isn't the caller that created it (another app install, a buyer, or the merchant reading an app's or buyer's record), or the caller that created an older record is unknown. Filter its list with `idempotency_key` to find it. Recorded payloads, including replayed responses and webhook events, can return `null`. To find a key that a replay returns as `null`, read the resource.

last4stringRequired

Last four characters of the card's current code.

last_loaded_atstring or nullRequired

RFC3339 timestamp. `null` when no value has been loaded onto the card.

last_redeemed_atstring or nullRequired

RFC3339 timestamp. `null` when the card has never been redeemed.

merchant_idstringRequired

ID of the merchant this resource belongs to.

reserved_moneyobjectRequired

Value held for redemptions in progress. It isn't available to other payments until the redemption succeeds or is released.

restrictionsarray of objectRequired

The 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.

statusenumRequired

Where the card is in its lifecycle. Only an `active` card can be spent.

  • pending
  • active
  • frozen
  • closed
supported_actionsarray of enumRequired

Lifecycle actions accepted for the stored card state, independent of the caller's credentials. Empty when no action is available.

  • adjust_balance
  • cash_out
  • close
  • freeze
  • unfreeze
updated_atstringRequired

RFC3339 timestamp.

versionintegerRequired

Current version of this resource's owned state. Send it as `expected_version` when changing the resource to reject a stale write.

JSON
{
  "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",
  "idempotency_key": null,
  "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_atstringRequired

When the disposition was created.

dispositionenumRequired

How 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_moneyobjectRequired

The 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_idstringRequired

The lost dispute this disposition resolves.

gift_card_funding_disposition_idstringRequired

Stable identifier of the disposition.

gift_card_idsarray of stringRequired

Gift cards whose value this disposition honors, including replacement cards that received value from the disputed funding.

honored_value_moneyobjectRequired

Unspent value that stays spendable under this disposition, summed across the affected cards, including replacement cards that received value from the disputed funding.

idempotency_keystring or nullRequired

The Idempotency-Key of the request that created this resource. `null` when that request sent no key, Flint created the resource, the reader isn't the caller that created it (another app install, a buyer, or the merchant reading an app's or buyer's record), or the caller that created an older record is unknown. Filter its list with `idempotency_key` to find it. Recorded payloads, including replayed responses and webhook events, can return `null`. To find a key that a replay returns as `null`, read the resource.

original_gift_card_consideration_moneyobjectRequired

What the buyer paid for the gift card value the disputed payment funded, summed across its funding loads.

payment_intent_idstringRequired

The disputed payment that funded the gift card value.

preserved_reserved_value_moneyobjectRequired

Part of honored_value_money that pending redemptions held when the disposition was created. It stays reserved for them.

reason_messagestringRequired

Your reason for honoring the value, from the create request.

JSON
{
  "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 nullRequired

What the buyer paid for the value, separate from `value_money`. `null` when no payment amount is recorded.

created_atstringRequired

RFC3339 timestamp.

funding_disputesarray of objectRequired

Restrictions 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_idstringRequired

ID of the gift card the load added value to.

gift_card_load_idstringRequired

Unique identifier for this gift card load, prefixed `gcl_`.

idempotency_keystring or nullRequired

The Idempotency-Key of the request that created this resource. `null` when that request sent no key, Flint created the resource, the reader isn't the caller that created it (another app install, a buyer, or the merchant reading an app's or buyer's record), or the caller that created an older record is unknown. Filter its list with `idempotency_key` to find it. Recorded payloads, including replayed responses and webhook events, can return `null`. To find a key that a replay returns as `null`, read the resource. Older records can return their key when the creating caller is unknown.

purchase_refund_value_holdsarray of object

Pending original cash refunds holding unspent value on this descendant funding lot. Unknown provider outcomes retain these holds.

purchase_refundsarray of objectRequired

Cash 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_restorationobject

Set when the buyer paid again for value that reversing a gift card purchase had removed, and this load restored it. Names the original card and load, the purchase refund entry that removed the value, and the purchased unit. Omitted for other loads.

refund_provenanceobject

Traces a load made by a refund back to its original funding. `null` when the load wasn't made by a refund.

refund_transferred_moneyobject

The part of this load's value that refunds of redemptions moved onto replacement gift cards. Omitted until a refund moves value.

remaining_moneyobjectRequired

The value from this load still on the card: not yet spent, reversed, or moved to a replacement card. It includes value held by a reserved redemption.

reversed_moneyobjectRequired

The value removed from this load by refunding or reversing the purchase that funded it. It goes down again when a purchase refund fails and the value is restored.

sourceone ofRequired

Where the value came from, with your reference for it.

source_created_atstring or nullRequired

RFC3339 timestamp. `null` when no source time was recorded.

value_moneyobjectRequired

The face value the load adds to the card.

versionintegerRequired

Current version of this resource's owned state. Send it as `expected_version` when changing the resource to reject a stale write.

JSON
{
  "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_atstringRequired

RFC3339 timestamp.

deliveryobject

Included 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_idstringRequired

ID of the gift card the notification is about.

gift_card_notification_idstringRequired

Unique identifier for this gift card notification, prefixed `gcn_`.

recipientobjectRequired

Who the notification is sent to.

resend_of_notification_idstring

ID of the earlier notification this one sends again.

sent_atstring

RFC3339 timestamp.

statusenumRequired

Where sending the notification stands. Read `delivery` for the attempts and email events behind it.

  • scheduled
  • pending
  • sent
  • failed
  • unconfirmed
  • canceled
status_reasonenum or nullRequired

Why 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_rotated
  • null
supported_actionsarray of enumRequired

Lifecycle actions accepted for this notification's stored state, independent of the caller's credentials. Empty when none are available.

  • cancel
updated_atstringRequired

RFC3339 timestamp.

versionintegerRequired

Current version of this resource's owned state. Send it as `expected_version` when changing the resource to reject a stale write.

JSON
{
  "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_modeenumRequired

Whether the redemption spends the value now or reserves it to capture later.

  • automatic
  • manual
captured_moneyobjectRequired

The value captured from the card so far.

created_atstringRequired

RFC3339 timestamp.

expires_atstring or nullRequired

When an uncaptured manual reservation expires. `null` when `capture_mode` is `automatic`, which posts immediately.

gift_card_idstringRequired

ID of the gift card the value is spent from.

gift_card_redemption_idstringRequired

Unique identifier for this gift card redemption, prefixed `gcr_`.

idempotency_keystring or nullRequired

The Idempotency-Key of the request that created this resource. `null` when that request sent no key, Flint created the resource, the reader isn't the caller that created it (another app install, a buyer, or the merchant reading an app's or buyer's record), or the caller that created an older record is unknown. Filter its list with `idempotency_key` to find it. Recorded payloads, including replayed responses and webhook events, can return `null`. To find a key that a replay returns as `null`, read the resource. Older records can return their key when the creating caller is unknown.

order_idstring or nullRequired

ID of the Flint order the redemption pays for. `null` when `source_type` is `external`.

order_payment_attempt_idstring or nullRequired

The order payment attempt the redemption belongs to. Set for source_type flint_order. `null` when `source_type` is `external`.

refunded_moneyobjectRequired

Total refunded against this redemption across all refunds. Each refund lists its share in `tender_allocations`.

remaining_refundable_moneyobjectRequired

Captured value available to refund to this redemption. Order redemption reads account for refunds and value reserved by exchanges or order edits. Zero while the redemption is reserved, canceled, or expired.

requested_moneyobjectRequired

The amount requested when the redemption was created.

reserved_moneyobjectRequired

The value held on the card for this redemption while it is reserved.

sale_referencestring or nullRequired

Your reference for the sale the redemption pays for. Set for source_type external. `null` when `source_type` is `flint_order`.

source_typeenumRequired

What the redemption pays for: a sale you record, or a Flint order's payment.

  • external
  • flint_order
statusenumRequired

Where the redemption is in its lifecycle.

  • reserved
  • succeeded
  • canceled
  • expired
supported_actionsarray of enumRequired

Lifecycle 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.

  • capture
  • cancel
updated_atstringRequired

RFC3339 timestamp.

versionintegerRequired

Current version of this resource's owned state. Send it as `expected_version` when changing the resource to reject a stale write.

JSON
{
  "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#

GET/v1/gift-card-funding-dispositions

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

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_afterstring

Inclusive lower bound on created_at.

created_beforestring

Exclusive upper bound on created_at.

dispute_idstring

Exact, case-sensitive filter.

idempotency_keystring

Filter by the original Idempotency-Key, after trimming surrounding whitespace. Matching is exact and case-sensitive. Returns only resources created in your caller namespace, plus resources created before caller scoping under the original key. 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. A match can show `idempotency_key: null` when that request sent no key, Flint created the resource, the reader isn't the caller that created it (another app install, a buyer, or the merchant reading an app's or buyer's record), or the caller that created an older record is unknown.

page_sizeinteger

Maximum number of results to return, from 1 to 100. Defaults to 20.

page_tokenstring

Opaque, signed next_page_token from the previous response, bound to the list and caller. 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 altered, invalid, expired, or mismatched token returns a validation error.

Response · 200

The gift card resource or committed command result.

dataarray of objectRequired

Resource, collection, or operation result returned by this request.

metaobject

Additional information about this response.

next_page_tokenstring

Opaque token to send as `page_token` to retrieve the next page. Omitted when there is no next page.

request_idstringRequired

Identifier 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.

JSON
{
  "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#

POST/v1/gift-card-funding-dispositionsKey required

Requires 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

dispositionenum

What the merchant decided about the card's value after the funding payment lost a dispute.

  • honor_value
dispute_idstringRequired

The lost dispute on the payment that funded the gift card value.

reason_messagestringRequired

Your reason for honoring the gift card value despite the confirmed funding loss.

Response · 201

The created gift card funding disposition.

dataobjectRequired

Resource, collection, or operation result returned by this request.

metaobject

Additional information about this response.

request_idstringRequired

Identifier 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#

GET/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_idstringRequired

Flint resource ID. Must be a valid ID with prefix gfd_. Malformed IDs return 400 INVALID_REQUEST with detail INVALID_VALUE; well-formed IDs that do not exist return 404 RESOURCE_NOT_FOUND.

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.

JSON
{
  "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#

GET/v1/gift-card-loads

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

Lists funding lots newest first by created_at, with descending ID order for ties. 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_afterstring

Inclusive lower bound on created_at.

created_beforestring

Exclusive upper bound on created_at.

funding_source_typearray of enum

Exact, 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.

  • adjustment
  • external_payment
  • flint_manual_payment
  • flint_payment
  • gift_card_purchase_refund_recovery
  • gift_card_refund
  • import
  • store_credit
gift_card_idstring

Exact, case-sensitive filter.

idempotency_keystring

Filter by the original Idempotency-Key, after trimming surrounding whitespace. Matching is exact and case-sensitive. Returns only resources created in your caller namespace, plus resources created before caller scoping under the original key. 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. A match can show `idempotency_key: null` when that request sent no key, Flint created the resource, the reader isn't the caller that created it (another app install, a buyer, or the merchant reading an app's or buyer's record), or the caller that created an older record is unknown.

order_idstring

Exact, case-sensitive filter.

page_sizeinteger

Maximum number of results to return, from 1 to 100. Defaults to 20.

page_tokenstring

Opaque, signed next_page_token from the previous response, bound to the list and caller. 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 altered, invalid, expired, or mismatched token returns a validation error.

source_external_reference_idstring

Exact, 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 objectRequired

Resource, collection, or operation result returned by this request.

metaobject

Additional information about this response.

next_page_tokenstring

Opaque token to send as `page_token` to retrieve the next page. Omitted when there is no next page.

request_idstringRequired

Identifier 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.

JSON
{
  "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#

POST/v1/gift-card-loadsKey required

Requires 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 null

What the buyer paid for the value, separate from `value_money`. `null` when no payment amount is recorded.

expected_gift_card_versioninteger

The gift card version last read. The command changes this card only when its current version matches.

gift_card_idstringRequired

The gift card to load.

sourceone ofRequired

Where the value came from, with your reference for it.

source_created_atstring

RFC3339 timestamp.

value_moneyobjectRequired

The face value the load adds to the card.

Response · 201

The gift card resource or committed command result.

dataobjectRequired

Resource, collection, or operation result returned by this request.

metaobject

Additional information about this response.

request_idstringRequired

Identifier 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#

GET/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_idstringRequired

Flint resource ID. Must be a valid ID with prefix gcl_. Malformed IDs return 400 INVALID_REQUEST with detail INVALID_VALUE; well-formed IDs that do not exist return 404 RESOURCE_NOT_FOUND.

Response · 200

The gift card resource or committed command result.

dataobjectRequired

Resource, collection, or operation result returned by this request.

metaobject

Additional information about this response.

request_idstringRequired

Identifier 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.

JSON
{
  "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#

GET/v1/gift-card-notifications

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

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_afterstring

Inclusive lower bound on created_at.

created_beforestring

Exclusive upper bound on created_at.

gift_card_idstring

Exact, case-sensitive filter.

page_sizeinteger

Maximum number of results to return, from 1 to 100. Defaults to 20.

page_tokenstring

Opaque, signed next_page_token from the previous response, bound to the list and caller. 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 altered, invalid, expired, or mismatched token returns a validation error.

statusarray of enum

Exact, 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.

  • canceled
  • failed
  • pending
  • scheduled
  • sent
  • unconfirmed

Response · 200

The gift card resource or committed command result.

dataarray of objectRequired

Resource, collection, or operation result returned by this request.

metaobject

Additional information about this response.

next_page_tokenstring

Opaque token to send as `page_token` to retrieve the next page. Omitted when there is no next page.

request_idstringRequired

Identifier 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.

JSON
{
  "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#

POST/v1/gift-card-notificationsIdempotent

Requires 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_idstringRequired

ID of the gift card the notification is about.

recipientobjectRequired

Who the notification is sent to.

resend_of_notification_idstring

ID of the earlier notification this one sends again.

Response · 201

The gift card resource or committed command result.

dataobjectRequired

Resource, collection, or operation result returned by this request.

metaobject

Additional information about this response.

request_idstringRequired

Identifier 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#

GET/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_idstringRequired

Flint resource ID. Must be a valid ID with prefix gcn_. Malformed IDs return 400 INVALID_REQUEST with detail INVALID_VALUE; well-formed IDs that do not exist return 404 RESOURCE_NOT_FOUND.

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.

JSON
{
  "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#

POST/v1/gift-card-notifications/{gift_card_notification_id}/cancelIdempotent

Requires 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_idstringRequired

Flint resource ID. Must be a valid ID with prefix gcn_. Malformed IDs return 400 INVALID_REQUEST with detail INVALID_VALUE; well-formed IDs that do not exist return 404 RESOURCE_NOT_FOUND.

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#

GET/v1/gift-card-redemptions

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

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_afterstring

Inclusive lower bound on created_at.

created_beforestring

Exclusive upper bound on created_at.

gift_card_idstring

Exact, case-sensitive filter.

idempotency_keystring

Filter by the original Idempotency-Key, after trimming surrounding whitespace. Matching is exact and case-sensitive. Returns only resources created in your caller namespace, plus resources created before caller scoping under the original key. 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. A match can show `idempotency_key: null` when that request sent no key, Flint created the resource, the reader isn't the caller that created it (another app install, a buyer, or the merchant reading an app's or buyer's record), or the caller that created an older record is unknown.

order_idstring

Exact, case-sensitive filter.

page_sizeinteger

Maximum number of results to return, from 1 to 100. Defaults to 20.

page_tokenstring

Opaque, signed next_page_token from the previous response, bound to the list and caller. 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 altered, invalid, expired, or mismatched token returns a validation error.

sale_referencestring

Exact, case-sensitive filter on your reference for the sale. Matches only external redemptions.

source_typearray of enum

Exact, 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.

  • external
  • flint_order
statusarray of enum

Exact, 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.

  • canceled
  • expired
  • reserved
  • succeeded

Response · 200

The gift card resource or committed command result.

dataarray of objectRequired

Resource, collection, or operation result returned by this request.

metaobject

Additional information about this response.

next_page_tokenstring

Opaque token to send as `page_token` to retrieve the next page. Omitted when there is no next page.

request_idstringRequired

Identifier 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.

JSON
{
  "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#

POST/v1/gift-card-redemptionsKey required

Requires 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_moneyobjectRequired

The amount to redeem from the card.

capture_modeenumRequired

Whether the redemption spends the value now or reserves it to capture later.

  • automatic
expected_gift_card_versioninteger

The gift card version last read. The command changes this card only when its current version matches.

gift_card_idstringRequired

ID of the gift card the value is spent from.

sale_referencestringRequired

Your 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.

dataobjectRequired

Resource, collection, or operation result returned by this request.

metaobject

Additional information about this response.

request_idstringRequired

Identifier 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#

GET/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_idstringRequired

Flint resource ID. Must be a valid ID with prefix gcr_. Malformed IDs return 400 INVALID_REQUEST with detail INVALID_VALUE; well-formed IDs that do not exist return 404 RESOURCE_NOT_FOUND.

Response · 200

The gift card resource or committed command result.

dataobjectRequired

Resource, collection, or operation result returned by this request.

metaobject

Additional information about this response.

request_idstringRequired

Identifier 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.

JSON
{
  "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#

POST/v1/gift-card-redemptions/{gift_card_redemption_id}/cancelIdempotent

Requires 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_idstringRequired

Flint resource ID. Must be a valid ID with prefix gcr_. Malformed IDs return 400 INVALID_REQUEST with detail INVALID_VALUE; well-formed IDs that do not exist return 404 RESOURCE_NOT_FOUND.

Request body

expected_versioninteger

The 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#

POST/v1/gift-card-redemptions/{gift_card_redemption_id}/captureIdempotent

Requires 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_idstringRequired

Flint resource ID. Must be a valid ID with prefix gcr_. Malformed IDs return 400 INVALID_REQUEST with detail INVALID_VALUE; well-formed IDs that do not exist return 404 RESOURCE_NOT_FOUND.

Request body

expected_versioninteger

The 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#

GET/v1/gift-card-transactions

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

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_referencestring

Exact, case-sensitive filter on your reference for the cash paid to the buyer outside Flint. Matches only cash_out transactions.

gift_card_idstring

Exact, case-sensitive filter.

idempotency_keystring

Filter by the original Idempotency-Key, after trimming surrounding whitespace. Matching is exact and case-sensitive. Returns only resources created in your caller namespace, plus resources created before caller scoping under the original key. 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. A match can show `idempotency_key: null` when that request sent no key, Flint created the resource, the reader isn't the caller that created it (another app install, a buyer, or the merchant reading an app's or buyer's record), or the caller that created an older record is unknown.

order_idstring

Exact, case-sensitive filter.

page_sizeinteger

Maximum number of results to return, from 1 to 100. Defaults to 20.

page_tokenstring

Opaque, signed next_page_token from the previous response, bound to the list and caller. 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 altered, invalid, expired, or mismatched token returns a validation error.

posted_afterstring

Inclusive lower bound on posted_at.

posted_beforestring

Exclusive upper bound on posted_at.

source_idstring

Exact, case-sensitive filter.

source_typearray of enum

Exact, 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_disposition
  • gift_card_load
  • gift_card_redemption
  • purchase_refund_allocation
  • refund
  • refund_allocation
transaction_typearray of enum

Filter 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.

  • load
  • import
  • redeem
  • refund
  • refund_transfer
  • adjustment
  • cash_out
  • purchase_reversal
  • funding_loss_accepted
  • purchase_refund_recovery
  • purchase_refund_recovery_transfer

Response · 200

The gift card resource or committed command result.

dataarray of objectRequired

Resource, collection, or operation result returned by this request.

metaobject

Additional information about this response.

next_page_tokenstring

Opaque token to send as `page_token` to retrieve the next page. Omitted when there is no next page.

request_idstringRequired

Identifier 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.

JSON
{
  "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#

GET/v1/gift-cards

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

Lists gift cards newest first by created_at, with descending ID order for ties 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_afterstring

Inclusive lower bound on created_at.

created_beforestring

Exclusive upper bound on created_at.

customer_idstring

Exact, case-sensitive filter on the customer stored on the gift card. An unknown customer returns an empty page.

external_reference_idstring

Exact, case-sensitive filter.

idempotency_keystring

Filter by the original Idempotency-Key, after trimming surrounding whitespace. Matching is exact and case-sensitive. Returns only resources created in your caller namespace, plus resources created before caller scoping under the original key. 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. A match can show `idempotency_key: null` when that request sent no key, Flint created the resource, the reader isn't the caller that created it (another app install, a buyer, or the merchant reading an app's or buyer's record), or the caller that created an older record is unknown.

page_sizeinteger

Maximum number of results to return, from 1 to 100. Defaults to 20.

page_tokenstring

Opaque, signed next_page_token from the previous response, bound to the list and caller. 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 altered, invalid, expired, or mismatched token returns a validation error.

statusarray of enum

Exact, 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.

  • active
  • closed
  • frozen
  • pending

Response · 200

The gift card resource or committed command result.

dataarray of objectRequired

Resource, collection, or operation result returned by this request.

metaobject

Additional information about this response.

next_page_tokenstring

Opaque token to send as `page_token` to retrieve the next page. Omitted when there is no next page.

request_idstringRequired

Identifier 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.

JSON
{
  "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",
      "idempotency_key": null,
      "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#

POST/v1/gift-cardsKey required

Requires 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

codestring

Existing 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.

currencyenumRequired

ISO 4217 currency code.

  • USD
customer_idstring

ID of the customer to associate with the card.

external_reference_idstring

Caller-owned identifier for this resource in an external system.

fundingobject or null

The card's initial value and where it came from. Omit it to create an unfunded `pending` card.

notificationobject

Optional recipient notification recorded with issuance. Requires commerce.gift_cards.secrets.write in addition to issuance authority.

Response · 201

The gift card resource or committed command result.

dataobjectRequired

Resource, collection, or operation result returned by this request.

metaobject

Additional information about this response.

request_idstringRequired

Identifier 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#

GET/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_idstringRequired

Flint resource ID. Must be a valid ID with prefix gc_. Malformed IDs return 400 INVALID_REQUEST with detail INVALID_VALUE; well-formed IDs that do not exist return 404 RESOURCE_NOT_FOUND.

Response · 200

The gift card resource or committed command result.

dataobjectRequired

Resource, collection, or operation result returned by this request.

metaobject

Additional information about this response.

request_idstringRequired

Identifier 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.

JSON
{
  "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",
    "idempotency_key": null,
    "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#

PATCH/v1/gift-cards/{gift_card_id}Idempotent

Requires 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_idstringRequired

Flint resource ID. Must be a valid ID with prefix gc_. Malformed IDs return 400 INVALID_REQUEST with detail INVALID_VALUE; well-formed IDs that do not exist return 404 RESOURCE_NOT_FOUND.

Request body

customer_idstring or null

Omission preserves the association; null clears it.

expected_versioninteger

The gift card version last read. The command changes this card only when its current version matches.

external_reference_idstring or null

Caller-owned identifier for this resource in an external system. Omission preserves the association; null clears it.

Response · 200

The gift card resource or committed command result.

Same response as Get a gift card.

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#

POST/v1/gift-cards/{gift_card_id}/adjust-balanceKey required

Requires 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_idstringRequired

Flint resource ID. Must be a valid ID with prefix gc_. Malformed IDs return 400 INVALID_REQUEST with detail INVALID_VALUE; well-formed IDs that do not exist return 404 RESOURCE_NOT_FOUND.

Request body

amount_moneyobjectRequired

Nonzero USD amount to change the card's value by: positive adds value and negative removes it.

expected_versioninteger

The gift card version last read. The command changes this card only when its current version matches.

reasonenumRequired

Why 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.

  • complimentary
  • balance_accidentally_decreased
  • support_issue
  • suspicious_activity
  • balance_accidentally_increased

Response · 200

The gift card resource or committed command result.

dataobjectRequired

Resource, collection, or operation result returned by this request.

metaobject

Additional information about this response.

request_idstringRequired

Identifier 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#

POST/v1/gift-cards/{gift_card_id}/cash-outKey required

Requires 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_idstringRequired

Flint resource ID. Must be a valid ID with prefix gc_. Malformed IDs return 400 INVALID_REQUEST with detail INVALID_VALUE; well-formed IDs that do not exist return 404 RESOURCE_NOT_FOUND.

Request body

amount_moneyobjectRequired

Amount 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.

cash_out_referencestringRequired

Your 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_versioninteger

The 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.

dataobjectRequired

Resource, collection, or operation result returned by this request.

metaobject

Additional information about this response.

request_idstringRequired

Identifier 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#

POST/v1/gift-cards/{gift_card_id}/closeIdempotent

Requires 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_idstringRequired

Flint resource ID. Must be a valid ID with prefix gc_. Malformed IDs return 400 INVALID_REQUEST with detail INVALID_VALUE; well-formed IDs that do not exist return 404 RESOURCE_NOT_FOUND.

Request body

expected_versioninteger

The 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.

Same response as Get a gift card.

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#

POST/v1/gift-cards/{gift_card_id}/freezeIdempotent

Requires 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_idstringRequired

Flint resource ID. Must be a valid ID with prefix gc_. Malformed IDs return 400 INVALID_REQUEST with detail INVALID_VALUE; well-formed IDs that do not exist return 404 RESOURCE_NOT_FOUND.

Request body

expected_versioninteger

The gift card version last read. The command changes this card only when its current version matches.

reasonenumRequired

Why the merchant is freezing spending.

  • suspicious_activity
  • customer_request
  • support_issue

Response · 200

The gift card resource or committed command result.

Same response as Get a gift card.

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#

POST/v1/gift-cards/{gift_card_id}/rotate-codeIdempotent

Requires 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_idstringRequired

Flint resource ID. Must be a valid ID with prefix gc_. Malformed IDs return 400 INVALID_REQUEST with detail INVALID_VALUE; well-formed IDs that do not exist return 404 RESOURCE_NOT_FOUND.

Request body

expected_versioninteger

The gift card version last read. The command changes this card only when its current version matches.

notificationobject

Explicitly send or schedule the replacement code through private recipient access. Requires commerce.gift_cards.secrets.write.

Response · 200

The gift card resource or committed command result.

dataobjectRequired

Resource, collection, or operation result returned by this request.

metaobject

Additional information about this response.

request_idstringRequired

Identifier 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#

POST/v1/gift-cards/{gift_card_id}/unfreezeIdempotent

Requires 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_idstringRequired

Flint resource ID. Must be a valid ID with prefix gc_. Malformed IDs return 400 INVALID_REQUEST with detail INVALID_VALUE; well-formed IDs that do not exist return 404 RESOURCE_NOT_FOUND.

Request body

expected_versioninteger

The 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.

Same response as Get a gift card.

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#

POST/v1/gift-cards/lookup

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

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

codestringRequired

The gift card's code. Spaces and hyphens are ignored.

Response · 200

The gift card resource or committed command result.

Same response as Get a gift card.

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?