FlintflintDocs

Return resolutions

Return resolutions represent buyer-value outcomes. Previewing is side-effect free. Creating an ordinary proposed resolution reserves Return value capacity, and confirming it freezes the calculation and starts or gates downstream effects. The Return resolutions guide covers the flow end to end.

Effects remain normal Flint resources. Refund resolutions link Refunds, exchanges and replacements link Orders, and buyer balances link PaymentIntents. Read execution_blockers and linked effect statuses instead of treating a successful API response as proof that money moved or merchandise shipped.

Types#

TypeOutcome
refundMoney back on the original payment
exchangeDifferent merchandise, with any difference settled either way
replacementThe same merchandise again, with no money moving
no_monetary_actionGoods come back and no value is owed
correctionAdjusts a resolution that already settled

Store credit is reserved and not published until Flint has a reconciled credit ledger. A refund goes to the original payer and payment method, including on a gift return; where that is unacceptable, decline the monetary resolution.

Lifecycle#

proposed to pending to partially_fulfilled to fulfilled, with requires_action, failed, and canceled as the ways out. requires_action means something outside Flint has to happen, usually the buyer paying an exchange balance.

A confirmed resolution stays pending while execution_blockers names what it is waiting for.

BlockerCleared by
handoff_pendingThe buyer handing merchandise to a carrier
receipt_pendingThe warehouse recording arrival
inspection_pendingAn inspection and its acceptance decision
manual_release_pendingA call to /release
buyer_payment_pendingThe buyer paying a balance
refund_pendingThe refund settling
replacement_order_pendingThe replacement Order being created
fulfillment_pendingThe replacement shipping
credit_effect_pendingA linked credit effect completing

The first three follow from refund_timing on the decision (after_handoff, after_receipt, after_inspection), which is how you avoid paying out for goods that never arrive.

Adjustments#

Fees and credits are adjustments on the resolution rather than separate objects, so they stay in the same arithmetic as the refund: restocking_fee, return_shipping_fee, other_fee, goodwill_credit, price_correction, other. Each carries a value_effect of deduction or credit and rolls up into the Return's financial_summary as deduction_money or credit_money, never netted invisibly into refunded_money.

Corrections#

A correction is a new resolution with resolution_type=correction and corrects_return_resolution_id. Its target must be fulfilled and belong to the same reopened Return. Corrections contain applied credit or deduction adjustments but no Return line allocations, replacement lines, or pricing basis. They preserve the original resource graph and create a normal compensating Refund for positive net buyer credit when confirmed. Deductions may offset a credit to zero, but a correction that leaves the buyer owing money is rejected until Flint has a shared hosted collection flow for standalone PaymentIntents. Reverse lookup uses the corrects_return_resolution_id list filter.

Writes#

Child mutations on /line-items and /replacement-line-items return the parent resolution rather than the mutated line. A replacement line takes exactly one of variant_id, bundle_id, or name. Writes take expected_return_resolution_revision, and /release is available only while action_reason is manual_release.

Endpoints

Create return resolution preview#

POST/v1/return-resolution-previewsRequires scope: commerce.return_policies.write or commerce.return_reasons.write or commerce.returns.decisions.write or commerce.returns.operations.write or commerce.returns.process.write or commerce.returns.read or commerce.returns.resolutions.write or commerce.returns.write

Calculate resolution amounts and warnings without reserving value or creating a resolution. Requested Returns use eligible policy capacity; open Returns use committed approved capacity. The result is advisory and tied to based_on_return_revision.

Request body
option 1object
option 2object
Response · 200
dataobjectrequired
metaobject
request_idstring

Error codes

AUTH_REQUIREDINSUFFICIENT_SCOPEINVALID_REQUESTRATE_LIMIT_EXCEEDEDRESOURCE_NOT_FOUND
Bash
curl -X POST https://api.withflintpay.com/v1/return-resolution-previews \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "resolution_type": "refund",
    "return_id": ""
  }'

List return resolutions#

GET/v1/return-resolutionsRequires scope: commerce.return_policies.write or commerce.return_reasons.write or commerce.returns.decisions.write or commerce.returns.operations.write or commerce.returns.process.write or commerce.returns.read or commerce.returns.resolutions.write or commerce.returns.write

