Skip to content

From preview to settled#

  1. Preview with POST /v1/return-previews and mode: "resolution". Flint prices the outcome and reserves or starts nothing.
  2. Propose with POST /v1/returns/{return_id}/resolutions. The resolution is proposed and reserves its line quantity, so no other resolution can claim the same approved units.
  3. Edit or cancel the proposal with PATCH or /cancel. Canceling frees its quantity.
  4. Confirm with /confirm. The amounts freeze, and the effects start once each line's release_timing allows.

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_typeThe buyer getsFlint creates
refundMoney back on the original paymentA Refund
store_creditThe returned value on new gift cardsA Refund to new gift cards, with no processor refund
exchangeDifferent merchandiseA replacement Order, plus a Refund or a PaymentIntent for any difference
replacementThe same merchandise againA replacement Order, plus a Refund or a PaymentIntent for any difference
no_monetary_actionNothing, because no value is owedNothing
correctionAn adjustment to a resolution that settledA 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.

Resolutiongift_card_refund_destination
refund, exchange, and a correction of anything but store_creditAccepted and echoed on the resolution
store_credit, and a correction of itRejected. The value always goes on new gift cards
replacement, no_monetary_actionRejected

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:

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

Exchanging a $54.00 return for a $39.00 item, with a restocking fee
  • Returned valuereturned_total_money
    $54.00
  • Restocking feededuction_money
    −$5.00
  • Replacement Orderreplacement_total_money
    Tax included
    −$39.00
  • Refunded to the buyerbuyer_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.

FieldRule
adjustment_typerestocking_fee, return_shipping_fee, other_fee, goodwill_credit, price_correction, or other
value_effectdeduction adds to deduction_money; credit adds to credit_adjustment_money
assessed_amount_money, applied_amount_moneyBoth required and in one currency. The applied amount can't exceed the assessed amount
reasonRequired
statusDefaults to applied, or to waived when you send a waiver_reason. A waived adjustment applies zero
return_line_item_idScopes 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#

Return resolution statusStartFinal
  • 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 resolution
Final values do not change again
  • proposed
    Created, not confirmed. Nothing runs. You can edit it with PATCH, confirm it, or cancel it.
  • pending
    Confirmed, and executing or waiting on execution_blockers.
  • requires_action
    Waiting on a person. action_required_by says who and action_reason says why, such as manual_release until a merchant calls /release, or buyer_payment while the buyer's payment for a balance needs them. Once they act, it returns to pending.
  • fulfilledFinal
    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. A correction can adjust it afterward.
  • failed
    Execution stopped. failure_code says why and whether retrying can help. See Failure codes.
  • canceledFinal
    Canceled. 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.

codeCleared by
handoff_pendingThe buyer handing the merchandise to a carrier
receipt_pendingThe merchandise being received
inspection_pendingAn inspection accepting it
manual_release_pendingA merchant calling /release
buyer_payment_pendingThe buyer paying the balance
refund_pendingThe linked Refund succeeding
replacement_order_pendingFlint creating the replacement Order
fulfillment_pendingThe 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_timingThe resolution runs
after_approvalAs soon as it's confirmed
after_handoffOnce the buyer hands the merchandise to a carrier
after_receiptOnce the merchandise is received
after_inspectionOnce an inspection accepts it, or on receipt when the line's inspection is waived
manualWhen 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 resolution
  • gift_card_refund_destination_required
    Retryable. The original gift card is closed, or the amount would pass its balance cap. Retry with gift_card_refund_destination: "new_gift_card".
  • store_credit_unavailable
    Not retryable. The order's payments can no longer fund store credit. Cancel the resolution, then create a refund resolution.
  • refund_creation_failed
    Retryable. Flint couldn't create the Refund after retrying.
  • refund_failed
    Retryable. The Refund was created and failed; failure_message says why. Fix the cause, then retry, which creates a new Refund.
  • refund_line_value_unavailable
    Not 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_failed
    Retryable. Flint couldn't create the buyer's PaymentIntent after retrying. Retry resumes the payment.
  • payment_failed
    Retryable. The buyer's PaymentIntent was canceled or expired. Retry, then launch /checkout-sessions again for the new payment.
  • replacement_order_creation_failed
    Retryable. Flint couldn't create the replacement Order after retrying.
  • replacement_fulfillment_canceled
    Final. 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 a resolution_failed completion blocker. To send a replacement another way, fail the fulfillment instead of canceling it; see Cancel, fail, and try again.
  • resolution_effect_failed
    Retryable. 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.

