Return resolutions
A return resolution is what the buyer gets for approved Return quantity: money back, store credit, different merchandise, the same merchandise again, or nothing. It belongs to a Return, and once confirmed, Flint carries it out through ordinary Refunds, PaymentIntents, and Orders that link back to it.
Use this resource to read and act on outcomes: list what a Return owes, confirm or cancel a proposal, release a held resolution, retry a failure, or correct one that already settled. The Return resolutions guide walks through each outcome with full requests and responses.
From preview to settled#
- Preview with
POST /v1/return-previewsandmode: "resolution". Flint prices the outcome and reserves or starts nothing. - Propose with
POST /v1/returns/{return_id}/resolutions. The resolution isproposedand reserves its line quantity, so no other resolution can claim the same approved units. - Edit or cancel the proposal with
PATCHor/cancel. Canceling frees its quantity. - Confirm with
/confirm. The amounts freeze, and the effects start once each line'srelease_timingallows.
You don't always make these calls yourself. A resolution sent in POST /v1/returns/{return_id}/process is created and confirmed in that one request. When a policy or a decision resolves a line automatically through automatic_resolution_type, Flint creates and confirms a refund, store_credit, or no_monetary_action resolution for it; see What automatic decides. Those resolutions follow the same lifecycle as yours.
Note: Confirmed isn't paid
A successful confirm fixes the amounts. It doesn't mean money moved or goods shipped. Read status, execution_blockers, and the linked resources to know what has happened.
Types#
resolution_type | The buyer gets | Flint creates |
|---|---|---|
refund | Money back on the original payment | A Refund |
store_credit | The returned value on new gift cards | A Refund to new gift cards, with no processor refund |
exchange | Different merchandise | A replacement Order, plus a Refund or a PaymentIntent for any difference |
replacement | The same merchandise again | A replacement Order, plus a Refund or a PaymentIntent for any difference |
no_monetary_action | Nothing, because no value is owed | Nothing |
correction | An adjustment to a resolution that settled | A Refund for a net credit. See Corrections |
Every type except correction names the Return lines it covers in line_items: up to 100 entries, each with a return_line_item_id and a whole-number quantity that is approved and not claimed by another resolution. A Return line can appear only once per resolution. exchange and replacement also need replacement_line_items, up to 100, and a pricing_basis; Choose replacement merchandise covers both.
The resolution lists what it creates in refund_ids, payment_intent_ids, and replacement_order_id. Each Refund and the replacement Order carry return_resolution_id back, so GET /v1/refunds?return_resolution_id= finds every Refund a resolution made.
Store credit#
A store_credit resolution refunds the returned value onto new Flint gift cards instead of the original payment. It is priced, gated, and confirmed like a refund. buyer_refund_amount_money is the value issued on the new cards.
Every payment on the order that still has refundable value must be able to fund store credit. Flint checks this on create, on confirm, and when a decision or process call resolves a line automatically; a refusal returns 409 ACTION_NOT_ALLOWED with reason store_credit_unavailable. If the order stops qualifying after you confirm, the resolution fails with the failure code of the same name. Store credit lists which payments qualify.
Who sends the new cards' codes to the buyer follows customer_email_delivery.returns; see Delivering the gift card. The resolution is fulfilled once the value is on the cards, whether or not an email went out.
Where gift card value goes#
gift_card_refund_destination decides where the part the buyer paid by gift card goes. original, the default, credits the card that paid; new_gift_card issues that value on new cards. Value paid any other way goes back to the original payment.
| Resolution | gift_card_refund_destination |
|---|---|
refund, exchange, and a correction of anything but store_credit | Accepted and echoed on the resolution |
store_credit, and a correction of it | Rejected. The value always goes on new gift cards |
replacement, no_monetary_action | Rejected |
Send it on create, on a resolution in /process, on PATCH while the resolution is proposed, or on /retry. Flint never moves gift card value to new cards on its own: when the original card is closed or the amount would pass its balance cap, the resolution fails with gift_card_refund_destination_required, and you retry with new_gift_card.
Amounts#
Every type except no_monetary_action combines its amounts the same way:
returned_total_money + credit_adjustment_money - deduction_money - replacement_total_money
A positive result is buyer_refund_amount_money. A negative one is buyer_payment_amount_money, which the buyer pays through the resolution's checkout session; only an exchange or replacement can have one. replacement_total_money is the replacement Order's total, including its tax. Confirming freezes all of these amounts.
- Returned value
returned_total_money$54.00 - Restocking fee
deduction_money−$5.00 - Replacement Order
replacement_total_moneyTax included−$39.00 - Refunded to the buyer
buyer_refund_amount_money$10.00
Adjustments#
Fees and credits are adjustments on the resolution, not separate objects, so they stay in the same arithmetic as the refund. The Return's financial_summary reports their totals as deduction_money and credit_adjustment_money, apart from refunded_money, so nothing is netted out of sight.
| Field | Rule |
|---|---|
adjustment_type | restocking_fee, return_shipping_fee, other_fee, goodwill_credit, price_correction, or other |
value_effect | deduction adds to deduction_money; credit adds to credit_adjustment_money |
assessed_amount_money, applied_amount_money | Both required and in one currency. The applied amount can't exceed the assessed amount |
reason | Required |
status | Defaults to applied, or to waived when you send a waiver_reason. A waived adjustment applies zero |
return_line_item_id | Scopes a deduction to one line. It can't exceed that line's returned total on the resolution |
All deductions together can't exceed the returned total plus credits, and a resolution carries at most 50 adjustments. Fees covers the usual value_effect for each type and the fees a policy adds for you.
Lifecycle#
Moves back
- requires_action → pendingperson acts
- failed → pendingretry
- proposed moves to pending on confirm
- proposed moves to canceled on cancel
- pending moves to requires_action on waits on a person
- requires_action moves to pending on person acts
- pending moves to fulfilled on value delivered
- pending moves to failed on effect fails
- failed moves to pending on retry
- failed moves to canceled on cancel
- pending moves to canceled on cancel before an effect starts
- requires_action moves to canceled on cancel before an effect starts
Confirming can skip pending: a resolution held by manual timing goes straight to requires_action, and a no_monetary_action resolution with nothing to wait for goes straight to fulfilled. A pending or requires_action resolution can be canceled until it starts a Refund, PaymentIntent, or Order; an exchange whose balance is unpaid can be canceled after that too, as Canceling an unpaid exchange describes.
status on return resolutionproposedCreated, not confirmed. Nothing runs. You can edit it withPATCH, confirm it, or cancel it.pendingConfirmed, and executing or waiting onexecution_blockers.requires_actionWaiting on a person.action_required_bysays who andaction_reasonsays why, such asmanual_releaseuntil a merchant calls/release, orbuyer_paymentwhile the buyer's payment for a balance needs them. Once they act, it returns topending.fulfilledFinalThe buyer has the value: every linked Refund succeeded, any balance was collected, and any replacement Order'sfulfillment_statusisfulfilledornot_applicable. A correction can adjust it afterward.failedExecution stopped.failure_codesays why and whether retrying can help. See Failure codes.canceledFinalCanceled. Its quantity is free for another resolution.
supported_actions lists what can succeed now: confirm, cancel, release, retry, and checkout_session. While the parent Return isn't open it holds at most checkout_session. Check it before calling an action instead of calling to find out.
A resolution's own status never reads partially_fulfilled, and the status filter on GET /v1/return-resolutions rejects it. Only the Return's aggregate resolution_status reports it; see Resolution status.
Execution blockers#
A confirmed resolution stays pending while execution_blockers names what it waits for. Each blocker has a code, a return_line_item_id for a line gate, and a linked_resource when it waits on another resource.
code | Cleared by |
|---|---|
handoff_pending | The buyer handing the merchandise to a carrier |
receipt_pending | The merchandise being received |
inspection_pending | An inspection accepting it |
manual_release_pending | A merchant calling /release |
buyer_payment_pending | The buyer paying the balance |
refund_pending | The linked Refund succeeding |
replacement_order_pending | Flint creating the replacement Order |
fulfillment_pending | The replacement Order, in linked_resource, being fulfilled |
While manual_release_pending is present, or buyer_payment_pending waits on the buyer to act, the resolution is requires_action instead of pending.
The first four come from each line's release_timing, which the decision sets and the resolution's line_items echo. It gates every type, including exchanges and replacements:
release_timing | The resolution runs |
|---|---|
after_approval | As soon as it's confirmed |
after_handoff | Once the buyer hands the merchandise to a carrier |
after_receipt | Once the merchandise is received |
after_inspection | Once an inspection accepts it, or on receipt when the line's inspection is waived |
manual | When a merchant calls /release, which works only while action_reason is manual_release |
The gate counts units per line. A resolution releases only when the line's handed-off, received, or accepted quantity covers it plus every resolution already released on that line, up to the line's return_required_quantity.
An exchange or replacement isn't fulfilled until its replacement Order is, and that Order must be paid before it can be fulfilled. Exchanges and replacements wait for fulfillment covers how each Order becomes paid, and When the buyer owes money covers the checkout session for a balance.
Failure codes#
A failed resolution carries failure_code and failure_message. supported_actions includes retry only when the code allows it.
failure_code on return resolutiongift_card_refund_destination_requiredRetryable. The original gift card is closed, or the amount would pass its balance cap. Retry withgift_card_refund_destination: "new_gift_card".store_credit_unavailableNot retryable. The order's payments can no longer fund store credit. Cancel the resolution, then create arefundresolution.refund_creation_failedRetryable. Flint couldn't create the Refund after retrying.refund_failedRetryable. The Refund was created and failed;failure_messagesays why. Fix the cause, then retry, which creates a new Refund.refund_line_value_unavailableNot retryable. Another refund already covered part of an order line, so this refund can't be paid. Cancel the resolution, then resolve fewer units or choose an outcome without a refund.payment_intent_creation_failedRetryable. Flint couldn't create the buyer's PaymentIntent after retrying. Retry resumes the payment.payment_failedRetryable. The buyer's PaymentIntent was canceled or expired. Retry, then launch/checkout-sessionsagain for the new payment.replacement_order_creation_failedRetryable. Flint couldn't create the replacement Order after retrying.replacement_fulfillment_canceledFinal. The replacement Order's fulfillment was canceled, so the goods won't be sent. The resolution offers neither retry nor cancel, and the Return shows aresolution_failedcompletion blocker. To send a replacement another way, fail the fulfillment instead of canceling it; see Cancel, fail, and try again.resolution_effect_failedRetryable. Another execution failure. Retry, and contact support if it repeats.
failure_code is extensible. Treat a code you don't recognize as not retryable: show failure_message and don't retry it automatically.
Retry starts a new attempt and requires a reason. Earlier Refund and PaymentIntent IDs stay on the resolution, and a late event from an earlier attempt can't settle the new one. A gift_card_refund_destination sent with the retry is saved on the resolution before the attempt starts, so later retries keep it.
Cancel works on a failed resolution only when it never created a Refund, PaymentIntent, or Order, or when it is an exchange whose balance is unpaid; see Canceling an unpaid exchange. When it created a Refund that isn't failed or canceled, cancel returns 409 ACTION_NOT_ALLOWED with reason refund_created. Read that Refund instead of creating another.
Cancellation reasons#
POST /v1/return-resolutions/{return_resolution_id}/cancel requires a reason: buyer_request, merchant_request, duplicate, expired, created_in_error, or other. It also accepts a reason_message. Canceling a resolution that is already canceled returns it unchanged, with its original reason.
| Field | Where it appears |
|---|---|
cancellation_reason | Every read, including the buyer's /v1/me/return-resolutions view |
cancellation_reason_message | Merchant reads only |
canceled_by | Merchant reads only. The actor, with an actor_type and an actor_id when one exists |
cancellation_reason is extensible, so render values you don't recognize generically. action_reason is a different field: it says what a confirmed resolution waits for, and it clears when the resolution is canceled.
/release and /retry also require a reason, but those actions can repeat, so their reasons aren't fields on the resolution. Read them from GET /v1/returns/{return_id}/activities, where each entry carries the actor, the reason, and the Return version it produced. See Return activities.
Corrections#
Confirmed money movements are never edited backward. To change the value of a resolution that already settled, reopen its Return and create a resolution with resolution_type: "correction" and corrects_return_resolution_id.
- The target must be
fulfilledand belong to the same Return, and the Return must be open. - A correction carries only
adjustments, with at least one applied adjustment above zero.line_items,replacement_line_items, andpricing_basisare rejected. - It pays out like its target. A correction of
store_creditissues new gift cards; any other correction refunds the original payment and takes its owngift_card_refund_destination. - A net credit creates an ordinary linked Refund when confirmed. Deductions can bring the credit to zero, but a correction that would leave the buyer owing money is rejected, because a correction has no Order for the buyer to pay through.
The original resolution and its Refunds stay as they were. GET /v1/return-resolutions?corrects_return_resolution_id= lists every correction of a resolution. Fixing one after it settled shows the reopen and correction requests.
Writes#
PATCH /v1/return-resolutions/{return_resolution_id} changes a resolution only while it is proposed. It takes line_items, replacement_line_items, adjustments, pricing_basis, gift_card_refund_destination, metadata, and external_reference_id.
The three arrays are owned collections. A present array replaces that collection atomically and requires the resolution's expected_version; an omitted array stays as it is. Within an array:
- Send a member's stable ID to keep it:
return_resolution_line_item_id,return_replacement_line_item_id, orreturn_resolution_adjustment_id. - Send a member without an ID to add it. Create rejects member IDs, because a new resolution has nothing to keep.
- Leave a member out to remove it, or send
[]to remove them all.
Every replacement line sends its type, including lines you keep: variant with variant_id, bundle with bundle_id, or custom with name, unit_price_money, and fulfillment. Custom lines use the same fulfillment input as order lines; send {"requirement":"none"} when nothing is delivered.
Confirm, release, cancel, and retry accept an optional expected_version to make sure you act on the version you reviewed. Create takes expected_return_version, a fence on the parent Return; Writes covers both kinds of version check.
Updating adjustments#
An adjustment you send back with its return_resolution_adjustment_id takes the fields you send, and its ID stays the same for as long as you keep it. A waived adjustment sent back with the same status, waiver_reason, and waiver_reason_message keeps its waived_by and waived_at. Changing any of the three records you as the waiver, at the time of the request.
Errors#
- StatusHTTP 400CodeINVALID_
REQUEST What to dodetails[0]names the field. AREQUIREDdetail withparam: "expected_version"means aPATCHsent an array without the version. AnINVALID_VALUEdetail on a member ID, such asadjustments[0].return_resolution_adjustment_id, means the ID belongs to another resolution or appears twice. AnINVALID_VALUEdetail on an adjustment'sapplied_amount_money.amountmeans a deduction exceeds what it can reduce. ANOT_ALLOWEDdetail withconflicting_fields: ["resolution_type", "gift_card_refund_destination"]means the type doesn't take a gift card destination. - StatusHTTP 409What to doThe resolution's state or the order refuses the action, and
details[0].reasonsays why.terminal_status: the resolution isfulfilledorcanceled.unsupported_state: another status, or a retry of afailure_codethat retrying can't fix.refund_created: canceling a failed resolution whose Refund isn'tfailedorcanceled;remediation.next_actionsoffersget_refund.refund_unavailableorstore_credit_unavailable: on create or confirm, the order's payments can't fund arefundorstore_credit, anddetails[0]names the order. Readsupported_actionsand choose another action or outcome. - StatusHTTP 409What to doThe
expected_versionorexpected_return_versionyou sent is stale.details[0].current_versionhas the current version. Read the resource again, check what changed, and resend.
Expand the replacement order in the list#
GET /v1/return-resolutions accepts expand=replacement_order, which needs commerce.orders.read as well as a returns read scope. Each resolution with a replacement_order_id gains replacement_order, the order's summary, and the others return replacement_order: null. The summary matches the one on the single-resolution read, including the order's recorded buyer_contact; see Expanded order summaries. payment_intents and refunds expand only on GET /v1/return-resolutions/{return_resolution_id}.
curl -G https://api.withflintpay.com/v1/return-resolutions \
-H "Authorization: Bearer YOUR_API_KEY" \
--data-urlencode "resolution_type=exchange" \
--data-urlencode "expand=replacement_order"
Webhooks#
- return_
resolution. created A resolution was proposed, by you or by a policy. - return_
resolution. updated Its status, blockers, amounts, linked resources, or cancellation fields changed. The payload is the full resolution.
The Refunds, PaymentIntents, and Orders a resolution creates send their own events. How this lands elsewhere covers how they link back.
Related guides#
Return resolutionsPreview, confirm, collect a balance, and correct a resolution, with full requests.ReturnsHow a Return's decision, merchandise, and value statuses fit together.RefundsThe lifecycle of the Refund a resolution creates.The Return resolution object#
The refund, exchange, or other outcome of a return.
Returned by GET /v1/return-resolutions/{return_resolution_id} and carried by the endpoints below.
Attributes
action_reasonenumWhat the resolution waits for while its status is `requires_action`.
buyer_paymentbuyer_selectionmerchant_reviewmanual_releaselinked_effect_retryother
action_required_byenumWho has to act while the resolution's status is `requires_action`.
buyermerchant
adjustmentsarray of objectRequiredFees and credits applied to the resolution's amounts.
adjustment_typeenumRequiredWhat the fee or credit is for.
return_shipping_feerestocking_feeother_feegoodwill_creditprice_correctionother
applied_amount_moneyobjectRequiredAmount that counts toward the resolution. It can't exceed `assessed_amount_money`, and is zero when the adjustment is waived.
assessed_amount_moneyobjectRequiredAmount the fee or credit comes to before any waiver. Same currency as `applied_amount_money`.
reasonenumRequiredWhy the adjustment was made.
return_policyinspection_resultreturn_shipping_costcustomer_servicemanual_correctionother
reason_messagestringOptional detail about `reason`, kept with the record.
return_line_item_idstringID of the Return line a deduction applies to. Absent when it applies to the resolution as a whole.
return_policy_revision_idstringreturn_resolution_adjustment_idstringRequiredUnique identifier for this return resolution adjustment, prefixed `retadj_`.
statusenumRequiredWhether the adjustment counts toward the buyer's value. A waived adjustment applies zero.
appliedwaived
value_effectenumRequiredWhether the adjustment reduces or increases what the buyer receives.
deductioncredit
waived_atstringRFC3339 timestamp.
waived_byobjectWho waived the adjustment.
waiver_reasonenumWhy the adjustment was waived.
policy_overridemerchant_reviewcustomer_serviceother
waiver_reason_messagestringDetail about `waiver_reason`.
buyer_payment_amount_moneyobjectRequiredAmount the buyer owes when deduction_money and replacement_total_money exceed returned_total_money plus credit_adjustment_money. Zero when the buyer is owed a refund and for no_monetary_action.
amountintegerRequiredAmount in the currency's minor unit, such as cents for USD.
currencystringRequiredISO 4217 currency code for this amount.
buyer_refund_amount_moneyobjectRequiredValue returned to the buyer: returned_total_money plus credit_adjustment_money, minus deduction_money and replacement_total_money, when that balance is zero or more. For store_credit, the value issued on new gift cards. Zero for no_monetary_action.
amountintegerRequiredAmount in the currency's minor unit, such as cents for USD.
currencystringRequiredISO 4217 currency code for this amount.
canceled_atstringRFC3339 timestamp.
canceled_byobjectWho canceled the resolution. Merchant reads only.
Not returned with a customer session
actor_idstringID of the actor, when one exists. Merchant reads only.
actor_typeenumRequiredWhat kind of actor acted.
buyermerchantintegrationsystem
cancellation_reasonenumWhy the resolution was canceled.
buyer_requestmerchant_requestduplicateexpiredcreated_in_errorother
cancellation_reason_messagestringDetail sent with the cancellation. Merchant reads only.
Not returned with a customer session
confirmed_atstringRFC3339 timestamp.
confirmed_byobjectWho confirmed the resolution.
Not returned with a customer session
actor_idstringID of the actor, when one exists. Merchant reads only.
actor_typeenumRequiredWhat kind of actor acted.
buyermerchantintegrationsystem
corrects_return_resolution_idstringID of the settled resolution this correction adjusts. Present only when `resolution_type` is `correction`.
Not returned with a customer session
created_atstringRequiredRFC3339 timestamp.
created_byobjectRequiredWho created the resolution.
Not returned with a customer session
actor_idstringID of the actor, when one exists. Merchant reads only.
actor_typeenumRequiredWhat kind of actor acted.
buyermerchantintegrationsystem
credit_adjustment_moneyobjectRequiredCredits added by the resolution's adjustments.
amountintegerRequiredAmount in the currency's minor unit, such as cents for USD.
currencystringRequiredISO 4217 currency code for this amount.
deduction_moneyobjectRequiredDeductions taken by the resolution's adjustments, such as a restocking fee.
amountintegerRequiredAmount in the currency's minor unit, such as cents for USD.
currencystringRequiredISO 4217 currency code for this amount.
execution_blockersarray of objectRequiredWhat a confirmed resolution is still waiting for. Empty when nothing is.
codeenumRequiredhandoff_pending: The buyer has not handed off the required merchandise. receipt_pending: Required merchandise has not been received. inspection_pending: Required inspection is incomplete. manual_release_pending: The merchant must release the resolution. buyer_payment_pending: The buyer's balance has not been collected. refund_pending: A linked Refund has not succeeded. replacement_order_pending: The replacement Order has not been created. fulfillment_pending: The replacement Order, in linked_resource, has units not yet fulfilled.
handoff_pendingreceipt_pendinginspection_pendingmanual_release_pendingbuyer_payment_pendingrefund_pendingreplacement_order_pendingfulfillment_pending
linked_resourceobjectThe resource the blocker waits on, such as a Refund or the replacement Order.
Not returned with a customer session
return_line_item_idstringID of the Return line the blocker gates. Absent when it applies to the whole resolution.
external_reference_idstringCaller-owned identifier for this resource in an external system.
Not returned with a customer session
failure_codeenumReason code for a failed Return resolution, when available. refund_line_value_unavailable means another refund already returned part of an order line, so retrying cannot succeed; cancel the resolution and resolve the line for fewer units or without a refund. replacement_fulfillment_canceled means the replacement Order's fulfillment was canceled, so it won't be sent. gift_card_refund_destination_required means the original gift card cannot accept the refund; retry with gift_card_refund_destination set to new_gift_card. store_credit_unavailable means the original payment cannot fund store credit; cancel the resolution and create a refund resolution.
gift_card_refund_destination_requiredstore_credit_unavailablerefund_creation_failedrefund_failedrefund_line_value_unavailablepayment_intent_creation_failedpayment_failedreplacement_order_creation_failedreplacement_fulfillment_canceledresolution_effect_failed
failure_messagestringExplanation of a failed Return resolution, when available.
fulfilled_atstringWhen the resolution became fulfilled.
gift_card_refund_destinationenumWhere the gift-card-paid portion is refunded. original credits the original gift card; new_gift_card issues new gift cards. Accepted for refund, exchange, and correction, except a correction of store_credit. Omit for store_credit, replacement, and no_monetary_action; sending it returns INVALID_REQUEST with a NOT_ALLOWED detail and conflicting_fields naming resolution_type and gift_card_refund_destination. Store credit and its corrections always issue new gift cards. PATCH can change it only while proposed. Retry persists the chosen destination before starting the new attempt.
originalnew_gift_card
line_itemsarray of objectRequiredReturn lines and quantities the resolution covers. Absent on a correction.
quantityintegerRequiredWhole-number quantity; fractional quantities are not supported.
release_timingenumRelease gate for every resolution type, including exchanges and replacements. Released after the Return is approved. Released after the buyer hands back the required merchandise. Released after the required merchandise is received. Released after the required merchandise passes inspection. Held until a merchant calls POST /v1/return-resolutions/{id}/release.
after_approvalafter_handoffafter_receiptafter_inspectionmanual
return_line_item_idstringRequiredID of the Return line the resolution covers.
return_resolution_idstringRequiredID of the resolution the line belongs to.
return_resolution_line_item_idstringRequiredID of an existing resolution line to keep. Leave out to add a new line.
returned_total_moneyobjectRequiredValue of the returned units this line covers.
metadatamap of stringRequiredStored caller-owned key-value data. See `MetadataInput` for key, value, and size rules.
payment_intent_idsarray of stringRequiredNot returned with a customer session
payment_intentsarray of objectNot returned with a customer session
amount_moneyobjectRequiredThe amount requested from the buyer, including any tip_money. Capturing doesn't change it: after a partial capture it still shows the requested amount, and captured_money shows what was collected. On a standalone payment intent, PATCH can change it only before the first confirmation attempt.
capture_methodenumWhen money is collected. Defaults to automatic.
automaticmanual
created_atstringRFC3339 timestamp.
customer_idstringCustomer linked to this payment intent.
order_idstringOrder this payment intent belongs to. Create it through the order and confirm it with POST /v1/orders/{order_id}/pay. Capture and cancel use POST /v1/payment-intents/{payment_intent_id}/capture or /cancel for every payment intent. Order-owned intents accept PATCH for metadata and external_reference_id.
payment_intent_idstringRequiredFlint payment intent ID.
payment_sourceobjectSummary of the card or bank account used for the payment. Absent until a payment source is attached.
refund_statusenumHow much of captured_money has been refunded, including value issued as store credit, based on refunded_money.
nonepartially_refundedrefunded
statusenumRequiredLifecycle status. requires_payment_method covers both a new payment intent and one whose last attempt failed, so read last_payment_error with it. succeeded, canceled, and expired are final. Refunds and disputes never change status.
requires_payment_methodrequires_confirmationrequires_actionprocessingrequires_capturecanceledsucceededexpired
updated_atstringRFC3339 timestamp.
versionintegerRequiredPersisted version of this resource's owned state. Expanded resources and external observations can change independently.
pricing_basisenumHow replacement lines are priced. Present on exchanges and replacements.
original_pricecurrent_pricemerchant_agreed_price
refund_idsarray of stringRequiredNot returned with a customer session
refundsarray of objectNot returned with a customer session
amount_moneyobjectRequiredTotal refunded across all tenders, including `refunded_tip_money`.
created_atstringRequiredRFC3339 timestamp.
credit_note_idstringID of the credit note this refund paid out. Present only on refunds issued through a credit note.
customerobject or nullPresent only when `expand` includes `customer`; `null` when expanded and there is no related customer.
customer_idstringID of the customer on the refunded order or payment. Absent when neither has one.
external_reference_idstringCaller-owned identifier for this resource in an external system.
failure_reasonenumWhy a refund failed or a payment refund was canceled. Failed and canceled amounts become refundable again. Fix the cause, then create a new refund with a new idempotency key. Unknown provider values are returned as refund_failed.
expired_or_canceled_cardlost_or_stolen_cardinsufficient_fundsinsufficient_available_balancedeclinedmerchant_requestpayment_disputedpayment_refund_failedpayment_refund_not_attemptedrefund_failed
idempotency_keystringPresent only on refunds created through POST /v1/credit-notes/{credit_note_id}/refunds or by issuing a credit note with refund: the Idempotency-Key of that call. Use it with GET /v1/credit-notes/{credit_note_id}/refunds?idempotency_key= to recover a refund whose create response was lost.
invoice_idstringID of the invoice whose credit note this refund paid out. Present only on refunds issued through a credit note.
line_item_allocationsarray of objectHow the refund applied to each order line item it covered, with quantity, tax, and adjustments.
merchant_idstringRequiredID of the merchant this resource belongs to.
metadatamap of stringStored caller-owned key-value data. See `MetadataInput` for key, value, and size rules.
orderobject or nullPresent only when `expand` includes `order`; `null` when expanded and there is no related order.
order_idstringID of the order the refund was issued against. Absent for a refund of a payment that has no order, and for a standalone gift card refund.
payment_intentobject or nullPresent only when `expand` includes `payment_intent`; `null` when expanded and there is no related payment intent.
payment_intent_idstringID of the payment the refund was issued against, when it targeted one payment. `payment_refunds` lists every payment it returned money through.
payment_refundsarray of objectThe part of the refund returned through each payment, with its own status. Absent when the refund was all gift card credit or store credit.
payment_review_idstringID of the payment review whose decline created this refund. Present only on refunds issued for a declined review.
reasonenum or nullRequiredWhy the refund was issued. It never changes how the money moves. The buyer's refund receipt shows it only for `requested_by_customer`, `duplicate`, `defective_product`, `wrong_item_shipped`, `never_received`, `not_as_described`, `arrived_too_late`, and `accidental_order`. `null` when no reason was recorded.
duplicatefraudulentrequested_by_customerdefective_productwrong_item_shippednever_receivednot_as_describedarrived_too_latecustomer_changed_mindbetter_price_foundaccidental_orderothernull
reason_messagestringNote explaining the refund, up to 1,024 characters.
refund_idstringRequiredUnique identifier for this refund, prefixed `ref_`.
refunded_tip_moneyobjectRequiredShare of `amount_money` that refunds tips.
return_idstringID of the return this refund paid out. Present only on refunds issued by a return.
return_resolution_idstringID of the return resolution that issued this refund. Present only on refunds issued by a return.
statusenumRequiredSummary of payment_refunds and tender_allocations. Only failed is final: succeeded and partially_succeeded can still change when a bank rejects a refund after accepting it. Follow refund.updated.
pendingsucceededpartially_succeededfailed
tax_breakdown_refundsarray of objectTax reversed on order-level charges and flat taxes, one entry per tax breakdown. Tax reversed on line items is in `line_item_allocations[].tax_breakdown_refunds`.
tender_allocationsarray of objectEvery tender the refund drew from, payment or gift card, with its amount, tip share, status, and destination.
unissued_gift_card_recoveriesarray of objectCash returned after an unissued gift card purchase refund failed. Return it through a new refund against payment_intent_id and order_line_item_id. It does not issue another card. Source remaining and pending amounts describe the entire original settlement allocation; repeated entries for that source are not additive.
updated_atstringRequiredRFC3339 timestamp.
versionintegerRequiredPersisted version of this resource's owned state. Expanded resources and external observations can change independently.
replacement_line_itemsarray of objectRequiredMerchandise the buyer receives instead, for an exchange or replacement.
bundle_idstringID of the bundle the replacement line is for.
descriptionstringDescription of the replacement item.
discount_moneyobjectRequiredDiscount on the replacement units.
namestringRequiredName of the replacement item.
product_idstringThe product this replacement variant belongs to. Present whenever variant_id is present; omitted for bundles and custom items.
quantityintegerRequiredWhole-number quantity; fractional quantities are not supported.
return_replacement_line_item_idstringRequiredUnique identifier for this return replacement line item, prefixed `retrepli_`.
return_resolution_idstringRequiredID of the resolution the line belongs to.
skustringSKU of the replacement item.
subtotal_moneyobjectRequiredSubtotal of the replacement units, before discount and tax.
tax_moneyobjectRequiredTax on the replacement units.
total_moneyobjectRequiredSubtotal minus discount, plus tax.
unit_price_moneyobjectRequiredPrice of one replacement unit.
variant_idstringID of the variant the replacement line is for.
replacement_orderobject or nullPresent only when `expand` includes `replacement_order`; `null` when expanded and there is no related order.
Not returned with a customer session
buyer_contactobjectBuyer contact recorded on the order, including guest contact when retained. Omitted when the order has no recorded contact.
closed_atstringWhen the order closed. Present exactly when status is closed. Set once at the transition and never changed.
closed_reasonenumWhy the order closed. Present exactly when status is closed. Set once at closure. Unrecognized reasons are returned as other; new values may be added.
paidclosed_by_merchantcheckout_expiredwritten_offsupersededreturn_resolution_canceledother
created_atstringWhen the order was created, in RFC3339 format.
customer_idstringCustomer associated with the order, when one is set.
deferred_promotionsarray of objectRequiredPromotions accepted at subscription signup. They attach when the subscription is provisioned and first discount its first charged cycle. They do not discount this order and are separate from discounts and order totals. Always present; empty when no promotions are deferred.
fulfillment_statusenumAggregate progress across the order's fulfillment quantities.
not_fulfilledpartially_fulfilledfulfilledcancelednot_applicableclosed
governing_delivery_selection_idstring or nullRequiredID of the delivery selection that governs this order. Null when no selection governs the order.
order_idstringRequiredStable identifier of the expanded order.
order_numberstringHuman-readable order number for receipts and merchant reference.
payment_intent_idsarray of stringPayment intents associated with the order.
payment_statusenumRequiredCollection progress. An invoice write-off also completes collection without receiving the written-off amount.
unpaidpartially_paidpaid
pricing_amountsobjectRequiredOrder totals before accounting for collected payments and refunds.
refund_statusenumRequiredRefund progress for collected money.
nonepartially_refundedrefunded
settlement_amountsobjectRequiredPayments, refunds, credits, and amounts still owed for the order.
statusenumRequiredWhether the order still accepts changes and new payments. Refunds, fulfillment, disputes, returns, and metadata or note edits continue on a closed order.
openclosed
updated_atstringWhen the order was last updated, in RFC3339 format.
replacement_order_idstringID of the replacement Order Flint created for an exchange or replacement. Absent until it exists.
Not returned with a customer session
replacement_total_moneyobjectRequiredTotal of the replacement items the buyer receives.
amountintegerRequiredAmount in the currency's minor unit, such as cents for USD.
currencystringRequiredISO 4217 currency code for this amount.
resolution_typeenumRequiredWhat the buyer gets for the approved quantity.
refundexchangereplacementstore_creditno_monetary_actioncorrection
return_idstringRequiredID of the Return the resolution belongs to.
return_policy_revision_idstringNot returned with a customer session
return_resolution_idstringRequiredUnique identifier for this return resolution, prefixed `retres_`.
returned_total_moneyobjectRequiredValue of the returned units this resolution covers.
amountintegerRequiredAmount in the currency's minor unit, such as cents for USD.
currencystringRequiredISO 4217 currency code for this amount.
statusenumRequiredfulfilled means the buyer has the value: every linked Refund succeeded, any balance was collected, and any replacement Order's fulfillment_status is fulfilled or not_applicable.
proposedpendingrequires_actionfulfilledfailedcanceled
supported_actionsarray of enumRequiredActions that can succeed now. Empty unless the parent Return is open, except checkout_session. A failed resolution lists retry while it has a failed effect and its failure code permits retry. It lists cancel when it never created a Refund, PaymentIntent, or Order.
cancelcheckout_sessionconfirmreleaseretry
updated_atstringRequiredRFC3339 timestamp.
versionintegerRequiredCurrent version of this resource's owned state. Send it as `expected_version` when changing the resource to reject a stale write.
{
"adjustments": [],
"buyer_payment_amount_money": {
"amount": 1500,
"currency": "USD"
},
"buyer_refund_amount_money": {
"amount": 0,
"currency": "USD"
},
"confirmed_at": "2026-09-09T00:00:00Z",
"confirmed_by": {
"actor_type": "merchant"
},
"created_at": "2026-09-08T00:00:00Z",
"created_by": {
"actor_type": "merchant"
},
"credit_adjustment_money": {
"amount": 0,
"currency": "USD"
},
"deduction_money": {
"amount": 0,
"currency": "USD"
},
"execution_blockers": [],
"fulfilled_at": "2026-09-09T00:00:00Z",
"line_items": [
{
"quantity": 1,
"release_timing": "after_receipt",
"return_line_item_id": "retli_01KEZF7C001NHF6JPD83VD0MRK",
"return_resolution_id": "retres_01KEZF7C00VBZRA9H0NN82A4S9",
"return_resolution_line_item_id": "retresli_01J00000000000000000000000",
"returned_total_money": {
"amount": 5000,
"currency": "USD"
}
}
],
"metadata": {},
"payment_intent_ids": [
"pi_01KEZF7C0012ZTCGDTXP9S02QD"
],
"pricing_basis": "original_price",
"refund_ids": [],
"replacement_line_items": [
{
"discount_money": {
"amount": 0,
"currency": "USD"
},
"name": "Linen shirt, large",
"quantity": 1,
"return_replacement_line_item_id": "retrepli_01J00000000000000000000000",
"return_resolution_id": "retres_01KEZF7C00VBZRA9H0NN82A4S9",
"subtotal_money": {
"amount": 6500,
"currency": "USD"
},
"tax_money": {
"amount": 0,
"currency": "USD"
},
"total_money": {
"amount": 6500,
"currency": "USD"
},
"unit_price_money": {
"amount": 6500,
"currency": "USD"
}
}
],
"replacement_order_id": "ord_01KEZF7C00NEFAAYQ7FWBTP8EQ",
"replacement_total_money": {
"amount": 6500,
"currency": "USD"
},
"resolution_type": "exchange",
"return_id": "ret_01KEZF7C00VDTZH2NK73DBK2HZ",
"return_resolution_id": "retres_01KEZF7C00VBZRA9H0NN82A4S9",
"returned_total_money": {
"amount": 5000,
"currency": "USD"
},
"status": "fulfilled",
"supported_actions": [],
"updated_at": "2026-09-09T00:00:00Z",
"version": 2
}List return resolutions#
/v1/return-resolutionsRequires scope commerce.returns.operations.write or commerce.returns.policies.write or commerce.returns.read or commerce.returns.reasons.write or commerce.returns.resolutions.write or commerce.returns.write
Rate limit: read
List resolutions. Filter by corrects_return_resolution_id to retrieve the correction history for a resolution that already settled. Default order: created_at descending, then return_resolution_id descending.
Query parameters
action_required_byarray of enumFilter by action required by. 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.
buyermerchantintegration
corrects_return_resolution_idstringFilter by corrects return resolution id.
created_afterstringInclusive lower bound on created_at.
created_beforestringExclusive upper bound on created_at.
external_reference_idstringExact-match filter on the caller-owned external reference ID.
page_sizeintegerMaximum number of results to return, from 1 to 100. Defaults to 20.
page_tokenstringOpaque next_page_token from the previous response. Omit on the first request. You may change `page_size` between pages. Reuse it with the same endpoint, filters, sort, and request context. Do not parse or construct tokens. An invalid, expired, or mismatched token returns a validation error.
querystringSearch by return resolution ID or external reference ID.
resolution_typearray of enumFilter by resolution 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.
refundexchangereplacementstore_creditno_monetary_actioncorrection
return_idstringFilter by return id.
return_line_item_idstringFilter by return line item id.
return_policy_revision_idstringFilter by return policy revision id.
statusarray of enumFilter by status. 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.
proposedpendingrequires_actionfulfilledfailedcanceled
updated_afterstringInclusive lower bound on updated_at.
updated_beforestringExclusive upper bound on updated_at.
expandarray of enumInclude related objects in the response. Supported expansions: replacement_order. Include the requested related resources using scoped batch reads for this page. Each relationship requires its existing target read scopes. Expansion changes the representation without changing pagination tokens. Limits: at most 10 unique expand paths per request.
replacement_order
Response · 200
Successful response.
dataarray of objectRequiredResource, collection, or operation result returned by this request.
action_reasonenumWhat the resolution waits for while its status is `requires_action`.
buyer_paymentbuyer_selectionmerchant_reviewmanual_releaselinked_effect_retryother
action_required_byenumWho has to act while the resolution's status is `requires_action`.
buyermerchant
adjustmentsarray of objectRequiredFees and credits applied to the resolution's amounts.
buyer_payment_amount_moneyobjectRequiredAmount the buyer owes when deduction_money and replacement_total_money exceed returned_total_money plus credit_adjustment_money. Zero when the buyer is owed a refund and for no_monetary_action.
buyer_refund_amount_moneyobjectRequiredValue returned to the buyer: returned_total_money plus credit_adjustment_money, minus deduction_money and replacement_total_money, when that balance is zero or more. For store_credit, the value issued on new gift cards. Zero for no_monetary_action.
canceled_atstringRFC3339 timestamp.
canceled_byobjectWho canceled the resolution. Merchant reads only.
Not returned with a customer session
cancellation_reasonenumWhy the resolution was canceled.
buyer_requestmerchant_requestduplicateexpiredcreated_in_errorother
cancellation_reason_messagestringDetail sent with the cancellation. Merchant reads only.
Not returned with a customer session
confirmed_atstringRFC3339 timestamp.
confirmed_byobjectWho confirmed the resolution.
Not returned with a customer session
corrects_return_resolution_idstringID of the settled resolution this correction adjusts. Present only when `resolution_type` is `correction`.
Not returned with a customer session
created_atstringRequiredRFC3339 timestamp.
created_byobjectRequiredWho created the resolution.
Not returned with a customer session
credit_adjustment_moneyobjectRequiredCredits added by the resolution's adjustments.
deduction_moneyobjectRequiredDeductions taken by the resolution's adjustments, such as a restocking fee.
execution_blockersarray of objectRequiredWhat a confirmed resolution is still waiting for. Empty when nothing is.
external_reference_idstringCaller-owned identifier for this resource in an external system.
Not returned with a customer session
failure_codeenumReason code for a failed Return resolution, when available. refund_line_value_unavailable means another refund already returned part of an order line, so retrying cannot succeed; cancel the resolution and resolve the line for fewer units or without a refund. replacement_fulfillment_canceled means the replacement Order's fulfillment was canceled, so it won't be sent. gift_card_refund_destination_required means the original gift card cannot accept the refund; retry with gift_card_refund_destination set to new_gift_card. store_credit_unavailable means the original payment cannot fund store credit; cancel the resolution and create a refund resolution.
gift_card_refund_destination_requiredstore_credit_unavailablerefund_creation_failedrefund_failedrefund_line_value_unavailablepayment_intent_creation_failedpayment_failedreplacement_order_creation_failedreplacement_fulfillment_canceledresolution_effect_failed
failure_messagestringExplanation of a failed Return resolution, when available.
fulfilled_atstringWhen the resolution became fulfilled.
gift_card_refund_destinationenumWhere the gift-card-paid portion is refunded. original credits the original gift card; new_gift_card issues new gift cards. Accepted for refund, exchange, and correction, except a correction of store_credit. Omit for store_credit, replacement, and no_monetary_action; sending it returns INVALID_REQUEST with a NOT_ALLOWED detail and conflicting_fields naming resolution_type and gift_card_refund_destination. Store credit and its corrections always issue new gift cards. PATCH can change it only while proposed. Retry persists the chosen destination before starting the new attempt.
originalnew_gift_card
line_itemsarray of objectRequiredReturn lines and quantities the resolution covers. Absent on a correction.
metadatamap of stringRequiredStored caller-owned key-value data. See `MetadataInput` for key, value, and size rules.
payment_intent_idsarray of stringRequiredNot returned with a customer session
payment_intentsarray of objectNot returned with a customer session
pricing_basisenumHow replacement lines are priced. Present on exchanges and replacements.
original_pricecurrent_pricemerchant_agreed_price
refund_idsarray of stringRequiredNot returned with a customer session
refundsarray of objectNot returned with a customer session
replacement_line_itemsarray of objectRequiredMerchandise the buyer receives instead, for an exchange or replacement.
replacement_orderobject or nullPresent only when `expand` includes `replacement_order`; `null` when expanded and there is no related order.
Not returned with a customer session
replacement_order_idstringID of the replacement Order Flint created for an exchange or replacement. Absent until it exists.
Not returned with a customer session
replacement_total_moneyobjectRequiredTotal of the replacement items the buyer receives.
resolution_typeenumRequiredWhat the buyer gets for the approved quantity.
refundexchangereplacementstore_creditno_monetary_actioncorrection
return_idstringRequiredID of the Return the resolution belongs to.
return_policy_revision_idstringNot returned with a customer session
return_resolution_idstringRequiredUnique identifier for this return resolution, prefixed `retres_`.
returned_total_moneyobjectRequiredValue of the returned units this resolution covers.
statusenumRequiredfulfilled means the buyer has the value: every linked Refund succeeded, any balance was collected, and any replacement Order's fulfillment_status is fulfilled or not_applicable.
proposedpendingrequires_actionfulfilledfailedcanceled
supported_actionsarray of enumRequiredActions that can succeed now. Empty unless the parent Return is open, except checkout_session. A failed resolution lists retry while it has a failed effect and its failure code permits retry. It lists cancel when it never created a Refund, PaymentIntent, or Order.
cancelcheckout_sessionconfirmreleaseretry
updated_atstringRequiredRFC3339 timestamp.
versionintegerRequiredCurrent version of this resource's owned state. Send it as `expected_version` when changing the resource to reject a stale write.
metaobjectAdditional information about this response.
api_versionstringAPI version used to produce this response.
idempotency_replayedbooleanWhether this response replays a stored result for the supplied Idempotency-Key.
trace_idstringTrace identifier to include when contacting Flint about this request.
warningsarray of objectConditions that need attention even though the request succeeded.
next_page_tokenstringOpaque token to send as `page_token` to retrieve the next page. Omitted when there is no next page.
request_idstringRequiredIdentifier of this API request, used to correlate logs and support requests.
curl https://api.withflintpay.com/v1/return-resolutions \
-H "Flint-Version: 2026-09-07" \
-H "Authorization: Bearer YOUR_API_KEY"Successful response.
{
"data": [
{
"adjustments": [],
"buyer_payment_amount_money": {
"amount": 1500,
"currency": "USD"
},
"buyer_refund_amount_money": {
"amount": 0,
"currency": "USD"
},
"confirmed_at": "2026-09-09T00:00:00Z",
"confirmed_by": {
"actor_type": "merchant"
},
"created_at": "2026-09-08T00:00:00Z",
"created_by": {
"actor_type": "merchant"
},
"credit_adjustment_money": {
"amount": 0,
"currency": "USD"
},
"deduction_money": {
"amount": 0,
"currency": "USD"
},
"execution_blockers": [],
"fulfilled_at": "2026-09-09T00:00:00Z",
"line_items": [
{
"quantity": 1,
"release_timing": "after_receipt",
"return_line_item_id": "retli_01KEZF7C001NHF6JPD83VD0MRK",
"return_resolution_id": "retres_01KEZF7C00VBZRA9H0NN82A4S9",
"return_resolution_line_item_id": "retresli_01J00000000000000000000000",
"returned_total_money": {
"amount": 5000,
"currency": "USD"
}
}
],
"metadata": {},
"payment_intent_ids": [
"pi_01KEZF7C0012ZTCGDTXP9S02QD"
],
"pricing_basis": "original_price",
"refund_ids": [],
"replacement_line_items": [
{
"discount_money": {
"amount": 0,
"currency": "USD"
},
"name": "Linen shirt, large",
"quantity": 1,
"return_replacement_line_item_id": "retrepli_01J00000000000000000000000",
"return_resolution_id": "retres_01KEZF7C00VBZRA9H0NN82A4S9",
"subtotal_money": {
"amount": 6500,
"currency": "USD"
},
"tax_money": {
"amount": 0,
"currency": "USD"
},
"total_money": {
"amount": 6500,
"currency": "USD"
},
"unit_price_money": {
"amount": 6500,
"currency": "USD"
}
}
],
"replacement_order_id": "ord_01KEZF7C00NEFAAYQ7FWBTP8EQ",
"replacement_total_money": {
"amount": 6500,
"currency": "USD"
},
"resolution_type": "exchange",
"return_id": "ret_01KEZF7C00VDTZH2NK73DBK2HZ",
"return_resolution_id": "retres_01KEZF7C00VBZRA9H0NN82A4S9",
"returned_total_money": {
"amount": 5000,
"currency": "USD"
},
"status": "fulfilled",
"supported_actions": [],
"updated_at": "2026-09-09T00:00:00Z",
"version": 2
}
],
"meta": {
"api_version": "2026-09-07"
},
"request_id": "req_01KWM6VJA2F3XPY7CB6E1HSNSJ"
}Get return resolution#
/v1/return-resolutions/{return_resolution_id}Requires scope commerce.returns.operations.write or commerce.returns.policies.write or commerce.returns.read or commerce.returns.reasons.write or commerce.returns.resolutions.write or commerce.returns.write
Rate limit: read
Retrieve one resolution with its amounts, adjustments, execution blockers, and linked refunds, payments, and replacement order. Supports expand for those links.
Path parameters
return_resolution_idstringRequiredFlint return resolution id.
Query parameters
expandarray of enumInclude related objects in the response. Supported expansions: payment_intents, refunds, replacement_order. Expanded relationships are returned only when explicitly requested and authorized. Limits: at most 10 unique expand paths per request. To-many expansions are capped at 20 related objects per path.
payment_intentsrefundsreplacement_order
Response · 200
Successful response.
dataobjectRequiredResource, collection, or operation result returned by this request.
action_reasonenumWhat the resolution waits for while its status is `requires_action`.
buyer_paymentbuyer_selectionmerchant_reviewmanual_releaselinked_effect_retryother
action_required_byenumWho has to act while the resolution's status is `requires_action`.
buyermerchant
adjustmentsarray of objectRequiredFees and credits applied to the resolution's amounts.
buyer_payment_amount_moneyobjectRequiredAmount the buyer owes when deduction_money and replacement_total_money exceed returned_total_money plus credit_adjustment_money. Zero when the buyer is owed a refund and for no_monetary_action.
buyer_refund_amount_moneyobjectRequiredValue returned to the buyer: returned_total_money plus credit_adjustment_money, minus deduction_money and replacement_total_money, when that balance is zero or more. For store_credit, the value issued on new gift cards. Zero for no_monetary_action.
canceled_atstringRFC3339 timestamp.
canceled_byobjectWho canceled the resolution. Merchant reads only.
Not returned with a customer session
cancellation_reasonenumWhy the resolution was canceled.
buyer_requestmerchant_requestduplicateexpiredcreated_in_errorother
cancellation_reason_messagestringDetail sent with the cancellation. Merchant reads only.
Not returned with a customer session
confirmed_atstringRFC3339 timestamp.
confirmed_byobjectWho confirmed the resolution.
Not returned with a customer session
corrects_return_resolution_idstringID of the settled resolution this correction adjusts. Present only when `resolution_type` is `correction`.
Not returned with a customer session
created_atstringRequiredRFC3339 timestamp.
created_byobjectRequiredWho created the resolution.
Not returned with a customer session
credit_adjustment_moneyobjectRequiredCredits added by the resolution's adjustments.
deduction_moneyobjectRequiredDeductions taken by the resolution's adjustments, such as a restocking fee.
execution_blockersarray of objectRequiredWhat a confirmed resolution is still waiting for. Empty when nothing is.
external_reference_idstringCaller-owned identifier for this resource in an external system.
Not returned with a customer session
failure_codeenumReason code for a failed Return resolution, when available. refund_line_value_unavailable means another refund already returned part of an order line, so retrying cannot succeed; cancel the resolution and resolve the line for fewer units or without a refund. replacement_fulfillment_canceled means the replacement Order's fulfillment was canceled, so it won't be sent. gift_card_refund_destination_required means the original gift card cannot accept the refund; retry with gift_card_refund_destination set to new_gift_card. store_credit_unavailable means the original payment cannot fund store credit; cancel the resolution and create a refund resolution.
gift_card_refund_destination_requiredstore_credit_unavailablerefund_creation_failedrefund_failedrefund_line_value_unavailablepayment_intent_creation_failedpayment_failedreplacement_order_creation_failedreplacement_fulfillment_canceledresolution_effect_failed
failure_messagestringExplanation of a failed Return resolution, when available.
fulfilled_atstringWhen the resolution became fulfilled.
gift_card_refund_destinationenumWhere the gift-card-paid portion is refunded. original credits the original gift card; new_gift_card issues new gift cards. Accepted for refund, exchange, and correction, except a correction of store_credit. Omit for store_credit, replacement, and no_monetary_action; sending it returns INVALID_REQUEST with a NOT_ALLOWED detail and conflicting_fields naming resolution_type and gift_card_refund_destination. Store credit and its corrections always issue new gift cards. PATCH can change it only while proposed. Retry persists the chosen destination before starting the new attempt.
originalnew_gift_card
line_itemsarray of objectRequiredReturn lines and quantities the resolution covers. Absent on a correction.
metadatamap of stringRequiredStored caller-owned key-value data. See `MetadataInput` for key, value, and size rules.
payment_intent_idsarray of stringRequiredNot returned with a customer session
payment_intentsarray of objectNot returned with a customer session
pricing_basisenumHow replacement lines are priced. Present on exchanges and replacements.
original_pricecurrent_pricemerchant_agreed_price
refund_idsarray of stringRequiredNot returned with a customer session
refundsarray of objectNot returned with a customer session
replacement_line_itemsarray of objectRequiredMerchandise the buyer receives instead, for an exchange or replacement.
replacement_orderobject or nullPresent only when `expand` includes `replacement_order`; `null` when expanded and there is no related order.
Not returned with a customer session
replacement_order_idstringID of the replacement Order Flint created for an exchange or replacement. Absent until it exists.
Not returned with a customer session
replacement_total_moneyobjectRequiredTotal of the replacement items the buyer receives.
resolution_typeenumRequiredWhat the buyer gets for the approved quantity.
refundexchangereplacementstore_creditno_monetary_actioncorrection
return_idstringRequiredID of the Return the resolution belongs to.
return_policy_revision_idstringNot returned with a customer session
return_resolution_idstringRequiredUnique identifier for this return resolution, prefixed `retres_`.
returned_total_moneyobjectRequiredValue of the returned units this resolution covers.
statusenumRequiredfulfilled means the buyer has the value: every linked Refund succeeded, any balance was collected, and any replacement Order's fulfillment_status is fulfilled or not_applicable.
proposedpendingrequires_actionfulfilledfailedcanceled
supported_actionsarray of enumRequiredActions that can succeed now. Empty unless the parent Return is open, except checkout_session. A failed resolution lists retry while it has a failed effect and its failure code permits retry. It lists cancel when it never created a Refund, PaymentIntent, or Order.
cancelcheckout_sessionconfirmreleaseretry
updated_atstringRequiredRFC3339 timestamp.
versionintegerRequiredCurrent version of this resource's owned state. Send it as `expected_version` when changing the resource to reject a stale write.
metaobjectAdditional information about this response.
api_versionstringAPI version used to produce this response.
idempotency_replayedbooleanWhether this response replays a stored result for the supplied Idempotency-Key.
trace_idstringTrace identifier to include when contacting Flint about this request.
warningsarray of objectConditions that need attention even though the request succeeded.
request_idstringRequiredIdentifier of this API request, used to correlate logs and support requests.
curl https://api.withflintpay.com/v1/return-resolutions/retres_01KEZF7C00C7RZJN31W9SGMEQ3 \
-H "Flint-Version: 2026-09-07" \
-H "Authorization: Bearer YOUR_API_KEY"Successful response.
{
"data": {
"adjustments": [],
"buyer_payment_amount_money": {
"amount": 1500,
"currency": "USD"
},
"buyer_refund_amount_money": {
"amount": 0,
"currency": "USD"
},
"confirmed_at": "2026-09-09T00:00:00Z",
"confirmed_by": {
"actor_type": "merchant"
},
"created_at": "2026-09-08T00:00:00Z",
"created_by": {
"actor_type": "merchant"
},
"credit_adjustment_money": {
"amount": 0,
"currency": "USD"
},
"deduction_money": {
"amount": 0,
"currency": "USD"
},
"execution_blockers": [],
"fulfilled_at": "2026-09-09T00:00:00Z",
"line_items": [
{
"quantity": 1,
"release_timing": "after_receipt",
"return_line_item_id": "retli_01KEZF7C001NHF6JPD83VD0MRK",
"return_resolution_id": "retres_01KEZF7C00VBZRA9H0NN82A4S9",
"return_resolution_line_item_id": "retresli_01J00000000000000000000000",
"returned_total_money": {
"amount": 5000,
"currency": "USD"
}
}
],
"metadata": {},
"payment_intent_ids": [
"pi_01KEZF7C0012ZTCGDTXP9S02QD"
],
"pricing_basis": "original_price",
"refund_ids": [],
"replacement_line_items": [
{
"discount_money": {
"amount": 0,
"currency": "USD"
},
"name": "Linen shirt, large",
"quantity": 1,
"return_replacement_line_item_id": "retrepli_01J00000000000000000000000",
"return_resolution_id": "retres_01KEZF7C00VBZRA9H0NN82A4S9",
"subtotal_money": {
"amount": 6500,
"currency": "USD"
},
"tax_money": {
"amount": 0,
"currency": "USD"
},
"total_money": {
"amount": 6500,
"currency": "USD"
},
"unit_price_money": {
"amount": 6500,
"currency": "USD"
}
}
],
"replacement_order_id": "ord_01KEZF7C00NEFAAYQ7FWBTP8EQ",
"replacement_total_money": {
"amount": 6500,
"currency": "USD"
},
"resolution_type": "exchange",
"return_id": "ret_01KEZF7C00VDTZH2NK73DBK2HZ",
"return_resolution_id": "retres_01KEZF7C00VBZRA9H0NN82A4S9",
"returned_total_money": {
"amount": 5000,
"currency": "USD"
},
"status": "fulfilled",
"supported_actions": [],
"updated_at": "2026-09-09T00:00:00Z",
"version": 2
},
"meta": {
"api_version": "2026-09-07"
},
"request_id": "req_01KWM6VJA2F3XPY7CB6E1HSNSJ"
}Update return resolution#
/v1/return-resolutions/{return_resolution_id}IdempotentRequires scope commerce.returns.resolutions.write
Rate limit: write
Update a proposed resolution before confirmation. A present line_items, replacement_line_items, or adjustments array replaces that collection and requires expected_version.
Path parameters
return_resolution_idstringRequiredFlint return resolution id.
Request body
adjustmentsarray of objectRequires expected_version.
adjustment_typeenumRequiredWhat the fee or credit is for.
return_shipping_feerestocking_feeother_feegoodwill_creditprice_correctionother
applied_amount_moneyobjectRequiredAmount that counts toward the resolution. It can't exceed `assessed_amount_money`, and is zero when the adjustment is waived.
assessed_amount_moneyobjectRequiredAmount the fee or credit comes to before any waiver. Same currency as `applied_amount_money`.
reasonenumRequiredWhy the adjustment was made.
return_policyinspection_resultreturn_shipping_costcustomer_servicemanual_correctionother
reason_messagestringOptional detail about `reason`, kept with the record.
return_line_item_idstringID of the Return line a deduction applies to. Absent when it applies to the resolution as a whole.
return_resolution_adjustment_idstringKeep this member ID when updating an existing adjustment. Omit it to create a new adjustment.
statusenumWhether the adjustment counts toward the buyer's value. A waived adjustment applies zero.
appliedwaived
value_effectenumRequiredWhether the adjustment reduces or increases what the buyer receives.
deductioncredit
waiver_reasonenumWhy the adjustment was waived.
policy_overridemerchant_reviewcustomer_serviceother
waiver_reason_messagestringDetail about `waiver_reason`.
expected_versionintegerRequired when any of these fields is present: line_items, replacement_line_items, adjustments.
external_reference_idstring or nullCaller-owned identifier for this resource in an external system. Send null to clear it.
gift_card_refund_destinationenumWhere the gift-card-paid portion is refunded. original credits the original gift card; new_gift_card issues new gift cards. Accepted for refund, exchange, and correction, except a correction of store_credit. Omit for store_credit, replacement, and no_monetary_action; sending it returns INVALID_REQUEST with a NOT_ALLOWED detail and conflicting_fields naming resolution_type and gift_card_refund_destination. Store credit and its corrections always issue new gift cards. PATCH can change it only while proposed. Retry persists the chosen destination before starting the new attempt.
originalnew_gift_card
line_itemsarray of objectRequires expected_version.
quantityintegerRequiredWhole-number quantity; fractional quantities are not supported.
return_line_item_idstringRequiredID of the Return line the resolution covers.
return_resolution_line_item_idstringID of an existing resolution line to keep. Leave out to add a new line.
metadatamap of string or nullCaller-owned metadata. Omit this field to leave metadata unchanged. Send an object to merge by key, set a key to null to remove it, or set metadata to null to clear all caller-owned metadata. An empty object makes no change. Values can't be empty strings. Keys starting with flint_ are reserved for Flint, are not returned, and cannot be written through the public API.
pricing_basisenumHow replacement lines are priced. Send with `exchange` or `replacement`.
original_pricecurrent_pricemerchant_agreed_price
replacement_line_itemsarray of one ofRequires expected_version.
Send exactly one of these
The `variant` variant of `UpdateReturnReplacementLineItemInput`.
descriptionstringDescription of the replacement item.
quantityintegerRequiredWhole-number quantity; fractional quantities are not supported.
return_replacement_line_item_idstringID of an existing replacement line to keep. Leave out to add a new line.
skustringSKU of the replacement item.
typeenumRequiredThe source of the replacement merchandise: variant, bundle, or custom.
variant
unit_price_moneyobjectPrice of one replacement unit. Required when `type` is `custom` or `pricing_basis` is `merchant_agreed_price`.
variant_idstringRequiredID of the variant to send. Used when `type` is `variant`.
curl -X PATCH https://api.withflintpay.com/v1/return-resolutions/retres_01KEZF7C00C7RZJN31W9SGMEQ3 \
-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,
"line_items": [
{
"quantity": 1,
"return_line_item_id": "retli_01KEZF7C001NHF6JPD83VD0MRK"
}
]
}'Cancel return resolution#
/v1/return-resolutions/{return_resolution_id}/cancelIdempotentRequires scope commerce.returns.resolutions.write
Rate limit: write
Cancel a resolution and release the line value it reserved. A failed resolution can be canceled only when it never created a Refund, PaymentIntent, or Order, or when it is an unpaid exchange. Effects that already succeeded are undone with a compensating correction instead.
Path parameters
return_resolution_idstringRequiredFlint return resolution id.
Request body
expected_versionintegerVersion last read from the resource returned in `data` (the primary resource for a result object). The write fails with `VERSION_CONFLICT` if it has changed. Requiredness depends on the operation and fields being changed.
reasonenumRequiredWhy it is being canceled.
buyer_requestmerchant_requestduplicateexpiredcreated_in_errorother
reason_messagestringOptional detail about `reason`, kept with the record.
curl -X POST https://api.withflintpay.com/v1/return-resolutions/retres_01KEZF7C00C7RZJN31W9SGMEQ3/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,
"reason": "buyer_request"
}'Get or create return resolution checkout session#
/v1/return-resolutions/{return_resolution_id}/checkout-sessionsIdempotentRequires scope commerce.returns.resolutions.write
Rate limit: write
Create or reuse a hosted or embedded checkout session for the buyer's balance on a replacement order linked to this return resolution. The response is `200` when it reuses an existing session and `201` when it creates one. Omit surface to use hosted. The same surface reuses the open session; changing surface replaces an idle session and is refused while a payment is in progress. Use redirects to set where the buyer goes after paying or canceling. The return_url field is an alias for redirects.success_url on hosted checkout or payment_return_url on embedded checkout and must be an address of the merchant's customer account. A reused session takes a new success destination only until a payment starts, then keeps its existing destination.
Path parameters
return_resolution_idstringRequiredFlint return resolution id.
Request body
page_originstringOrigin of the page where you render this embedded checkout, such as https://shop.example.com. Only this origin can show the checkout's gift card challenge and receive its result. It does not let the browser call the Flint API. Accepted only when surface is embedded. Use HTTPS and a lowercase DNS hostname. Do not include a path, query, fragment, or default port. In test mode, localhost, names ending in .localhost, and 127.0.0.1 also work over HTTP or HTTPS.
payment_return_urlstringEmbedded sessions only. Absolute HTTPS URL on your site where Flint sends the buyer after a redirect payment such as Affirm, whatever the outcome; read the session there to show the result. Required when the session offers affirm. It can't contain credentials, a query string, or a fragment. Test mode also accepts http loopback URLs. Up to 2,048 characters.
redirectsobjectWhere hosted checkout sends the buyer. Not allowed when surface is embedded; use payment_return_url.
cancel_urlstringWhere the buyer goes when they leave checkout without paying. The session stays open until it expires. Absolute HTTPS URL; test mode also accepts HTTP loopback URLs. Up to 2,048 characters.
expired_urlstringWhere Flint sends a buyer who opens the session after it expires. Without it, the buyer sees Flint's expired-checkout page. Absolute HTTPS URL; test mode also accepts HTTP loopback URLs. Up to 2,048 characters.
success_urlstringWhere the buyer goes after paying. Flint adds checkout_session_id and order_id query parameters, replacing any with those names. The redirect doesn't prove payment: confirm with the order.paid webhook or by reading the session. Absolute HTTPS URL; test mode also accepts HTTP loopback URLs. Up to 2,048 characters.
return_urlstringWhere the checkout sends the buyer after paying, such as the Return's page in the customer account. Limited to 2048 characters (Unicode code points) before trimming surrounding whitespace. It must be an HTTPS address of the merchant's customer account: /{merchant_id} on Flint's account host, the merchant's active custom account domain, or the host of customer_account.merchant_account_url when the merchant hosts the account. In test mode, any URL on localhost or a loopback IP address (such as 127.0.0.1 or [::1]) is also accepted, over HTTP or HTTPS and on any port. Anything else returns 400 INVALID_REQUEST with an INVALID_VALUE detail on return_url. An alias for redirects.success_url on hosted checkout or payment_return_url on embedded checkout; keep them consistent when sending both.
surfaceenumDefaults to hosted. The same surface reuses the open checkout. A different surface replaces it only while no payment is in progress; otherwise the request returns 409 ACTION_NOT_ALLOWED with reason in_progress.
hostedembedded
Response · 201
Checkout session created.
dataobjectRequiredResource, collection, or operation result returned by this request.
checkout_auth_tokenstringCheckout credential. Send it as Authorization: Bearer <checkout_auth_token>. Present on checkout launch and customer binding confirmation; omitted when a saved-card confirmation keeps the current credential.
active_payment_attemptobjectAn attempt to pay an order.
buyer_contactobjectContact the buyer entered in checkout before paying, saved with the session's checkout credential. Separate from merchant-supplied prefill and customer_prefill from the customer record. Omitted until the buyer saves or clears a field. When a checkout session payment omits buyer_contact.email or buyer_contact.phone, Flint uses these values. Flint clears the contact 30 days after the session ends, and when a customer linked to the session is deleted.
buyer_fieldsobjectWhat checkout asks the buyer for. Each field you leave out uses your checkout settings.
can_save_payment_methodbooleanWhether checkout offers the buyer the option to save the card they type for faster checkout at this merchant. When true and save_payment_method_requires_verification is false, PayOrder accepts save_payment_method: true for one newly collected card. False when the merchant turned checkout.saved_payment_details off, customer accounts are merchant hosted, card is not an available payment option, the checkout collects an invoice, a subscription, or a return, or the checkout acts for no customer and Flint cannot email the buyer a verification code. Returned only to the checkout credential; never in webhook payloads.
Not returned with a bearer token
can_save_payment_method_with_phonebooleanWhether the buyer can save the card they type by giving a US or Canadian mobile phone number with the payment, in save_payment_method_phone on POST /v1/orders/{order_id}/pay, and confirming it with a texted code after paying. True while Flint can send texts and either save_payment_method_requires_verification is true, so the number replaces confirming an email before paying, or the checkout acts for the customer whose email the buyer confirmed with this credential, so the number joins that customer's saved details once the buyer confirms it. Returned only to the checkout credential; never in webhook payloads.
Not returned with a bearer token
checkout_session_idstringRequiredUnique identifier for this checkout session, prefixed `cs_`.
closed_reason_messagestringThe note supplied when the checkout session was closed.
Not returned with a checkout credential or a customer session
created_atstringRequiredRFC3339 timestamp.
custom_textobjectThe custom text this session shows in checkout.
customerobject or nullPresent only when `expand` includes `customer`; `null` when expanded and there is no related customer.
Not returned with a checkout credential or a customer session
customer_idstringThe customer of the session's order. Omitted when the order has none. A checkout credential issued for this session acts for this customer. Add expand=customer to include the customer.
customer_prefillobjectContact and default addresses of the customer the checkout acts for, with the recipient name on its default shipping address: the customer the merchant created the session for, or the customer whose email the buyer confirmed in it. Present on GET and PATCH responses while the session is open and acts for a customer. Separate from merchant-supplied prefill and buyer_contact saved by the buyer. Returned only to the checkout credential; never in webhook payloads.
Not returned with a bearer token
deliveryobjectCurrent delivery choices for Flint-owned pricing. External pricing reports requires_explicit_quote; reading this field does not request a delivery quote. Omitted when the session is not open, has no order, or Flint cannot read its delivery.
delivery_method_idsarray of stringRequiredImmutable delivery method assignment captured when the checkout was created.
delivery_pinned_dependenciesarray of objectImmutable configuration lineage used to evaluate delivery quotes.
Not returned with a checkout credential or a customer session
delivery_selection_requiredbooleanRequiredWhether the order has at least one remaining quote-resolved fulfillment choice that must be selected before payment.
expires_atstringRFC3339 timestamp.
expires_in_secondsintegerThe lifetime the session got. expires_at is its deadline. Omitted for invoice sessions, which take their deadline from the invoice.
external_reference_idstringCaller-owned identifier for this resource in an external system.
Not returned with a checkout credential or a customer session
gift_card_challengeobjectWhere the buyer completes a gift card challenge for this checkout. Returned on single-session reads, session create and update responses, checkout launch results, and customer verification confirmation results while the session is open and can show the challenge. Omitted from lists, webhooks, expanded resources, and delivery selection results.
invoiceobject or nullPresent only when `expand` includes `invoice`; `null` when expanded and there is no related invoice.
Not returned with a checkout credential or a customer session
invoice_idstringID of the invoice a session of type `invoice` collects payment for. Absent for other types.
is_in_recoverybooleanRequiredWhether this terminal session credential is temporarily restricted to recovering its owning payment attempt.
legalobjectThe terms and policy links this session shows the buyer, and whether the buyer must accept the terms.
merchant_iconobjectThe merchant's square icon, shown in browser tabs and compact headers. Returned by `GET /v1/checkout-sessions/{checkout_session_id}` when the merchant has one; other responses and webhooks omit it.
merchant_idstringRequiredID of the merchant this resource belongs to.
merchant_logoobjectThe merchant's logo. Returned by `GET /v1/checkout-sessions/{checkout_session_id}` when the merchant has one; other responses and webhooks omit it.
merchant_namestringThe merchant's business name, which hosted checkout shows when `theme.title` is unset. Reads `Merchant` when the merchant has not set a business name. Returned by `GET /v1/checkout-sessions/{checkout_session_id}`; other responses and webhooks omit it.
merchant_supportobjectHow the buyer can reach the merchant for help: the support email, phone, and URL the merchant set. Present on GET and PATCH responses when the merchant set at least one of them. Show it where your checkout tells the buyer to contact the merchant, such as an expired or closed checkout, or your receipt. Returned only to the checkout credential; never in webhook payloads.
Not returned with a bearer token
metadatamap of stringStored caller-owned key-value data. See `MetadataInput` for key, value, and size rules.
Not returned with a checkout credential or a customer session
orderobject or nullPresent only when `expand` includes `order`; `null` when expanded and there is no related order.
Not returned with a checkout credential or a customer session
order_idstringID of the order the session collects payment for, fixed at creation. Absent when the session has no order.
page_originstringOrigin of the page that renders this embedded checkout. Omitted when not set.
payment_collectionobjectGuidance for collecting a payment source. Checkout-credential reads include it only while the session is open. Returned only to the checkout credential; never in webhook payloads.
Not returned with a bearer token
payment_intent_idsarray of stringIDs of the payment intents for the session's order. Absent when the order has none.
payment_intentsarray of objectPresent only when `expand` includes `payment_intents`: summaries of the payment intents in `payment_intent_ids`.
Not returned with a checkout credential or a customer session
payment_linkobject or nullPresent only when `expand` includes `payment_link`; `null` when expanded and there is no related payment link.
Not returned with a checkout credential or a customer session
payment_link_idstringID of the payment link the session was started from. Absent when it was not started from a payment link.
payment_link_imageobjectThe current image of the payment link that opened this session. Returned by `GET /v1/checkout-sessions/{checkout_session_id}` when that link has an image; other responses and webhooks omit it.
payment_method_saveobjectThe card the buyer saved with this checkout's payment by giving a mobile phone number, and whether they confirmed it. Present on GET and PATCH responses after a payment that paid the order in full, or that was approved for the merchant to capture later, and saved a card this way. A checkout whose payment is approved stays open until the capture. Returned only to the checkout credential; never in webhook payloads.
Not returned with a bearer token
payment_return_urlstringEmbedded sessions only. Absolute HTTPS URL on your site where Flint sends the buyer after a redirect payment such as Affirm, whatever the outcome; read the session there to show the result. Required when the session offers affirm. It can't contain credentials, a query string, or a fragment. Test mode also accepts http loopback URLs. Up to 2,048 characters.
paymentsobjectConfigured payment options for merchant credentials; currently available payment options for the checkout credential.
prefillobjectContact details and addresses to fill in for the buyer, who can change them. For a customer with saved addresses, Flint fills in any address you leave out, and reads include it. With quick_pay or subscription_plan and automatic tax on, a prefilled address sets the order's tax location. Not changed by what the buyer types; for that, read buyer_contact. customer_prefill is what the checkout credential reads from the customer record.
problemsarray of objectRequiredNamed conditions that affect checkout completion. Follow each problem's remediation action instead of reconstructing delivery lifecycle rules in the client. payment_in_progress means another payment for the order must finish before this checkout can complete. When Flint cannot read the checkout's delivery, the read still succeeds and reports delivery_unreadable; its remediation says whether reading the session again can succeed, and its next action's reason_code names the error.
promotion_configobjectWhether automatic promotions apply to this session and whether the buyer can enter promotion codes.
recovery_expires_atstring or nullWhen the restricted payment-attempt recovery window ends. `null` when the session has no recovery window.
recovery_payment_attempt_idstringPayment attempt that this checkout credential may recover while is_in_recovery is true.
redirectsobjectWhere hosted checkout sends the buyer. Not allowed when surface is embedded; use payment_return_url.
save_payment_method_requires_verificationbooleanWhether the buyer must confirm their email with a code before the checkout can save their card or use their saved cards. True when can_save_payment_method is true and the checkout acts for no customer for this credential: the merchant created it without one, and either the buyer has not confirmed an email with this credential, or the customer whose email they confirmed has since changed that email or been deleted. A credential other than the one a confirmation returned, such as the hosted checkout link opened on another device, reads true. Send the code with POST /v1/checkout-sessions/{checkout_session_id}/customer-verifications. False while the checkout acts for a customer, and whenever can_save_payment_method is false. Returned only to the checkout credential; never in webhook payloads.
Not returned with a bearer token
save_payment_method_typesarray of enumWhat save_payment_method keeps, present when can_save_payment_method is true: card, a card the buyer types into checkout. Show the save option with that payment method only. A pay request that sends save_payment_method: true with Apple Pay, Google Pay, a bank account, or Affirm, through a confirmation token created with setup_future_usage none, still pays, and its payment attempt's payment_method_save reports not_saved. The values can grow. Returned only to the checkout credential; never in webhook payloads.
Not returned with a bearer token
card
setup_collectionobjectGuidance for collecting a payment method to save. Checkout-credential reads include it only while the session is open. Returned only to the checkout credential; never in webhook payloads.
Not returned with a bearer token
show_flint_markbooleanWhether Flint's hosted pages show the Powered by Flint mark for this merchant. `false` when the merchant's agreement with Flint removes it. Returned by `GET /v1/checkout-sessions/{checkout_session_id}`; other responses and webhooks omit it.
statusenumRequiredWhere the session is in its lifecycle. Only an `open` session accepts payment. `terminal_reason` says why a session that is not open ended.
openpaidpartially_paidexpiredclosedinvalidated
subscription_plan_idstringID of the subscription plan a session of type `subscription_plan` signs the buyer up for. Absent for other types.
subscription_termsobjectRenewal terms a subscription checkout commits the buyer to. Frozen when the session's order was created, so later plan changes do not alter them. Absent when the checkout starts no subscription.
superseding_checkout_session_idstringID of the session that replaced this one. Present when `terminal_reason` is `superseded`.
supported_actionsarray of enumRequiredLifecycle actions Flint accepts now, computed from stored checkout state without checking the caller's permissions. Contains close while open; empty after payment, closure, or expiry.
Not returned with a checkout credential or a customer session
close
surfaceenumRequiredHow the session is presented to the buyer. A hosted session has a `url` on Flint's checkout page; an embedded one is rendered on your own page.
hostedembedded
taxobjectThe session's tax settings. Omitted when the session sets none.
terminal_reasonenumWhy the session ended. The checkout credential can still read its own closed or expired session; every other call is refused because the session is not open. order_paid_elsewhere applies only to invalidated sessions when payment succeeds or partially succeeds outside the session. order_mutated applies when an edit closes or completes its order, or ends an invoice, return-resolution, or subscription-plan session. Other merchant edits keep hosted and embedded sessions open. A session already past expires_at ends with expired before the edit is applied.
payment_succeededpayment_partially_succeededexpiredclosed_by_merchantorder_mutatedsupersededorder_paid_elsewhereinvoice_paid_elsewhereinvoice_voidedinvoice_uncollectibleinvoice_balance_changed
themeobjectThe theme checkout renders with: your branding settings, with the session's `title`, `primary_color`, and `accent_color` over them. A session sets only those three; the other fields come from branding settings. Omitted when neither sets a value.
tipobjectThe tip options this session offers the buyer.
typeenumRequiredWhat the session collects payment for, fixed at creation.
orderquick_paysubscription_planinvoicepayment_link
updated_atstringRequiredRFC3339 timestamp.
urlstringHosted checkout URL that carries a one-time launch credential. Send the buyer here to pay. Present only for hosted sessions read with a merchant credential that can manage checkout sessions. Launch results include it for hosted sessions: create, payment-link resolve, and invoice and return-resolution checkout. Omitted for embedded sessions.
Not returned with a checkout credential
versionintegerRequiredPersisted version of this resource's owned state. Expanded resources and external observations can change independently.
metaobjectAdditional information about this response.
api_versionstringAPI version used to produce this response.
idempotency_replayedbooleanWhether this response replays a stored result for the supplied Idempotency-Key.
trace_idstringTrace identifier to include when contacting Flint about this request.
warningsarray of objectConditions that need attention even though the request succeeded.
request_idstringRequiredIdentifier of this API request, used to correlate logs and support requests.
Response · 200
The existing checkout session matched this return resolution. Nothing was created.
Same attributes as 201.
curl -X POST https://api.withflintpay.com/v1/return-resolutions/retres_01KEZF7C00C7RZJN31W9SGMEQ3/checkout-sessions \
-H "Flint-Version: 2026-09-07" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: a-unique-key" \
-d '{
"surface": "hosted"
}'Confirm return resolution#
/v1/return-resolutions/{return_resolution_id}/confirmIdempotentRequires scope commerce.returns.resolutions.write
Rate limit: write
Confirm a proposed resolution and freeze its economic facts. Execution can remain pending behind line-qualified execution blockers.
Path parameters
return_resolution_idstringRequiredFlint return resolution id.
Request body
expected_versionintegerVersion last read from the resource returned in `data` (the primary resource for a result object). The write fails with `VERSION_CONFLICT` if it has changed. Requiredness depends on the operation and fields being changed.
curl -X POST https://api.withflintpay.com/v1/return-resolutions/retres_01KEZF7C00C7RZJN31W9SGMEQ3/confirm \
-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
}'Release return resolution#
/v1/return-resolutions/{return_resolution_id}/releaseIdempotentRequires scope commerce.returns.resolutions.write
Rate limit: write
Release a confirmed resolution that is waiting on a manual release. Available only while action_reason is manual_release.
Path parameters
return_resolution_idstringRequiredFlint return resolution id.
Request body
expected_versionintegerVersion last read from the resource returned in `data` (the primary resource for a result object). The write fails with `VERSION_CONFLICT` if it has changed. Requiredness depends on the operation and fields being changed.
reasonenumRequiredWhy the resolution is being released.
merchant_approvedexception_resolvedother
reason_messagestringOptional detail about `reason`, kept with the record.
curl -X POST https://api.withflintpay.com/v1/return-resolutions/retres_01KEZF7C00C7RZJN31W9SGMEQ3/release \
-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": "merchant_approved"
}'Retry return resolution#
/v1/return-resolutions/{return_resolution_id}/retryIdempotentRequires scope commerce.returns.resolutions.write
Rate limit: write
Retry a failed resolution. For gift_card_refund_destination_required, send gift_card_refund_destination: new_gift_card to persist the destination before starting the new attempt. The override is accepted for refund, exchange, and corrections of resolutions other than store_credit. A new attempt starts, historical payment and refund IDs stay on the resolution, and a late event from an earlier attempt cannot settle the new attempt. Fails with ACTION_NOT_ALLOWED, with the line's current_status, when a Return line the resolution covers is no longer approved, such as after it was canceled, and with `LIMIT_EXCEEDED` when an approved line no longer has the quantity the resolution covers. Retry is available only when failure_code allows it, and supported_actions includes retry in that case. A failure that retry cannot fix fails with `ACTION_NOT_ALLOWED`; cancel the resolution instead.
Path parameters
return_resolution_idstringRequiredFlint return resolution id.
Request body
expected_versionintegerVersion last read from the resource returned in `data` (the primary resource for a result object). The write fails with `VERSION_CONFLICT` if it has changed. Requiredness depends on the operation and fields being changed.
gift_card_refund_destinationenumWhere the gift-card-paid portion is refunded. original credits the original gift card; new_gift_card issues new gift cards. Accepted for refund, exchange, and correction, except a correction of store_credit. Omit for store_credit, replacement, and no_monetary_action; sending it returns INVALID_REQUEST with a NOT_ALLOWED detail and conflicting_fields naming resolution_type and gift_card_refund_destination. Store credit and its corrections always issue new gift cards. PATCH can change it only while proposed. Retry persists the chosen destination before starting the new attempt.
originalnew_gift_card
reasonenumRequiredWhy the resolution is being run again.
dependency_recoveredpayment_method_updatedoperator_retryother
reason_messagestringOptional detail about `reason`, kept with the record.
curl -X POST https://api.withflintpay.com/v1/return-resolutions/retres_01KEZF7C00C7RZJN31W9SGMEQ3/retry \
-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,
"reason": "dependency_recovered"
}'Create return resolution#
/v1/returns/{return_id}/resolutionsIdempotentRequires scope commerce.returns.resolutions.write
Rate limit: write
Propose a buyer-value outcome for approved quantity. Creating a resolution reserves line value. Confirmation is what freezes it and starts its effects. Read resolutions with `GET /v1/return-resolutions?return_id=` or expand `return_resolutions` on `GET /v1/returns/{return_id}`.
Path parameters
return_idstringRequiredFlint return id.
Request body
Send exactly one of these
The `exchange` variant of `CreateReturnResolutionRequest`. The `no_monetary_action` variant of `CreateReturnResolutionRequest`. The `refund` variant of `CreateReturnResolutionRequest`. The `replacement` variant of `CreateReturnResolutionRequest`. The `store_credit` variant of `CreateReturnResolutionRequest`.
adjustmentsarray of objectFees and credits to apply to the resolution, at most 50.
adjustment_typeenumRequiredWhat the fee or credit is for.
return_shipping_feerestocking_feeother_feegoodwill_creditprice_correctionother
applied_amount_moneyobjectRequiredAmount that counts toward the resolution. It can't exceed `assessed_amount_money`, and is zero when the adjustment is waived.
assessed_amount_moneyobjectRequiredAmount the fee or credit comes to before any waiver. Same currency as `applied_amount_money`.
reasonenumRequiredWhy the adjustment was made.
return_policyinspection_resultreturn_shipping_costcustomer_servicemanual_correctionother
reason_messagestringOptional detail about `reason`, kept with the record.
return_line_item_idstringID of the Return line a deduction applies to. Absent when it applies to the resolution as a whole.
statusenumWhether the adjustment counts toward the buyer's value. A waived adjustment applies zero.
appliedwaived
value_effectenumRequiredWhether the adjustment reduces or increases what the buyer receives.
deductioncredit
waiver_reasonenumWhy the adjustment was waived.
policy_overridemerchant_reviewcustomer_serviceother
waiver_reason_messagestringDetail about `waiver_reason`.
expected_return_versionintegerOptional version of the parent Return. A stale value returns VERSION_CONFLICT with the Return ID and its current version.
external_reference_idstringCaller-owned identifier for this resource in an external system.
gift_card_refund_destinationenumWhere the gift-card-paid portion is refunded. original credits the original gift card; new_gift_card issues new gift cards. Accepted for refund, exchange, and correction, except a correction of store_credit. Omit for store_credit, replacement, and no_monetary_action; sending it returns INVALID_REQUEST with a NOT_ALLOWED detail and conflicting_fields naming resolution_type and gift_card_refund_destination. Store credit and its corrections always issue new gift cards. PATCH can change it only while proposed. Retry persists the chosen destination before starting the new attempt.
originalnew_gift_card
line_itemsarray of objectRequiredReturn lines and quantities to cover, up to 100. Not allowed on a correction.
quantityintegerRequiredWhole-number quantity; fractional quantities are not supported.
return_line_item_idstringRequiredID of the Return line the resolution covers.
metadatamap of stringCaller-owned metadata. Values can't be empty strings. Keys starting with flint_ are reserved for Flint, are not returned, and cannot be written through the public API.
pricing_basisenumHow replacement lines are priced. Send with `exchange` or `replacement`.
original_pricecurrent_pricemerchant_agreed_price
replacement_line_itemsarray of one ofMerchandise the buyer receives instead, up to 100. Send with `exchange` or `replacement`.
Send exactly one of these
The `variant` variant of `ReturnReplacementLineItemInput`.
descriptionstringDescription of the replacement item.
quantityintegerRequiredWhole-number quantity; fractional quantities are not supported.
skustringSKU of the replacement item.
typeenumRequiredThe source of the replacement merchandise: variant, bundle, or custom.
variant
unit_price_moneyobjectPrice of one replacement unit. Required when `type` is `custom` or `pricing_basis` is `merchant_agreed_price`.
variant_idstringRequiredID of the variant to send. Used when `type` is `variant`.
resolution_typeenumRequiredWhat the buyer gets for the approved quantity.
refundexchangereplacementstore_creditno_monetary_action
The `correction` variant of `CreateReturnResolutionRequest`.
adjustmentsarray of objectRequiredFees and credits to apply to the resolution, at most 50.
adjustment_typeenumRequiredWhat the fee or credit is for.
return_shipping_feerestocking_feeother_feegoodwill_creditprice_correctionother
applied_amount_moneyobjectRequiredAmount that counts toward the resolution. It can't exceed `assessed_amount_money`, and is zero when the adjustment is waived.
assessed_amount_moneyobjectRequiredAmount the fee or credit comes to before any waiver. Same currency as `applied_amount_money`.
reasonenumRequiredWhy the adjustment was made.
return_policyinspection_resultreturn_shipping_costcustomer_servicemanual_correctionother
reason_messagestringOptional detail about `reason`, kept with the record.
return_line_item_idstringID of the Return line a deduction applies to. Absent when it applies to the resolution as a whole.
statusenumWhether the adjustment counts toward the buyer's value. A waived adjustment applies zero.
appliedwaived
value_effectenumRequiredWhether the adjustment reduces or increases what the buyer receives.
deductioncredit
waiver_reasonenumWhy the adjustment was waived.
policy_overridemerchant_reviewcustomer_serviceother
waiver_reason_messagestringDetail about `waiver_reason`.
corrects_return_resolution_idstringRequiredID of the settled resolution to correct. Send only with `resolution_type: correction`.
expected_return_versionintegerOptional version of the parent Return. A stale value returns VERSION_CONFLICT with the Return ID and its current version.
external_reference_idstringCaller-owned identifier for this resource in an external system.
gift_card_refund_destinationenumWhere the gift-card-paid portion is refunded. original credits the original gift card; new_gift_card issues new gift cards. Accepted for refund, exchange, and correction, except a correction of store_credit. Omit for store_credit, replacement, and no_monetary_action; sending it returns INVALID_REQUEST with a NOT_ALLOWED detail and conflicting_fields naming resolution_type and gift_card_refund_destination. Store credit and its corrections always issue new gift cards. PATCH can change it only while proposed. Retry persists the chosen destination before starting the new attempt.
originalnew_gift_card
metadatamap of stringCaller-owned metadata. Values can't be empty strings. Keys starting with flint_ are reserved for Flint, are not returned, and cannot be written through the public API.
resolution_typeenumRequiredWhat the buyer gets for the approved quantity.
correction
curl -X POST https://api.withflintpay.com/v1/returns/ret_01KEZF7C00PG93650ZKVQNGF7X/resolutions \
-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_return_version": 2,
"gift_card_refund_destination": "original",
"line_items": [
{
"quantity": 1,
"return_line_item_id": "retli_01KEZF7C001NHF6JPD83VD0MRK"
}
],
"resolution_type": "refund"
}'Was this helpful?