List resolutions. Filter by corrects_return_resolution_id to retrieve the correction history for a resolution that already settled.

Query parameters
action_required_byenum

Filter by action required by.

buyermerchantintegration
corrects_return_resolution_idstring

Filter by corrects return resolution id.

created_afterstring

RFC3339 created after filter.

created_beforestring

RFC3339 created before filter.

external_reference_idstring

Filter by external reference id.

page_sizeinteger

Page size. Defaults to 20 and is capped at 100.

page_tokenstring

Opaque cursor returned by the previous page.

resolution_typearray of enum

Filter by resolution type.

refundexchangereplacementno_monetary_actioncorrection
return_idstring

Filter by return id.

return_line_item_idstring

Filter by return line item id.

return_policy_version_idstring

Filter by return policy version id.

statusarray of enum

Filter by status.

proposedpendingrequires_actionpartially_fulfilledfulfilledfailedcanceled
updated_afterstring

RFC3339 updated after filter.

updated_beforestring

RFC3339 updated before filter.

Response · 200
dataarray of objectrequired
metaobject
next_page_tokenstring
request_idstring

Error codes

AUTH_REQUIREDINSUFFICIENT_SCOPEINVALID_REQUESTRATE_LIMIT_EXCEEDED
Bash
curl https://api.withflintpay.com/v1/return-resolutions \
  -H "Authorization: Bearer YOUR_API_KEY"

Get return resolution#

GET/v1/return-resolutions/{return_resolution_id}Requires scope: commerce.return_policies.write or commerce.return_reasons.write or commerce.returns.decisions.write or commerce.returns.operations.write or commerce.returns.process.write or commerce.returns.read or commerce.returns.resolutions.write or commerce.returns.write

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

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; path depth at most 2. To-many expansions are capped at 20 related objects per path. Send repeated expand parameters as the canonical form, for example expand=payment_intents&expand=refunds. Comma-separated values, expand[]=payment_intents, and numeric expand[0]=payment_intents are accepted for common client compatibility.

payment_intentsrefundsreplacement_order
Response · 200
dataobjectrequired
metaobject
request_idstring

Error codes

AUTH_REQUIREDDANGLING_EXPANSION_REFERENCEEXPANSION_DEPENDENCY_UNAVAILABLEEXPANSION_RESOLUTION_FAILEDINSUFFICIENT_SCOPEINTERNAL_ERRORINVALID_REQUESTRATE_LIMIT_EXCEEDEDRESOURCE_NOT_FOUNDSERVICE_UNAVAILABLE
Bash
curl https://api.withflintpay.com/v1/return-resolutions/{return_resolution_id} \
  -H "Authorization: Bearer YOUR_API_KEY"

Update return resolution#

PATCH/v1/return-resolutions/{return_resolution_id}IdempotentRequires scope: commerce.returns.resolutions.write

Update a proposed resolution before confirmation. Only pricing_basis, adjustment_set, external_reference_id, and metadata are writable.

Path parameters
return_resolution_idstringrequired

Flint return resolution id.

Request body
adjustment_setobject
expected_return_resolution_revisionintegerrequired
external_reference_idstring
metadatamap of string
pricing_basisenum
original_pricecurrent_pricemerchant_agreed_price
Response · 200
dataobjectrequired
metaobject
request_idstring

Error codes

AUTH_REQUIREDINSUFFICIENT_SCOPEINVALID_REQUESTRATE_LIMIT_EXCEEDEDRESOURCE_NOT_FOUND
Bash
curl -X PATCH https://api.withflintpay.com/v1/return-resolutions/{return_resolution_id} \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{
    "expected_return_resolution_revision": 0
  }'

Cancel return resolution#

POST/v1/return-resolutions/{return_resolution_id}/cancelIdempotentRequires scope: commerce.returns.resolutions.write

Cancel a resolution and release the line value it reserved. Effects that already succeeded are undone with a compensating correction instead.

Path parameters
return_resolution_idstringrequired

Flint return resolution id.

Request body
expected_return_resolution_revisionintegerrequired
reasonenumrequired
buyer_requestmerchant_requestduplicateexpiredcreated_in_errorother
reason_messagestring
Response · 200
dataobjectrequired
metaobject
request_idstring

