Orders are the central commerce resource in Flint. Every sale flows through an order: it holds line items, discounts, charges, tax, a requested tip, and the full pricing and settlement state for the transaction. Other resources attach to orders rather than replacing them: payments, refunds, invoices, checkout sessions, and subscriptions all read from and write back to an order.
Line items come from your catalog (a variant_id or bundle_id, with price and display resolved automatically) or are ad hoc (you provide the name and unit price). Adding inventory_demands makes an ad hoc line item tracked. An order stays open while you build it, then settles through payment: pay it in full, or close it explicitly when no balance remains. pricing_amounts reflects what the order should collect; settlement_amounts reflects what has been paid, refunded, and is still outstanding.
To buy a gift card, use a variant from a gift_card product. Add gift_card_purchase.face_value_money to select an amount within the variant's custom amount bounds; omit it for the reference denomination. Do not send unit_price_money on a catalog line. Flint calculates consideration from the configured offer and returns gift_card_purchase with the frozen configuration, reference price, selected face value, and consideration per card. quantity counts cards with those same per-card terms. Catalog price changes do not reprice an existing line.
The purchase can include a typed recipient with email, optional name, optional message of up to 200 characters, and optional send_at between now and 90 days from now. Recipient details describe email delivery independently of order fulfillment. Omit recipient to buy the card without email delivery. Explicit null values are not accepted for gift_card_purchase or its fields. Gift card purchases are non-taxable, excluded from ordinary discounts, and require no shipping or inventory.
Before funding starts, replace a purchase recipient with PATCH /v1/orders/{order_id}/line-items/{order_line_item_id}. Send gift_card_recipient and the line item's version as expected_version; send gift_card_recipient: null to clear it. Omission preserves the recipient. Checkout credentials can update these two fields together. Recipient edits preserve the frozen face value and consideration and keep the checkout open. Once a payment starts or the order has any payment, the purchase recipient cannot change.
To sell a catalog variant on subscribe and save, send subscription on its line when you create the order or add the line: subscription_offer_id, billing_interval, and billing_interval_count from an active subscription offer. Switch a line before payment with PATCH /v1/orders/{order_id}/line-items/{order_line_item_id}, sending subscription (or null for one-time) and the line item's version as expected_version. Checkout credentials can update these two fields together. When the order is paid, each subscribed line reports the subscription_id it started.
Pay for gift card purchases through the order payment route. The order must have a customer_id, or the checkout buyer must verify their identity before paying. A purchase over the buyer's funding or daily purchase limit is rejected before collection starts. A complete unit activates when its consideration is captured and settled. Partial payment of a unit leaves it unissued until the remaining consideration is collected; it does not expose a partially funded card. Each issued unit retains its original payment sources and the frozen face value and price. Retrying the same payment attempt recovers the same cards. Read line_items[].purchased_gift_cards for their IDs, unit ordinals, and last characters. Ordinary order reads never include redemption codes. Reversing an invoice manual payment removes the purchased value it backs. If any of that value has been spent or reserved, the reversal returns a conflict. Collecting that amount again restores the same purchased unit through a new paid load. If the original card is closed or cannot hold the value, purchased_gift_cards includes a replacement with the same unit_ordinal and an original_gift_card_id. Its restoration_reason is manual_recollection when a manual payment collects the amount again, or processor_recollection when a processor payment does. The original card and payment history remain available.
In checkout, the buyer's delivery selection writes delivery_destination, and while that selection is active you can't set the field directly. Any payment, including a recorded offline payment, sets frozen_at. Flint can't take a card or other online payment for an order with items to ship, deliver, or pick up until it has a delivery selection (FULFILLMENT_SELECTION_REQUIRED), so set delivery_destination yourself only for an order you collect outside Flint, such as an invoice paid with a recorded offline payment. Set it before you create the invoice: once an order has an invoice, even a draft, updating the order returns 409 INVOICE_LOCKED_ORDER_FINANCIALS. While the order is open and unpaid, you can replace the whole destination, or set it to null before removing its last delivery obligation. Correct a later delivery problem on fulfillment.recipient; that changes where the fulfillment runs without rewriting what the buyer committed to.
Use PATCH /v1/orders/{order_id} for scalar order changes. The same request can update metadata, delivery_destination, tax, and requested_tip. Set requested_tip to a fixed amount_money or a percent; set it to null to clear the current request. Set delivery_destination to null to clear it. Metadata values merge by key, and a null value removes that key.
Remove one line item or charge with its DELETE route. Remove several discounts in one request with POST /v1/orders/{order_id}/discounts/remove. Use POST /v1/orders/{order_id}/discounts/reprice after an eligibility input changes and you want Flint to recalculate the applied discounts.
If any line item resolves to a variant with inventory_tracking: "tracked", the order needs an inventory_routing_source before it can hold stock: either a fixed Location or an allocation policy. Flint holds the routed quantity when payment begins, commits it when payment succeeds, and consumes it when fulfillment hands the goods off. inventory_reservation_id points at the claim. If payment succeeds but the stock cannot be committed, inventory_exception_status reads paid_inventory_failed and the order waits for POST /v1/orders/{order_id}/inventory-exception/resolve, unless your settings tell Flint to refund automatically instead. See the Inventory guide for the whole path.
GET /v1/orders filters by payment_status, refund_status, and fulfillment_status. Each takes one value, a repeated parameter, or comma-separated values, and matches an order in any of them: payment_status=unpaid,partially_paid lists the orders with a balance still to collect. A customer session filters GET /v1/me/orders the same way.
For the model behind this design, see the Orders-first guide. To collect payment against an order, use checkout sessions for hosted payment, invoices for receivables, or payments for direct integration.
Select gift cards with POST /v1/orders/{order_id}/gift-cards. Send gift_card_code in the JSON body and order_revision from the latest order read. The response returns masked gift_cards in application order and a gift_card_estimate with gift card and processor amounts. Selection does not reserve or debit value. Gift cards apply to USD orders that are not subscriptions, and an order can select at most 20. The estimate excludes new gift card purchase value from the gift card allocation. In a mixed basket, selected cards can pay for other goods while the processor funds the gift card purchase.
After repeated failed codes, a checkout credential also needs a single-use proof in Flint-Gift-Card-Challenge, or the request fails with GIFT_CARD_CHALLENGE_REQUIRED; see Checkout credential verification.
Remove a selection with DELETE /v1/orders/{order_id}/gift-cards/{gift_card_id}, with the current order_revision in the JSON body. Both routes accept an optional Idempotency-Key to recover a lost response. They reject stale revisions and changes during an active payment attempt. If a selected card's code is replaced, its selection has requires_authorization: true and contributes no value until you apply its current code. gift_card_estimate.can_pay is false when a selection needs authorization, when a payment attempt has reserved the selection (is_reserved: true), or when an order under the $1.00 processor minimum is not fully covered by the cards. On larger orders, the estimate lowers the gift card amount when needed so the processor charge is at least $1.00.
When gift_card_estimate.can_pay is true, send accepted_gift_card_allocation with POST /v1/orders/{order_id}/pay. Copy order_revision, gift_cards, gift_card_money, and processor_money from the estimate, and send an Idempotency-Key. Paying with selected cards and no accepted_gift_card_allocation returns GIFT_CARD_ALLOCATION_REQUIRED. The allocation is checked again when payment starts. If it changed, read the order and accept the refreshed estimate before retrying with a new key.
Use action: "pay" with a payment_source when processor_money.amount is positive. The processor collects only that remainder. To confirm an existing payment intent, use action: "confirm_payment_intents" and select exactly one intent for the remainder. When the gift cards cover the full amount due, use action: "pay" without a payment source. Gift card payments collect the full amount due. The payment attempt returns masked gift_card_redemptions separately from payment_intents. Resume an existing attempt by its ID; its original allocation remains fixed while the processor outcome is unresolved.
Read gift_card_settlements for the original gift card amounts that paid the order. Each entry retains its redemption ID, masked last characters, tip allocation, and payment time after refunds or code replacement.
Read return_credit_settlements for value applied from items the buyer returned, such as an exchange's replacement order. Each entry identifies the Return and resolution, the amount_money applied, and created_at. This value is included in settlement_amounts.paid_money; show it separately from gift card and processor payments when explaining how the order was paid.
Send a receipt to a buyer-provided address with POST /v1/orders/{order_id}/send-receipt and { "email": "buyer@example.com" }. The receipt includes the order's settled payments and masked gift card payments, including orders paid entirely with gift cards. Send an Idempotency-Key to recover a lost response. The route requires Flint-managed receipt delivery and otherwise returns ORDER_RECEIPT_MERCHANT_MANAGED. Each order can send to the same normalized address once every five minutes. Addresses are trimmed and lowercased, preserving plus-addressing. Checkout credentials can send only to the address on file. If no address is on file, checkout credentials can send to at most three distinct addresses over the order's lifetime. Receipts sent for this order through this route count toward this limit, including failed deliveries and receipts sent with a secret API key. Send to an address already used, or send the receipt with a secret API key. Merchant callers can choose any address. Omit email to send to the order's recorded email. Buyers use POST /v1/me/orders/{order_id}/send-receipt, which accepts no email and sends to the order's email.
When you send your own receipt or shipping email, link the buyer to the order with POST /v1/orders/{order_id}/access-links. The url it returns opens the order in your Flint-hosted customer account without a sign-in, and lets the buyer have the receipt sent again, for 30 days or 10 opens. The url is a bearer credential: Flint returns it only in that response and in a retry with the same Idempotency-Key. The route needs commerce.orders.read, and refuses a merchant_hosted customer account and an order without a customer_id. See Link the buyer to their order.
curl -X POST https://api.withflintpay.com/v1/orders/ord_01J5Z8N3QK4W7Y2RB6TPVXHC9D/access-links \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Idempotency-Key: order-link-ord_01J5Z8N3QK4W7Y2RB6TPVXHC9D"