FieldWhere it appears
cancellation_reasonEvery read, including the buyer's /v1/me/return-resolutions view
cancellation_reason_messageMerchant reads only
canceled_byMerchant 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 fulfilled and 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, and pricing_basis are rejected.
  • It pays out like its target. A correction of store_credit issues new gift cards; any other correction refunds the original payment and takes its own gift_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, or return_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#

  • HTTP 400
    details[0] names the field. A REQUIRED detail with param: "expected_version" means a PATCH sent an array without the version. An INVALID_VALUE detail on a member ID, such as adjustments[0].return_resolution_adjustment_id, means the ID belongs to another resolution or appears twice. An INVALID_VALUE detail on an adjustment's applied_amount_money.amount means a deduction exceeds what it can reduce. A NOT_ALLOWED detail with conflicting_fields: ["resolution_type", "gift_card_refund_destination"] means the type doesn't take a gift card destination.
  • HTTP 409
    The resolution's state or the order refuses the action, and details[0].reason says why. terminal_status: the resolution is fulfilled or canceled. unsupported_state: another status, or a retry of a failure_code that retrying can't fix. refund_created: canceling a failed resolution whose Refund isn't failed or canceled; remediation.next_actions offers get_refund. refund_unavailable or store_credit_unavailable: on create or confirm, the order's payments can't fund a refund or store_credit, and details[0] names the order. Read supported_actions and choose another action or outcome.
  • HTTP 409
    VERSION_CONFLICTRefresh, then retry
    The expected_version or expected_return_version you sent is stale. details[0].current_version has 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
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#

The Refunds, PaymentIntents, and Orders a resolution creates send their own events. How this lands elsewhere covers how they link back.

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_reasonenum

What the resolution waits for while its status is `requires_action`.

  • buyer_payment
  • buyer_selection
  • merchant_review
  • manual_release
  • linked_effect_retry
  • other
action_required_byenum

Who has to act while the resolution's status is `requires_action`.

  • buyer
  • merchant
adjustmentsarray of objectRequired

Fees and credits applied to the resolution's amounts.

buyer_payment_amount_moneyobjectRequired

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

Value 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_atstring

RFC3339 timestamp.

canceled_byobject

Who canceled the resolution. Merchant reads only.

Not returned with a customer session

cancellation_reasonenum

Why the resolution was canceled.

  • buyer_request
  • merchant_request
  • duplicate
  • expired
  • created_in_error
  • other
cancellation_reason_messagestring

Detail sent with the cancellation. Merchant reads only.

Not returned with a customer session

confirmed_atstring

RFC3339 timestamp.

confirmed_byobject

Who confirmed the resolution.

Not returned with a customer session

corrects_return_resolution_idstring

ID of the settled resolution this correction adjusts. Present only when `resolution_type` is `correction`.

Not returned with a customer session

created_atstringRequired

RFC3339 timestamp.

created_byobjectRequired

Who created the resolution.

Not returned with a customer session

credit_adjustment_moneyobjectRequired

Credits added by the resolution's adjustments.

deduction_moneyobjectRequired

Deductions taken by the resolution's adjustments, such as a restocking fee.

execution_blockersarray of objectRequired

What a confirmed resolution is still waiting for. Empty when nothing is.

external_reference_idstring

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

Not returned with a customer session

failure_codeenum