Error codes

AUTH_REQUIREDINSUFFICIENT_SCOPEINVALID_REQUESTRATE_LIMIT_EXCEEDEDRESOURCE_NOT_FOUND
Bash
curl -X POST https://api.withflintpay.com/v1/return-resolutions/{return_resolution_id}/cancel \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{
    "expected_return_resolution_revision": 0,
    "reason": "buyer_request"
  }'

Get or create return resolution checkout session#

POST/v1/return-resolutions/{return_resolution_id}/checkout-sessionIdempotentRequires scope: commerce.returns.resolutions.write

Create or reuse the standard hosted checkout session for a buyer-owed replacement Order linked to this Return resolution.

Path parameters
return_resolution_idstringrequired

Flint return resolution id.

Response · 201
dataobjectrequired

Checkout-session access returned for hosted or embedded checkout creation.

metaobject
request_idstring

Error codes

AUTH_REQUIREDINSUFFICIENT_SCOPEINVALID_REQUESTRATE_LIMIT_EXCEEDEDRESOURCE_NOT_FOUND
Bash
curl -X POST https://api.withflintpay.com/v1/return-resolutions/{return_resolution_id}/checkout-session \
  -H "Authorization: Bearer YOUR_API_KEY"

Confirm return resolution#

POST/v1/return-resolutions/{return_resolution_id}/confirmIdempotentRequires scope: commerce.returns.resolutions.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_return_resolution_revisionintegerrequired
Response · 200
dataobjectrequired
metaobject
request_idstring

Error codes

AUTH_REQUIREDINSUFFICIENT_SCOPEINVALID_REQUESTRATE_LIMIT_EXCEEDEDRESOURCE_NOT_FOUND
Bash
curl -X POST https://api.withflintpay.com/v1/return-resolutions/{return_resolution_id}/confirm \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{
    "expected_return_resolution_revision": 0
  }'

Add return resolution line item#

POST/v1/return-resolutions/{return_resolution_id}/line-itemsIdempotentRequires scope: commerce.returns.resolutions.write

Add approved Return quantity to a proposed resolution. The response is the updated resolution, not the new line.

Path parameters
return_resolution_idstringrequired

Flint return resolution id.

Request body
expected_return_resolution_revisionintegerrequired
line_itemobjectrequired
Response · 200
dataobjectrequired
metaobject
request_idstring

Error codes

AUTH_REQUIREDINSUFFICIENT_SCOPEINVALID_REQUESTRATE_LIMIT_EXCEEDEDRESOURCE_NOT_FOUND
Bash
curl -X POST https://api.withflintpay.com/v1/return-resolutions/{return_resolution_id}/line-items \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{
    "expected_return_resolution_revision": 0,
    "line_item": {
      "quantity": 0,
      "return_line_item_id": ""
    }
  }'

Get return resolution line item#

GET/v1/return-resolutions/{return_resolution_id}/line-items/{return_resolution_line_item_id}Requires scope: commerce.return_policies.write or commerce.return_reasons.write or commerce.returns.decisions.write or commerce.returns.operations.write or commerce.returns.process.write or commerce.returns.read or commerce.returns.resolutions.write or commerce.returns.write

Retrieve one resolution line item with the Return quantity it covers and its calculated value.

Path parameters
return_resolution_idstringrequired

Flint return resolution id.

return_resolution_line_item_idstringrequired

Flint return resolution line item id.

Response · 200
dataobjectrequired
metaobject
request_idstring

Error codes

AUTH_REQUIREDINSUFFICIENT_SCOPEINVALID_REQUESTRATE_LIMIT_EXCEEDEDRESOURCE_NOT_FOUND
Bash
curl https://api.withflintpay.com/v1/return-resolutions/{return_resolution_id}/line-items/{return_resolution_line_item_id} \
  -H "Authorization: Bearer YOUR_API_KEY"

Update return resolution line item#

PATCH/v1/return-resolutions/{return_resolution_id}/line-items/{return_resolution_line_item_id}IdempotentRequires scope: commerce.returns.resolutions.write