Reason 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_required
  • store_credit_unavailable
  • refund_creation_failed
  • refund_failed
  • refund_line_value_unavailable
  • payment_intent_creation_failed
  • payment_failed
  • replacement_order_creation_failed
  • replacement_fulfillment_canceled
  • resolution_effect_failed
failure_messagestring

Explanation of a failed Return resolution, when available.

fulfilled_atstring

When the resolution became fulfilled.

gift_card_refund_destinationenum

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

  • original
  • new_gift_card
line_itemsarray of objectRequired

Return lines and quantities the resolution covers. Absent on a correction.

metadatamap of stringRequired

Stored caller-owned key-value data. See `MetadataInput` for key, value, and size rules.

payment_intent_idsarray of stringRequired

Not returned with a customer session

payment_intentsarray of object

Not returned with a customer session

pricing_basisenum

How replacement lines are priced. Present on exchanges and replacements.

  • original_price
  • current_price
  • merchant_agreed_price
refund_idsarray of stringRequired

Not returned with a customer session

refundsarray of object

Not returned with a customer session

replacement_line_itemsarray of objectRequired

Merchandise the buyer receives instead, for an exchange or replacement.

replacement_orderobject or null

Present only when `expand` includes `replacement_order`; `null` when expanded and there is no related order.

Not returned with a customer session

replacement_order_idstring

ID of the replacement Order Flint created for an exchange or replacement. Absent until it exists.

Not returned with a customer session

replacement_total_moneyobjectRequired

Total of the replacement items the buyer receives.

resolution_typeenumRequired

What the buyer gets for the approved quantity.

  • refund
  • exchange
  • replacement
  • store_credit
  • no_monetary_action
  • correction
return_idstringRequired

ID of the Return the resolution belongs to.

return_policy_revision_idstring

Not returned with a customer session

return_resolution_idstringRequired

Unique identifier for this return resolution, prefixed `retres_`.

returned_total_moneyobjectRequired

Value of the returned units this resolution covers.

statusenumRequired

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

  • proposed
  • pending
  • requires_action
  • fulfilled
  • failed
  • canceled
supported_actionsarray of enumRequired

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

  • cancel
  • checkout_session
  • confirm
  • release
  • retry
updated_atstringRequired

RFC3339 timestamp.

versionintegerRequired

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

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

GET/v1/return-resolutions

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

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 enum

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

  • buyer
  • merchant
  • integration
corrects_return_resolution_idstring

Filter by corrects return resolution id.

created_afterstring

Inclusive lower bound on created_at.

created_beforestring

Exclusive upper bound on created_at.

external_reference_idstring

Exact-match filter on the caller-owned external reference ID.

page_sizeinteger

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

page_tokenstring

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

querystring

Search by return resolution ID or external reference ID.

resolution_typearray of enum

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

  • refund
  • exchange
  • replacement
  • store_credit
  • no_monetary_action
  • correction
return_idstring

Filter by return id.

return_line_item_idstring

Filter by return line item id.

return_policy_revision_idstring

Filter by return policy revision id.

statusarray of enum

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

  • proposed
  • pending
  • requires_action
  • fulfilled
  • failed
  • canceled
updated_afterstring

Inclusive lower bound on updated_at.

updated_beforestring

Exclusive upper bound on updated_at.

expandarray of enum

Include 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 objectRequired

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

metaobject

Additional information about this response.

next_page_tokenstring

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

request_idstringRequired

Identifier of this API request, used to correlate logs and support requests.

curl https://api.withflintpay.com/v1/return-resolutions \
  -H "Flint-Version: 2026-09-07" \
  -H "Authorization: Bearer YOUR_API_KEY"

Successful response.

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

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

Flint return resolution id.

Query parameters

expandarray of enum

Include 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_intents
  • refunds
  • replacement_order

Response · 200

Successful response.

dataobjectRequired

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

metaobject

Additional information about this response.

request_idstringRequired

Identifier of this API request, used to correlate logs and support requests.