Update a line item on a proposed resolution. The response is the updated resolution.

Path parameters
return_resolution_idstringrequired

Flint return resolution id.

return_resolution_line_item_idstringrequired

Flint return resolution line item id.

Request body
expected_return_resolution_revisionintegerrequired
quantityintegerrequired

Whole-number quantity; fractional quantities are not supported.

Response · 200
dataobjectrequired
metaobject
request_idstring

Error codes

AUTH_REQUIREDINSUFFICIENT_SCOPEINVALID_REQUESTRATE_LIMIT_EXCEEDEDRESOURCE_NOT_FOUND
Bash
curl -X PATCH https://api.withflintpay.com/v1/return-resolutions/{return_resolution_id}/line-items/{return_resolution_line_item_id} \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{
    "expected_return_resolution_revision": 0,
    "quantity": 0
  }'

Delete return resolution line item#

DELETE/v1/return-resolutions/{return_resolution_id}/line-items/{return_resolution_line_item_id}IdempotentRequires scope: commerce.returns.resolutions.write

Remove a line item from a proposed resolution, releasing the line value it reserved. The response is the updated resolution.

Path parameters
return_resolution_idstringrequired

Flint return resolution id.

return_resolution_line_item_idstringrequired

Flint return resolution line item id.

Response · 200
dataobjectrequired
metaobject
request_idstring

Error codes

AUTH_REQUIREDINSUFFICIENT_SCOPEINVALID_REQUESTRATE_LIMIT_EXCEEDEDRESOURCE_NOT_FOUND
Bash
curl -X DELETE https://api.withflintpay.com/v1/return-resolutions/{return_resolution_id}/line-items/{return_resolution_line_item_id} \
  -H "Authorization: Bearer YOUR_API_KEY"

Release return resolution#

POST/v1/return-resolutions/{return_resolution_id}/releaseIdempotentRequires scope: commerce.returns.resolutions.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_return_resolution_revisionintegerrequired
reasonenumrequired
merchant_approvedexception_resolvedother
reason_messagestring
Response · 200
dataobjectrequired
metaobject
request_idstring

Error codes

AUTH_REQUIREDINSUFFICIENT_SCOPEINVALID_REQUESTRATE_LIMIT_EXCEEDEDRESOURCE_NOT_FOUND
Bash
curl -X POST https://api.withflintpay.com/v1/return-resolutions/{return_resolution_id}/release \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{
    "expected_return_resolution_revision": 0,
    "reason": "merchant_approved"
  }'

Add return replacement line item#

POST/v1/return-resolutions/{return_resolution_id}/replacement-line-itemsIdempotentRequires scope: commerce.returns.resolutions.write

Add outbound merchandise to an exchange or replacement resolution. Provide exactly one of variant_id, bundle_id, or name. The response is the updated resolution.

Path parameters
return_resolution_idstringrequired

Flint return resolution id.

Request body
expected_return_resolution_revisionintegerrequired
line_itemone ofrequired
Response · 200
dataobjectrequired
metaobject
request_idstring

Error codes

AUTH_REQUIREDINSUFFICIENT_SCOPEINVALID_REQUESTRATE_LIMIT_EXCEEDEDRESOURCE_NOT_FOUND
Bash
curl -X POST https://api.withflintpay.com/v1/return-resolutions/{return_resolution_id}/replacement-line-items \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{
    "expected_return_resolution_revision": 0,
    "line_item": {
      "quantity": 0
    }
  }'

Get return replacement line item#

GET/v1/return-resolutions/{return_resolution_id}/replacement-line-items/{return_replacement_line_item_id}Requires scope: commerce.return_policies.write or commerce.return_reasons.write or commerce.returns.decisions.write or commerce.returns.operations.write or commerce.returns.process.write or commerce.returns.read or commerce.returns.resolutions.write or commerce.returns.write

Retrieve one replacement line item with the outbound merchandise it will ship.

Path parameters
return_replacement_line_item_idstringrequired

Flint return replacement line item id.

return_resolution_idstringrequired

Flint return resolution id.

Response · 200
dataobjectrequired
metaobject
request_idstring

Error codes

AUTH_REQUIREDINSUFFICIENT_SCOPEINVALID_REQUESTRATE_LIMIT_EXCEEDEDRESOURCE_NOT_FOUND
Bash
curl https://api.withflintpay.com/v1/return-resolutions/{return_resolution_id}/replacement-line-items/{return_replacement_line_item_id} \
  -H "Authorization: Bearer YOUR_API_KEY"

Update return replacement line item#

PATCH/v1/return-resolutions/{return_resolution_id}/replacement-line-items/{return_replacement_line_item_id}IdempotentRequires scope: commerce.returns.resolutions.write

Update replacement merchandise on a proposed resolution. The response is the updated resolution.

Path parameters
return_replacement_line_item_idstringrequired

Flint return replacement line item id.

return_resolution_idstringrequired

Flint return resolution id.

Request body
expected_return_resolution_revisionintegerrequired
quantityintegerrequired

Whole-number quantity; fractional quantities are not supported.

unit_price_moneyobject

Monetary amount represented as integer minor units plus an ISO 4217 currency code.

Response · 200
dataobjectrequired
metaobject
request_idstring

Error codes

AUTH_REQUIREDINSUFFICIENT_SCOPEINVALID_REQUESTRATE_LIMIT_EXCEEDEDRESOURCE_NOT_FOUND
Bash
curl -X PATCH https://api.withflintpay.com/v1/return-resolutions/{return_resolution_id}/replacement-line-items/{return_replacement_line_item_id} \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{
    "expected_return_resolution_revision": 0,
    "quantity": 0
  }'

Delete return replacement line item#

DELETE/v1/return-resolutions/{return_resolution_id}/replacement-line-items/{return_replacement_line_item_id}IdempotentRequires scope: commerce.returns.resolutions.write

Remove replacement merchandise from a proposed resolution. The response is the updated resolution.

Path parameters
return_replacement_line_item_idstringrequired

Flint return replacement line item id.

return_resolution_idstringrequired

Flint return resolution id.

Response · 200
dataobjectrequired
metaobject
request_idstring

Error codes

AUTH_REQUIREDINSUFFICIENT_SCOPEINVALID_REQUESTRATE_LIMIT_EXCEEDEDRESOURCE_NOT_FOUND
Bash
curl -X DELETE https://api.withflintpay.com/v1/return-resolutions/{return_resolution_id}/replacement-line-items/{return_replacement_line_item_id} \
  -H "Authorization: Bearer YOUR_API_KEY"

Retry return resolution#

POST/v1/return-resolutions/{return_resolution_id}/retryIdempotentRequires scope: commerce.returns.resolutions.write

Retry a failed resolution. 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.

Path parameters
return_resolution_idstringrequired

Flint return resolution id.

Request body
expected_return_resolution_revisionintegerrequired
reasonenumrequired
dependency_recoveredpayment_method_updatedoperator_retryother
reason_messagestring
Response · 200
dataobjectrequired
metaobject
request_idstring

Error codes

AUTH_REQUIREDINSUFFICIENT_SCOPEINVALID_REQUESTRATE_LIMIT_EXCEEDEDRESOURCE_NOT_FOUND
Bash
curl -X POST https://api.withflintpay.com/v1/return-resolutions/{return_resolution_id}/retry \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{
    "expected_return_resolution_revision": 0,
    "reason": "dependency_recovered"
  }'

Create return resolution#

POST/v1/returns/{return_id}/resolutionsIdempotentRequires scope: commerce.returns.resolutions.write

Propose a buyer-value outcome for approved quantity. Creating a resolution reserves line value. Confirmation is what freezes it and starts its effects.

Path parameters
return_idstringrequired

Flint return id.

Request body
option 1object
option 2object
Response · 201
dataobjectrequired
metaobject
request_idstring

Error codes

AUTH_REQUIREDINSUFFICIENT_SCOPEINVALID_REQUESTRATE_LIMIT_EXCEEDEDRESOURCE_NOT_FOUND
Bash
curl -X POST https://api.withflintpay.com/v1/returns/ret_01K0P7W6A4N9F3J2T8Q5R1C6XM/resolutions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{
    "expected_return_revision": 0,
    "resolution_type": "refund"
  }'
Rate this doc