curl https://api.withflintpay.com/v1/return-resolutions/retres_01KEZF7C00C7RZJN31W9SGMEQ3 \
  -H "Flint-Version: 2026-09-07" \
  -H "Authorization: Bearer YOUR_API_KEY"

Successful response.

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

PATCH/v1/return-resolutions/{return_resolution_id}Idempotent

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

Flint return resolution id.

Request body

adjustmentsarray of object

Requires expected_version.

expected_versioninteger

Required when any of these fields is present: line_items, replacement_line_items, adjustments.

external_reference_idstring or null

Caller-owned identifier for this resource in an external system. Send null to clear it.

gift_card_refund_destinationenum

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

  • original
  • new_gift_card
line_itemsarray of object

Requires expected_version.

metadatamap of string or null

Caller-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_basisenum

How replacement lines are priced. Send with `exchange` or `replacement`.

  • original_price
  • current_price
  • merchant_agreed_price
replacement_line_itemsarray of one of

Requires expected_version.

Response · 200

Successful response.

Same response as Get return resolution.

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#

POST/v1/return-resolutions/{return_resolution_id}/cancelIdempotent

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

Flint return resolution id.

Request body

expected_versioninteger

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

reasonenumRequired

Why it is being canceled.

  • buyer_request
  • merchant_request
  • duplicate
  • expired
  • created_in_error
  • other
reason_messagestring

Optional detail about `reason`, kept with the record.

Response · 200

Successful response.

Same response as Get return resolution.

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#

POST/v1/return-resolutions/{return_resolution_id}/checkout-sessionsIdempotent

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

Flint return resolution id.

Request body

page_originstring

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

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

redirectsobject

Where hosted checkout sends the buyer. Not allowed when surface is embedded; use payment_return_url.

return_urlstring

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

surfaceenum

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

  • hosted
  • embedded

Response · 201

Checkout session created.

dataobjectRequired

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

metaobject

Additional information about this response.

request_idstringRequired

Identifier of this API request, used to correlate logs and support requests.

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#

POST/v1/return-resolutions/{return_resolution_id}/confirmIdempotent

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

Flint return resolution id.

Request body

expected_versioninteger

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

Response · 200

Successful response.

Same response as Get return resolution.

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#

POST/v1/return-resolutions/{return_resolution_id}/releaseIdempotent

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

Flint return resolution id.

Request body

expected_versioninteger

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

reasonenumRequired

Why the resolution is being released.

  • merchant_approved
  • exception_resolved
  • other
reason_messagestring

Optional detail about `reason`, kept with the record.

Response · 200

Successful response.

Same response as Get return resolution.

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#

POST/v1/return-resolutions/{return_resolution_id}/retryIdempotent

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

Flint return resolution id.

Request body

expected_versioninteger

Version 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_destinationenum

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

  • original
  • new_gift_card
reasonenumRequired

Why the resolution is being run again.

  • dependency_recovered
  • payment_method_updated
  • operator_retry
  • other
reason_messagestring

Optional detail about `reason`, kept with the record.

Response · 200

Successful response.

Same response as Get return resolution.

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#

POST/v1/returns/{return_id}/resolutionsIdempotent

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

Flint 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 object

Fees and credits to apply to the resolution, at most 50.

expected_return_versioninteger

Optional version of the parent Return. A stale value returns VERSION_CONFLICT with the Return ID and its current version.

external_reference_idstring

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

gift_card_refund_destinationenum

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

  • original
  • new_gift_card
line_itemsarray of objectRequired

Return lines and quantities to cover, up to 100. Not allowed on a correction.

metadatamap of string

Caller-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_basisenum

How replacement lines are priced. Send with `exchange` or `replacement`.

  • original_price
  • current_price
  • merchant_agreed_price
replacement_line_itemsarray of one of

Merchandise the buyer receives instead, up to 100. Send with `exchange` or `replacement`.

resolution_typeenumRequired

What the buyer gets for the approved quantity.

  • refund
  • exchange
  • replacement
  • store_credit
  • no_monetary_action

Response · 201

Successful response.

Same response as Get return resolution.

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?