Returns
A Return takes merchandise back against an Order and settles what the buyer is owed. It records your decision, what physically comes back and where it goes, and the value the buyer receives, and it links the Refunds, gift cards, replacement Orders, PaymentIntents, and inventory movements those create.
Use a Return whenever goods come back, including a refund where the buyer keeps them. Use a Refund on its own only when money moves and no merchandise is involved: a Refund skips eligibility, restocking fees, inspection, and inventory.
The Returns guide explains the model and helps you pick an integration. Your first return takes one item from a paid order to a settled refund in sandbox.
How a Return moves#
Each kind of work has its own routes and write scope, so a store, a warehouse, and a support tool can each hold only the authority it needs. Any Returns scope, read or write, can read Returns and their records.
| Work | Routes | Scope |
|---|---|---|
| Check what can come back, or price an outcome | POST /v1/return-previews with mode: eligibility or mode: resolution | commerce.returns.read |
| Request the return, then approve or decline it | POST /v1/returns, the line item routes, then POST /v1/returns/{return_id}/decide | commerce.returns.write |
| Record what arrived, its condition, and where it went | Receipts, inspections, and dispositions | commerce.returns.operations.write |
| Give the buyer their value | Resolutions: refunds, store credit, exchanges, and replacements | commerce.returns.resolutions.write |
| Cancel, complete, or reopen | /cancel, /complete, and /reopen | commerce.returns.write |
POST /v1/returns/{return_id}/process commits decisions, receipts, inspections, dispositions, and resolutions in one request, so it needs all three write scopes. A counter return usually does everything in one process call. A mail-in return records each step as it happens. Either way, Refunds, payments, replacement Orders, and inventory updates complete asynchronously after the request returns.
Each Return is evaluated against your return policies, and each line names one of your return reasons. Scopes lists everything each scope allows.
Statuses#
A Return carries four status fields and a list of what is still owed. Read the one that answers your question instead of inferring it from another.
| Question | Read |
|---|---|
| Did we say yes? | decision_status |
| Did the goods come back? | merchandise_status |
| Did the buyer get their value? | resolution_status |
| Where does the whole Return stand? | status |
| What is still owed? | completion_blockers, empty when nothing is |
This open Return refunded the buyer on approval and is waiting for the parcel:
{
"return_id": "ret_01J5Z8N3QK4W7Y2RB6TPVXHC9D",
"status": "open",
"decision_status": "approved",
"merchandise_status": "in_transit",
"resolution_status": "fulfilled",
"completion_mode": "automatic",
"completion_blockers": [
{
"code": "receipt_pending",
"message": "Handed-off merchandise has not been received.",
"return_line_item_id": "retli_01J5Z8P4R7T2W9X3Y6B8C1D5FG"
}
]
}
Read every value with its field name. pending on decision_status means no decision yet, and on resolution_status it means a resolution is proposed or executing. What pending means compares it across every Returns resource.
Each Return line carries its own status, merchandise_status, and resolution_status with the same meanings. Two values appear only on the Return: exception on merchandise_status, and partially_fulfilled on resolution_status.
Return status#
- requested moves to open on approve
- requested moves to declined on decline
- requested moves to canceled on cancel
- open moves to completed on complete
- open moves to canceled on cancel
- completed moves to open on reopen
status on returnrequestedWaiting for a decision. You can cancel it, and the buyer can withdraw it.openSome quantity was approved. Merchandise or value work may remain; readcompletion_blockers.completedEvery completion blocker cleared and the Return completed./reopenreturns it toopen.declinedFinalDecided with nothing approved.canceledFinalCanceled before any receipt, inspection, disposition, or resolution was recorded, or all of its approved quantity was canceled.
completed isn't final, so you can record late compensating facts such as a correction. Reopening sets completion_mode to manual, so the Return stays open until you call /complete again. It also clears completed_at, completed_by, completion_reason, and completion_reason_message. A Return can be reopened more than once, so each reopen reason is recorded in its activities, not on the Return.
decision_status is pending until one decision covers every line at once. It doesn't change afterward, including on reopen: approved quantity canceled later shows in the line's canceled_quantity.
Merchandise status#
merchandise_status on returnnot_requiredNothing has to come back: the buyer keeps the goods (return_required_quantity: 0), or the Return isn't decided yet. A line whose approved quantity is all canceled reports it too.awaiting_handoffApproved merchandise hasn't been handed off.in_transitThe buyer handed it off and nothing has arrived.partially_receivedSome of the expected merchandise arrived.inspection_requiredEverything arrived and none of it is inspected yet. Only lines withis_inspection_requiredreach the inspection statuses.partially_inspectedSome received merchandise still needs inspection.inspection_review_requiredInspected merchandise is waiting for an acceptance decision.disposition_requiredReceived merchandise still needs a successful disposition.resolvedEvery received unit has a successful disposition.exceptionOn the Return only. A current receipt holds unverified or excess merchandise without a successful disposition. Verify it against a line, or disposition it.
Flint recalculates a line's merchandise_status from its quantities after each handoff, receipt, inspection, and disposition. A line skips any status its quantities pass over, and a superseding receipt or inspection can move it back. The Return reports exception while one applies. Otherwise it reports its least-finished line's status, in the order the list above runs from awaiting_handoff to not_required, so a line the buyer keeps never holds the Return back.
Resolution status#
resolution_status on returnnot_selectedApproved quantity has no resolution. An approved line starts here, and returns here when its only proposed resolution is canceled.pendingA resolution is proposed or executing. The resolution's ownstatusisproposeduntil it is confirmed andpendingafter.partially_fulfilledOn the Return only. Some lines' value was delivered and other approved quantity is still unresolved.requires_actionA resolution waits on someone; see itsaction_required_by.fulfilledAll approved value was delivered, or all approved quantity was canceled. Readstatusto tell a canceled Return from a delivered one.failedA resolution failed; see itsfailure_code.
The Return takes the first of these that applies to its lines and unsettled corrections. Fully declined and fully canceled lines don't count as unfinished work.
failedwhen any has failed.requires_actionwhen any is waiting on someone.fulfilledonce all remaining approved value is delivered.partially_fulfilledwhen some lines are fulfilled and other approved quantity is unresolved.pendingwhile a resolution is proposed or executing.not_selectedbefore any is proposed.
Each resolution's own lifecycle is in Return resolutions.
Completion blockers#
completion_blockers is the authoritative list of what is still owed. Each entry names the Return line it belongs to, plus the resolution or receipt holding it up when there is one. Two kinds name no line: an unsettled correction's blocker names only its resolution, and an exception for a unit that matches no line names only its receipt.
code | Cleared by |
|---|---|
decision_pending | Deciding the Return |
handoff_pending | The buyer handing the merchandise off, or a receipt |
receipt_pending | A receipt for the handed-off merchandise |
inspection_pending | Inspecting received merchandise |
inspection_review_required | An acceptance decision on an inspection line |
disposition_required | A successful disposition |
resolution_not_selected | Creating and confirming a resolution |
resolution_pending | The resolution's effects settling |
resolution_requires_action | Whatever the resolution waits on, usually a buyer payment |
resolution_failed | Retrying or replacing the failed resolution |
merchandise_exception | Verifying the unit against a line, or dispositioning it |
Resolution blockers come in two kinds, and one line can carry both:
- Per resolution. Each unfinished resolution on a line adds a blocker with its
return_resolution_id:resolution_not_selectedwhile it is proposed, thenresolution_pending,resolution_requires_action, orresolution_failed. - Uncovered quantity. Approved quantity that no resolution covers adds a
resolution_not_selectedblocker without areturn_resolution_idwhenever the line'savailable_resolution_quantityis above 0.
A line with two approved units and a replacement for one of them reports resolution_pending for the replacement, including while it waits for its Order to be fulfilled, and resolution_not_selected for the other unit.
Under completion_mode: automatic, Flint completes the Return when the last blocker clears. Under manual, you call POST /v1/returns/{return_id}/complete, which refuses while any blocker remains.
Warning: Wait for return.completed, not for the refund
A resolution can finish while merchandise work is still open. Gate downstream work on return.completed or an empty completion_blockers, never on a Refund succeeding. For an exchange or replacement, return.completed also waits for the replacement Order to be fulfilled; see Exchanges and replacements wait for fulfillment.
Line quantities#
Each Return line keeps whole-number counters for each step:
| Counter | Counts |
|---|---|
requested_quantity | Units the request asked to return |
approved_quantity, declined_quantity | Units the decision approved or declined |
canceled_quantity | Approved units canceled later |
return_required_quantity | Approved units the buyer must send back. 0 means the buyer keeps them and the Return still settles the money |
handed_off_quantity, received_quantity | Units the buyer handed off, and units that arrived |
inspected_quantity | Units inspected |
accepted_quantity, rejected_quantity | Inspected units with an acceptance decision either way |
review_required_quantity | Inspected units still waiting for that decision |
dispositioned_quantity | Units with a successful disposition |
resolved_quantity | Units whose resolution is fulfilled |
available_resolution_quantity | Approved units not yet on a resolution |
Units still expected back are return_required_quantity minus received_quantity. A line can disposition up to received_quantity when it needs no inspection, and up to accepted_quantity plus rejected_quantity when it does.
available_resolution_quantity is approved quantity, less canceled quantity and the quantity every resolution that isn't canceled reserves, including failed and fulfilled ones. A failed resolution keeps its quantity until you cancel it, so a retry and a replacement can't both pay out. You can cancel a failed resolution when it never created a Refund, PaymentIntent, or Order; its supported_actions then lists cancel. Canceling an unpaid exchange closes its replacement Order and releases its quantity for a new resolution.
Canceling line quantity and handback#
POST /v1/returns/{return_id}/line-items/{return_line_item_id}/cancel cancels approved quantity on an open Return that nothing has used yet: no unit of it can be handed off, declared on a return shipment, received, inspected, dispositioned, or reserved by a resolution. It takes quantity, the units to cancel, a required reason, and an optional handback_quantity: how many of those units the buyer no longer has to send back, which lowers return_required_quantity. Canceling a line's last approved quantity cancels the Return.
Omit handback_quantity and Flint lowers return_required_quantity only as far as needed, so the buyer is never expected to send back more units than remain approved:
| Approved | return_required_quantity | Cancel | Omitted handback_quantity becomes | return_required_quantity after |
|---|---|---|---|---|
| 3 | 3 | 2 | 2 | 1 |
| 3 | 2 | 1 | 0 | 2 |
| 3 | 0 | 2 | 0 | 0 |
An explicit handback_quantity must stay within three limits:
- Between 0 and
quantity. - No more than
return_required_quantityminusreceived_quantity, since units that arrived can't be handed back. - Low enough that
return_required_quantitydoesn't end up above the remaining approved quantity. In the first row,handback_quantity: 0would still expect 3 units from a line with 1 approved unit left, so it returns400 INVALID_REQUESTwith detailINVALID_VALUEandparam: "handback_quantity". Send a larger value or omit it.
When the quantity, or the handback, is more than the line can give up, the call returns 409 LIMIT_EXCEEDED with param: "quantity", the available_quantity you can still cancel, and the blocking_resources holding the rest.
Money#
Line value#
A Return line's return_value is fixed when the line is created: what the buyer paid for that order line, less what was already refunded or returned. Part of a line is valued the way Refunds values it. The subtotal, discount, and tax are each prorated by quantity and rounded down to the minor unit, and the total is subtotal minus discount plus tax, so the components always add up. The last units of an order line take every remaining minor unit, so all Returns on a line add up to exactly what was paid for it. Resolution lines use the same rule.
A Return refund pays each line from that line's own refundable balance and never moves money onto other order lines. If another refund already returned part of the order line, so less is left than the resolution needs, Flint creates no Refund and the resolution fails with failure_code: refund_line_value_unavailable. Cancel the resolution, then resolve the line for fewer units or without a refund.
Money a Return refund pays beyond its lines' value, such as a goodwill_credit adjustment, is recorded first against order lines that no Return holds, then against lines other Returns hold, and last against the Return's own lines. It reduces what later Returns on those lines can claim.
Financial summary#
financial_summary rolls up the Return's money so you can reconcile without adding up resolutions yourself. The returned_*_money fields sum return_value across the Return's lines. The rest count only resolutions that were confirmed and aren't canceled.
A refund amount moves from due_to_buyer_money to refunded_money when its Refund succeeds, and a balance the buyer owes moves from due_from_buyer_money to collected_money when their payment succeeds. Deductions and credits stay in deduction_money and credit_adjustment_money and are never netted out of refunded_money, so a fee stays visible. A $50.00 return with a $5.00 restocking fee, once refunded, shows 5000 in returned_total_money, 500 in deduction_money, and 4500 in refunded_money.
Amounts shows how each resolution arrives at its refund or balance.
Reading Returns#
Read a whole Return#
A Return lists the IDs of everything recorded against it, oldest first: return_receipt_ids, return_inspection_ids, return_disposition_ids, return_resolution_ids, and shipment_ids. The arrays keep superseded receipts and inspections, failed and canceled dispositions and resolutions, and voided shipments, so each matches what its list route returns for the Return's return_id. Each Return line lists the resolutions that include it in its own return_resolution_ids.
GET /v1/returns/{return_id} expands each array into its objects as return_receipts, return_inspections, return_dispositions, return_resolutions, and shipments, each next to its ID array and in the same order. It also expands order, customer, line_items.fulfillment, and line_items.return_reason.
curl -G https://api.withflintpay.com/v1/returns/ret_01J5Z8N3QK4W7Y2RB6TPVXHC9D \
-H "Authorization: Bearer YOUR_API_KEY" \
--data-urlencode "expand=return_receipts,return_dispositions,return_resolutions"
- Each child expansion returns up to 100 objects. When a Return has more, the read fails with
400 INVALID_REQUEST, detailINVALID_VALUE, andparam: "expand". Page that collection from its list route instead, such asGET /v1/return-dispositions?return_id=ret_01J5Z8N3QK4W7Y2RB6TPVXHC9D. - A shipment expands to its summary. Read
GET /v1/shipments/{shipment_id}for its packages. Expandingshipmentsalso needscommerce.orders.read. - Child expansions work only on this single-Return read with an API key or partner app, not on
GET /v1/returnsor/v1/mereads.
Show order and buyer on a list of Returns#
GET /v1/returns expands order and customer, so a returns desk can show each Return's order number and buyer from one request.
expand | Adds | Also needs |
|---|---|---|
order | The order summary for order_id | commerce.orders.read |
customer | The customer summary for customer_id, or null when the Return has none | customers.read |
A key without a scope an expansion needs gets 403 INSUFFICIENT_SCOPE with param: "expand". Flint expands after filtering and sorting, so the rows, their order, and next_page_token are the same with or without expand. The expanded order is the same summary that GET /v1/returns/{return_id}?expand=order returns.
Read the buyer's email from order.buyer_contact.email. It is the contact the order recorded when payment started, so it is present on guest orders, and it doesn't change when a customer later edits their email. A Return on a guest order has no customer_id, and its customer is null. When the order recorded no email or phone, the summary leaves buyer_contact out.
curl -G https://api.withflintpay.com/v1/returns \
-H "Authorization: Bearer YOUR_API_KEY" \
--data-urlencode "status=requested" \
--data-urlencode "expand=order,customer"
{
"data": [
{
"return_id": "ret_01KEZF7C00VDTZH2NK73DBK2HZ",
"return_number": "R-1001",
"status": "requested",
"order_id": "ord_01KEZF7C00RWKW7JDYTZ5A6ET0",
"order": {
"order_id": "ord_01KEZF7C00RWKW7JDYTZ5A6ET0",
"order_number": "1001",
"status": "open",
"payment_status": "paid",
"refund_status": "none",
"buyer_contact": {
"email": "guest@example.com",
"phone": null,
"is_email_cleared": false,
"is_phone_cleared": false
}
},
"customer": null
}
],
"next_page_token": null
}
The response is abridged. To build a work queue, filter by work_type, and use query for a search box; Build a returns queue shows both. Expand related records covers expansion errors and every list that accepts expand.
What a buyer's read shows#
A buyer reading a Return through a customer session, on /v1/me or in Flint's hosted account, gets a narrower view than a merchant credential:
supported_actionsis["cancel"]while the buyer can withdraw the Return, and empty otherwise. Lines carry no actions.completion_blockerskeeps only what the buyer can clear:handoff_pending,resolution_not_selected,resolution_requires_action, andresolution_failed, plusresolution_pendingwhen the buyer owes a balance the named resolution can collect in checkout.- Merchant-only fields are removed:
customer_id,policy_evaluation,external_reference_id,metadata,completed_by,cancellation_reason_message,canceled_by,completion_reason, andcompletion_reason_message. The buyer still seescancellation_reason. - Of the child ID arrays, only
return_resolution_idsremains, on the Return and on each line.
buyer_actions works the other way: it is filled for a buyer's read and empty for merchant reads and webhooks. Buyer-initiated returns builds a portal on these reads.
Recovery by key#
Recover a Return create whose response never arrived with GET /v1/returns?idempotency_key={key}, or GET /v1/me/returns?idempotency_key={key} with a customer session. Receipts, inspections, and dispositions use their top-level lists, such as GET /v1/return-receipts?return_id={return_id}&idempotency_key={key}. Recovery reads explains the matching rules and what an empty or pending result means.
Return activities#
GET /v1/returns/{return_id}/activities lists what was recorded against a Return: who did it, which resource it touched, the reason they gave, and the Return version it produced. It needs a merchant credential. reason_message can hold staff notes, so customer sessions are refused and there is no /v1/me route.
Activities come newest first. Send sort_direction=asc for chronological order, and keep it unchanged while following next_page_token. The list has no other filters.
| Field | Meaning |
|---|---|
activity_type | What happened, as {resource_type}.{action}, such as return.reopened or return_resolution.retried |
resource_type, resource_id | What it is about: the Return, a line, or a receipt, inspection, disposition, or resolution |
actor | Who acted. actor_type is buyer, merchant, integration, or system, with an actor_id when one exists |
reason, reason_message | The reason and note sent with the action. When Flint records a failed effect, they carry its failure code and message |
quantity | The units canceled, only on return_line_item.quantity_canceled |
return_version | The Return's version after the activity, to line it up with a webhook or a VERSION_CONFLICT |
Activities are history for timelines and audits, not a source of state: read the Return and its records for what is true now. activity_type and reason are extensible, so render a value you don't recognize as a generic row. The Returns guide lists every type and walks through a timeline.
Deciding and processing#
POST /v1/returns/{return_id}/decide records the decision on a requested Return and opens or declines it. POST /v1/returns/{return_id}/process does the same together with receipts, inspections, dispositions, and resolutions, and also records further facts on an open Return.
On a requested Return, both routes need exactly one decision for every requested line, and they record all of them or none. To settle part of a request later, decline that line's quantity, or remove the line with DELETE /v1/returns/{return_id}/line-items/{return_line_item_id} before deciding, then open a separate Return for it.
completion_mode is optional on both routes:
| Return | completion_mode omitted | completion_mode sent |
|---|---|---|
| Requested | The mode every pinned policy that sets one agrees on, or automatic when none sets one. If pinned policies disagree, the request fails with 400 INVALID_REQUEST and param: "completion_mode" | Used as sent, even when pinned policies disagree |
Open (/process only) | Keeps the committed mode | Accepted when it equals the committed mode |
On an open Return, /process treats a line's decision as an assertion about the committed terms, not a new decision. Omit it to keep those terms. When you send it, approved_quantity must equal the committed approved quantity, and every other field you send must equal its committed value; fields you omit aren't compared. automatic_resolution_type: null matches only a line without an automatic outcome.
These routes refuse with 409 ACTION_NOT_ALLOWED:
| Request | details[0].reason | details[0] names | param |
|---|---|---|---|
A requested line is left out of line_items | status_not_reached | The line, with current_status: requested | line_items |
/process sends a requested line without decision | status_not_reached | The line, with current_status: requested | line_items[0].decision, indexed to the line |
/process on an open Return sends a different completion_mode | field_locked | The Return, with current_status: open and its supported_actions | completion_mode |
/process on an open Return sends a decision that differs from the committed terms | field_locked | The line, with its status and supported_actions | line_items[0].decision, indexed to the line |
| An automatic refund can no longer run through the original payment's provider | refund_unavailable | The order, without current_status | line_items[0].automatic_resolution_type on /decide, line_items[0].decision.automatic_resolution_type on /process |
| The original payment can't fund automatic store credit | store_credit_unavailable | The order, without current_status | The same as refund_unavailable |
For refund_unavailable, send automatic_resolution_type: null to resolve the line yourself, or choose no_monetary_action. For store_credit_unavailable, choose refund. /decide on a Return that isn't requested, and /process on one that isn't requested or open, also return 409 ACTION_NOT_ALLOWED, naming the Return and its current_status.
A return_line_item_id that is invalid, sent twice, or from another Return fails with 400 INVALID_REQUEST and param set to line_items[0].return_line_item_id, indexed to the entry.
Writes#
Versions#
Writes that change meaning take an optional expected_version from the resource you last read. It always compares with the resource the route acts on:
/processcompares with the Return'sversion, and only when you send it.- Verifying a receipt line (
POST /v1/return-receipts/{return_receipt_id}/line-items/{return_receipt_line_item_id}/verify) compares with the receipt'sversion, and deciding an inspection line (POST /v1/return-inspections/{return_inspection_id}/line-items/{return_inspection_line_item_id}/decide) with the inspection's. A change to the Return alone doesn't make them stale. - A create that must not commit against a changed Return names the Return's version instead:
expected_return_versiononPOST /v1/returns/{return_id}/resolutions, orresolution.expected_return_versiononPOST /v1/return-previews. Both are optional. DELETE /v1/returns/{return_id}/line-items/{return_line_item_id}takes the Return's version as anexpected_versionquery parameter.- Replacing a resolution's owned arrays requires the resolution's
expected_version; see Return resolutions.
Writes on /v1/returns/{return_id}/line-items return the parent Return, not the line, because a line change can move the Return's statuses and blockers. GET on the same path returns the line itself.
Idempotency#
Idempotency-Key is required on the writes that can move stock or money:
POST /v1/returnsandPOST /v1/me/returns, because an automatic policy can approve and refund the Return.POST /v1/returns/{return_id}/receipts,/inspections, and/dispositions.POST /v1/returns/{return_id}/process.
Other Return writes accept an optional key. Replaying a key returns the original result without repeating inventory or money effects. To find a create whose response you lost, see Recovery by key.
Errors#
- StatusHTTP 409What to do
expected_versionorexpected_return_versionis stale.details[0].current_versionis the current version; for a staleexpected_return_version,paramnames the field you sent anddetails[0]names the Return. Re-read and decide again. Withoutparam, the write lost a race with another write: re-read and retry. - StatusHTTP 409What to doThe state of a resource refuses the action. Branch on
details[0].reason; Refused actions lists each one. - StatusHTTP 409CodeLIMIT_
EXCEEDED What to doA quantity or value is above what remains. A submitted quantity names its indexed field inparam, such asline_items[0].quantitywhen creating a resolution. Receipt verification and resolution creation can also refuse because stored records already use the capacity, and then omitparam: a receipt refusal names the receipt and its status withrequested_quantityandavailable_quantity, and a resolution refusal names the Return and its status withmaximum_moneyfloored at zero. Cancel the conflicting record or this one, then try again.
Refused actions#
ACTION_NOT_ALLOWED names the refusing resource in details[0].resource_type and resource_id. It can be the Return, a line, a receipt or inspection line, a disposition, a resolution, a reason, or a policy, not necessarily the resource in the URL path. details[0] carries its current_status (for a line, the status the line publishes) and, when the resource publishes them, its supported_actions filtered to what your credential's scopes allow. param appears when one request field is refused.
reason | Meaning on Returns resources |
|---|---|
already_applied | A receipt line is already verified, or an inspection line already has its acceptance decision |
terminal_status | The resource is canceled, completed, declined, fulfilled, succeeded, or superseded |
status_not_reached | The resource is requested, unverified, or review_required, and the action needs a later step first |
field_locked | /process on an open Return sent a completion_mode or line decision that differs from the committed one. param names the field |
archived | The reason or policy is archived |
not_offered | A buyer asked for something the policy doesn't offer through self-service, such as a line or resolution type. param names the field |
refund_created | A failed resolution already created a Refund and can't be canceled. remediation.next_actions offers get_refund |
refund_unavailable | The order's payment can no longer be refunded. details[0] names the order and has no current_status |
store_credit_unavailable | The order's payments can't fund store credit; see Store credit |
unsupported_state | Any other state that doesn't allow the action |
remediation.retry is none for every reason, so change the state or the request before you try again. The set of reasons can grow: for one you don't recognize, read the resource named in details[0] and choose from its current_status and supported_actions. Refused actions covers the reasons shared across the API.
Cancellation and completion reasons#
Canceling a Return requires a reason and accepts a reason_message. Flint keeps both on the Return with the actor who canceled it, so you can show why a Return ended without keeping your own record. Completing one by hand records an optional reason the same way.
| Field | Recorded when | Who can read it |
|---|---|---|
cancellation_reason | The Return is canceled | Merchants and buyers |
cancellation_reason_message | The Return is canceled with a reason_message | Merchants |
canceled_by | The Return is canceled | Merchants |
completion_reason | /complete is called with a reason | Merchants |
completion_reason_message | /complete is called with a reason_message | Merchants |
cancellation_reason is buyer_request, merchant_request, duplicate, expired, created_in_error, or other. completion_reason is manual_completion, exception_waived, or other. Both are extensible, so treat a value you don't recognize as other. canceled_by and completed_by are actors with an actor_type of buyer, merchant, integration, or system, and an actor_id when one exists.
A Return canceled by canceling its last approved line quantity records the reason, message, and actor sent with that line cancellation. When Flint completes a Return on its own, completion_reason and completion_reason_message stay absent and completed_by.actor_type is system. Reasons for actions that can repeat, such as reopening, are in the Return's activities.
Resolutions and dispositions keep their own cancellation_reason, cancellation_reason_message, and canceled_by; see Return resolutions and Return dispositions.
Link the buyer to a Return#
When you send your own Return email, POST /v1/returns/{return_id}/access-links creates a url that opens the Return and its order in your Flint-hosted customer account without a sign-in, for 30 days or 10 opens. The url is a bearer credential, returned only in that response and in a retry with the same Idempotency-Key, so send it only to the buyer. Link the buyer to their order covers when Flint sends the email for you.
Webhooks#
An action on the Return itself sends its own event, and every other change sends return.updated:
- return.
created A Return was created, by you, the buyer, or an integration. - return.
decision_ recorded The Return was decided and isopenordeclined. - return.
updated The Return was edited, or one of its lines, receipts, inspections, dispositions, or resolutions changed. - return.
canceled The Return was canceled, with its cancellation reason. - return.
completed Every completion blocker cleared and the Return completed. - return.
reopened A completed Return went back toopen.
A change to a receipt, inspection, disposition, or resolution sends return.updated with the Return, plus that record's own event, such as return_receipt.verified or return_resolution.updated. Canceling, completing, or reopening a Return doesn't also send return.updated, so subscribe to those events directly. Return webhooks leave out supported_actions, because a delivery has no credential to filter them by. The Returns guide suggests a subscription for each kind of integration, and the webhook events catalog has every payload.
Next steps#
Your first returnTake an item back and refund it in sandbox, at the counter or by mail.Receiving and inspectingRecord what arrived, inspect it, and put it back in stock.Return resolutionsRefunds, store credit, exchanges, replacements, and corrections.The Return object#
A request to send purchased items back.
Returned by GET /v1/returns/{return_id} and carried by the endpoints below.
Attributes
buyer_actionsarray of objectRequiredWhat the buyer can do with the return, in this order: withdraw, ship_items, then pay_balance. A buyer's read or change through a customer session on /v1/me, or in Flint's buyer account, lists all three every time; merchant reads and webhooks get an empty list. ship_items is required while handoff_requirements is not empty, due by the earliest expires_at there. pay_balance is required while a resolution waits for the buyer's payment.
cancelobjectPresent only on an available cancel action.
due_atstringWhen the buyer needs to act by. Omitted when the action has no deadline, or when the resource's state or the store's policy doesn't allow it.
is_availablebooleanRequiredWhether this session can take the action now.
is_requiredbooleanRequiredWhether the store needs the buyer to take the action, such as paying a due invoice. It stays true when the only thing in the way is signing in.
kindenumRequiredWhat the action is. Each resource lists its own kinds in a fixed order. New kinds may be added; ignore kinds you don't recognize.
start_returnresend_receiptcancelpauseresumereactivateupdate_payment_methodpaywithdrawship_itemspay_balanceretry_paymentupdate_deliveryskipupdate_billing_intervalupdate_quantityswap_itemsrenew
pauseobjectPresent only on an available pause action.
pay_balanceobjectPresent only on an available pay_balance action.
unavailable_reasonenumWhy the action can't be taken now. Present exactly when is_available is false. New reasons may be added; show a general message for a reason you don't recognize.
sign_in_requiredstore_policynot_in_statewindow_closednothing_to_returncollection_unavailablelimit_reached
canceled_atstringRFC3339 timestamp.
canceled_byobjectWho canceled the Return.
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 Return was canceled.
buyer_requestmerchant_requestduplicateexpiredcreated_in_errorother
cancellation_reason_messagestringDetail sent with the cancellation. Merchant reads only.
Not returned with a customer session
completed_atstringRFC3339 timestamp.
completed_byobjectWho completed the Return. `system` when Flint completed it automatically.
Not returned with a customer session
actor_idstringID of the actor, when one exists. Merchant reads only.
actor_typeenumRequiredWhat kind of actor acted.
buyermerchantintegrationsystem
completion_blockersarray of objectRequiredWhat is still owed before the Return can complete. Empty when nothing is.
codeenumRequiredWhat is still owed before this Return can complete. Each blocker names the Return line it belongs to and, where one exists, the receipt, inspection, disposition, or resolution holding it up. An empty completion_blockers array means nothing is outstanding.
decision_pendinghandoff_pendingreceipt_pendinginspection_pendinginspection_review_requireddisposition_requiredresolution_not_selectedresolution_pendingresolution_requires_actionresolution_failedmerchandise_exception
messagestringRequiredExplanation of what is still owed.
return_disposition_idstringreturn_inspection_idstringreturn_line_item_idstringID of the Return line the entry is about.
return_receipt_idstringID of the receipt holding this blocker up.
return_resolution_idstringID of the resolution holding this blocker up.
shipment_idstringcompletion_modeenumautomatic completes the Return when the last completion blocker clears; manual waits for POST /v1/returns/{return_id}/complete. Reopening a Return sets it to manual.
manualautomatic
completion_reasonenumWhy the Return was completed by hand. Absent when Flint completed it automatically.
Not returned with a customer session
manual_completionexception_waivedother
completion_reason_messagestringDetail sent when the Return was completed by hand.
Not returned with a customer session
created_atstringRequiredRFC3339 timestamp.
customerobject or nullPresent only when `expand` includes `customer`; `null` when expanded and there is no related customer.
Not returned with a customer session
created_atstringRFC3339 timestamp.
customer_idstringRequiredUnique identifier for this customer, prefixed `cus_`.
emailstring or nullRequiredCustomer email. `null` when the customer has none. Unique among the environment's customers.
namestring or nullRequiredCustomer name. `null` when none is set.
phonestring or nullRequiredCustomer phone number. `null` when none is set.
statusenumRequiredWhere the customer is in the deletion lifecycle.
activedeletion_processingdeleted
updated_atstringRFC3339 timestamp.
customer_idstringThe customer the Return belongs to.
Not returned with a customer session
decision_atstringRFC3339 timestamp.
decision_statusenumRequiredWhether the requested units were approved. `pending` until one decision covers every line.
pendingapprovedpartially_approveddeclined
external_reference_idstringCaller-owned identifier for this resource in an external system.
Not returned with a customer session
financial_summaryobjectRequiredThe Return's money in one place: the value of the returned lines, deductions and credits, and what has been refunded or collected.
collected_moneyobjectRequiredBalances collected from the buyer.
credit_adjustment_moneyobjectRequiredCredits added by confirmed, non-canceled resolutions.
deduction_moneyobjectRequiredFees withheld by confirmed, non-canceled resolutions.
due_from_buyer_moneyobjectRequiredBalances the buyer owes on confirmed, non-canceled resolutions whose payment has not succeeded.
due_to_buyer_moneyobjectRequiredRefund amounts on confirmed, non-canceled resolutions whose Refund has not succeeded.
refunded_moneyobjectRequiredRefund amounts that succeeded.
replacement_total_moneyobjectRequiredValue of replacement merchandise on confirmed, non-canceled resolutions.
returned_discount_moneyobjectRequiredSum of return_value.discount_money across the Return's line items.
returned_subtotal_moneyobjectRequiredSum of return_value.subtotal_money across the Return's line items.
returned_tax_moneyobjectRequiredSum of return_value.tax_money across the Return's line items.
returned_total_moneyobjectRequiredSum of return_value.total_money across the Return's line items.
handoff_requirementsarray of objectRequiredWhat the buyer still has to send back and where. Each entry leaves the list once it is satisfied, so an empty list means nothing is waiting on the buyer.
destinationobjectRequiredWhere the buyer sends the merchandise.
expires_atstringRFC3339 timestamp.
instructionsstringInstructions for the buyer on sending the merchandise.
line_itemsarray of objectRequiredReturn lines and the quantities still expected.
shipment_countintegerstatusenumRequiredWhether the buyer has started sending merchandise back. A requirement leaves handoff_requirements entirely once it is satisfied, so there is no terminal status and an empty array means nothing is waiting on the buyer.
pendingin_progress
initiated_byenumRequiredWho created the Return, from the credential that sent the request: buyer for a customer session on /v1/me or Flint's hosted account, merchant for a Dashboard user, integration for an API key or partner app. It cannot be sent.
buyermerchantintegration
line_itemsarray of objectRequiredThe lines being returned.
accepted_quantityintegerRequiredInspected units that were accepted. Whole-number quantity; fractional quantities are not supported.
allowed_resolution_typesarray of enumRequiredResolution types that can settle this line's approved quantity.
refundexchangereplacementno_monetary_actionstore_credit
approved_quantityintegerRequiredUnits the decision approved. Whole-number quantity; fractional quantities are not supported.
automatic_resolution_typeenumThe refund, store_credit, or no_monetary_action resolution Flint creates and confirms automatically. Absent when the merchant resolves manually.
refundstore_creditno_monetary_action
available_resolution_quantityintegerRequiredApproved quantity that can still be assigned to a new resolution. Every non-canceled resolution reserves its line quantity, including proposed, pending, action-required, failed, and fulfilled resolutions. Whole-number quantity; fractional quantities are not supported.
bundle_componentsarray of objectRequiredComponents of the bundle the line was sold from.
bundle_idstringID of the bundle the line was sold from.
buyer_notestringNote the buyer gave about this line. Some return reasons require one.
canceled_quantityintegerRequiredApproved units canceled later. Whole-number quantity; fractional quantities are not supported.
created_atstringRequiredRFC3339 timestamp.
decided_byobjectWho recorded the decision on this line.
decision_atstringRFC3339 timestamp.
decline_reasonenumWhy the line's declined quantity was declined.
not_eligiblequantity_unavailableevidence_missingsuspected_abusemerchant_discretionother
decline_reason_messagestringDetail sent with the decline.
declined_quantityintegerRequiredUnits the decision declined. Whole-number quantity; fractional quantities are not supported.
descriptionstringDescription of the item as sold.
dispositioned_quantityintegerRequiredUnits with a successful disposition. Whole-number quantity; fractional quantities are not supported.
eligibilityobjectRequiredHow the pinned return policy judged this line when the Return was created, with the policy revision it used.
fulfillmentobject or nullPresent only when `expand` includes `line_items.fulfillment`; `null` when expanded and there is no related fulfillment.
Not returned with a customer session
fulfillment_idstringRequiredID of the fulfillment the units were delivered in.
handed_off_quantityintegerRequiredUnits the buyer handed off for the trip back. Whole-number quantity; fractional quantities are not supported.
imageobjectImage of the item as sold.
inspected_quantityintegerRequiredUnits that have been inspected. Whole-number quantity; fractional quantities are not supported.
inspection_waived_atstringRFC3339 timestamp.
inspection_waived_byobjectWho waived inspection for this line.
inspection_waiver_reasonenumWhy inspection was waived for this line.
policy_overridetrusted_in_store_handoffmerchant_reviewother
inspection_waiver_reason_messagestringDetail sent when inspection was waived.
is_inspection_requiredbooleanWhether returned units of this line must be inspected.
is_policy_overriddenbooleanRequiredWhether the decision overrode the pinned return policy's proposal. `override_reason` says why.
merchandise_statusenumRequiredWhere this line's merchandise stands, from handoff through disposition.
not_requiredawaiting_handoffin_transitpartially_receivedinspection_requiredpartially_inspectedinspection_review_requireddisposition_requiredresolved
modifiersarray of objectRequiredModifiers selected on the order line, with their prices.
namestringRequiredName of the item as sold.
order_line_item_idstringRequiredID of the order line item the units come from.
overridden_atstringRFC3339 timestamp.
overridden_byobjectWho recorded the override.
override_reasonenumWhy the decision overrode the pinned return policy's proposal.
customer_service_exceptionpolicy_correctionrisk_reviewmerchant_discretionother
override_reason_messagestringDetail sent with the override.
product_idstringID of the catalog product the item was sold from.
received_quantityintegerRequiredUnits that arrived. Whole-number quantity; fractional quantities are not supported.
receiving_location_idstringID of the Location the buyer sends the merchandise to. Absent when none has to come back.
rejected_quantityintegerRequiredInspected units that were rejected. Whole-number quantity; fractional quantities are not supported.
release_timingenumCommitted resolution execution gate, filled for every approved line: after_inspection when merchandise and inspection are required, after_receipt when merchandise is required without inspection, or after_approval when merchandise is not required, unless the policy or decision sets a timing explicitly. Applies to every resolution type, including exchanges and replacements. manual is held until a merchant calls POST /v1/return-resolutions/{id}/release.
after_approvalafter_handoffafter_receiptafter_inspectionmanual
requested_quantityintegerRequiredUnits the request asked to return. Whole-number quantity; fractional quantities are not supported.
requested_resolution_typeenumOutcome requested for this line when it was created. Absent when none was requested.
refundexchangereplacementno_monetary_actionstore_credit
resolution_statusenumRequiredWhether the value for this line's approved quantity has been delivered.
not_selectedpendingrequires_actionfulfilledfailed
resolved_quantityintegerRequiredUnits whose resolution has finished. Whole-number quantity; fractional quantities are not supported.
return_idstringRequiredID of the Return this line belongs to.
return_line_item_idstringRequiredUnique identifier for this return line item, prefixed `retli_`.
return_reasonobject or nullPresent only when `expand` includes `line_items.return_reason`; `null` when expanded and there is no related return reason.
Not returned with a customer session
return_reason_handlestringRequiredHandle of the chosen reason, captured when the line is created or its reason changes. Later renames, deactivation or archiving don't change it.
return_reason_idstringRequiredID of the reason chosen for this line.
return_reason_namestringRequiredName of the chosen reason, captured when the line is created or its reason changes. Later renames, deactivation or archiving don't change it.
return_required_quantityintegerRequiredHow much of the approved quantity the buyer must physically send back; fractional quantities are not supported. Set 0 for a returnless refund, where the buyer keeps the merchandise and the Return still settles the money.
return_resolution_idsarray of stringRequiredIDs of the resolutions that include this line, oldest first, including failed and canceled resolutions.
return_valueobjectRequiredValue of the line's units, fixed when the line was created: what the buyer paid for them, less what was already refunded or returned.
review_required_quantityintegerRequiredInspected units still waiting for an acceptance decision. Whole-number quantity; fractional quantities are not supported.
selected_optionsarray of objectRequiredVariant options selected for the item, such as size and color.
skustringSKU of the item as sold.
statusenumRequiredWhere this line stands. Same values and meanings as the Return's `status`, applied to the line.
requestedopencompleteddeclinedcanceled
supported_actionsarray of enumRequiredcancelwaive_inspection
updated_atstringRequiredRFC3339 timestamp.
variant_idstringID of the catalog variant the item was sold from.
merchandise_statusenumRequiredOn the Return, the least-finished line's value.
not_requiredawaiting_handoffin_transitpartially_receivedinspection_requiredpartially_inspectedinspection_review_requireddisposition_requiredresolvedexception
metadatamap of stringRequiredStored 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.
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.
order_idstringRequiredID of the Order the Return is against.
policy_evaluationobjectHow your return policies judged the request when the Return was created.
Not returned with a customer session
evaluated_atstringRFC3339 timestamp.
expires_atstringRFC3339 timestamp.
line_itemsarray of objectRequiredEligibility of each line asked about.
reasonenumRequiredWhy the selection got this result.
eligible_under_policymanual_review_requiredreturn_window_expiredquantity_unavailablepolicy_ineligibleresolution_not_allowedreason_not_allowedpolicy_conflictno_matching_policy
reason_messagestringRequiredExplanation of `reason`.
return_policy_idstringID of the policy that judged the lines. Absent when none matched.
return_policy_revision_idstringID of the policy revision that judged the lines. Absent when none matched.
statusenumRequiredOverall result for the selection. `review_required` when the lines differ.
eligibleineligiblereview_required
resolution_statusenumRequiredWhether the buyer has received the value they are owed. Combines the Return's resolutions and its unsettled corrections.
not_selectedpendingpartially_fulfilledrequires_actionfulfilledfailed
return_disposition_idsarray of stringRequiredIDs of every disposition recorded for this Return, oldest first, including failed and canceled dispositions. Expand `return_dispositions` on `GET /v1/returns/{return_id}` to read them inline.
Not returned with a customer session
return_dispositionsarray of objectPresent only when `expand` includes `return_dispositions`. The dispositions in `return_disposition_ids`, in the same order.
Not returned with a customer session
canceled_atstringRFC3339 timestamp.
canceled_byobjectWho canceled the disposition. Merchant reads only.
cancellation_reasonenumWhy the disposition was canceled.
created_in_errorchanged_dispositionduplicateother
cancellation_reason_messagestringDetail sent with the cancellation. Merchant reads only.
created_atstringRequiredRFC3339 timestamp.
created_byobjectRequiredWho created the disposition.
disposition_typeenumRequiredWhat happens to the received units.
sellablequality_controldamagedquarantinedrepairrefurbishliquidatedonatediscardreturn_to_buyerlost
external_reference_idstringCaller-owned identifier for this resource in an external system.
failure_codeenumReason code for a failed merchandise disposition, when available.
inventory_effect_failedinventory_item_unmapped
failure_messagestringExplanation of a failed merchandise disposition, when available.
inventory_location_idstringID of the Location whose stock the disposition changes. Required for `sellable`, `quality_control`, `damaged`, `quarantined`, and `lost`; rejected for the other types.
inventory_movement_idsarray of stringRequiredIDs of the inventory movements the disposition wrote. Empty when it moved no stock.
inventory_receipt_idstringID of the inventory receipt the disposition recorded. Absent when it recorded none.
metadatamap of stringRequiredStored caller-owned key-value data. See `MetadataInput` for key, value, and size rules.
occurred_atstringRequiredRFC3339 timestamp.
quantityintegerRequiredWhole-number quantity; fractional quantities are not supported.
reasonenumRequiredWhy the disposition was made.
inspection_resultreturn_policywarehouse_overridesafety_requirementother
reason_messagestringOptional detail about `reason`, kept with the record.
replaced_by_return_disposition_idstringID of the disposition that took over this one. Present when a replacement canceled it.
replaces_return_disposition_idstringID of the `failed` or `canceled` disposition this one replaces. It takes over that disposition's unused capacity.
return_disposition_idstringRequiredUnique identifier for this return disposition, prefixed `retdsp_`.
return_idstringRequiredreturn_inspection_line_item_idstringID of the inspection line the disposition covers. Absent when it covers a receipt line.
return_line_item_idstringID of the Return line the units belong to.
return_receipt_line_item_idstringID of the receipt line the disposition covers. Absent when it covers an inspection line.
statusenumRequiredWhether inventory has applied the disposition.
pendingsucceededfailedcanceled
supported_actionsarray of enumRequiredActions that can succeed now. Empty unless the parent Return is open. cancel is listed only before the inventory effect starts.
cancelretry
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.
return_idstringRequiredUnique identifier for this return, prefixed `ret_`.
return_inspection_idsarray of stringRequiredIDs of every inspection recorded for this Return, oldest first, including superseded inspections. Expand `return_inspections` on `GET /v1/returns/{return_id}` to read them inline.
Not returned with a customer session
return_inspectionsarray of objectPresent only when `expand` includes `return_inspections`. The inspections in `return_inspection_ids`, in the same order.
Not returned with a customer session
correction_reasonenumWhy this observation replaces an earlier one. Send with `supersedes_return_receipt_id` or `supersedes_return_inspection_id`.
entry_errorduplicate_observationsource_correctionreconciliation_correctionother
correction_reason_messagestringDetail about `correction_reason`.
created_atstringRequiredRFC3339 timestamp.
external_actor_idstringYour identifier for the actor who recorded the event. Don't put secrets in this field.
external_reference_idstringCaller-owned identifier for this resource in an external system.
generated_dispositionsarray of objectRequiredDispositions Flint created when it recorded this observation. Empty unless the policy's `receipt_disposition_mode` is `automatic`.
inspected_atstringRequiredRFC3339 timestamp.
inspection_location_idstringRequiredLocation where the returned merchandise was inspected. Must match the receipt receiving_location_id.
line_itemsarray of objectRequiredThe lines recorded.
return_idstringRequiredID of the Return the goods belong to.
return_inspection_idstringRequiredUnique identifier for this return inspection, prefixed `retins_`.
return_receipt_idstringRequiredID of the receipt being inspected.
source_systemobject or nullRequiredSystem that recorded the observation. `null` when no source system was recorded.
statusenumRequiredWhether this is the current observation of these units or a correction replaced it.
currentsuperseded
superseded_atstringRFC3339 timestamp.
superseded_by_return_inspection_idstringID of the inspection that corrected this one. Absent while it is current.
supersedes_return_inspection_idstringID of the inspection this one corrects.
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.
return_numberstringRequiredHuman-readable number for the Return.
return_receipt_idsarray of stringRequiredIDs of every receipt recorded for this Return, oldest first, including superseded receipts. Expand `return_receipts` on `GET /v1/returns/{return_id}` to read them inline.
Not returned with a customer session
return_receiptsarray of objectPresent only when `expand` includes `return_receipts`. The receipts in `return_receipt_ids`, in the same order.
Not returned with a customer session
correction_reasonenumWhy this observation replaces an earlier one. Send with `supersedes_return_receipt_id` or `supersedes_return_inspection_id`.
entry_errorduplicate_observationsource_correctionreconciliation_correctionother
correction_reason_messagestringDetail about `correction_reason`.
created_atstringRequiredRFC3339 timestamp.
external_actor_idstringYour identifier for the actor who recorded the event. Don't put secrets in this field.
external_reference_idstringCaller-owned identifier for this resource in an external system.
generated_dispositionsarray of objectRequiredDispositions Flint created when it recorded this observation. Empty unless the policy's `receipt_disposition_mode` is `automatic`.
line_itemsarray of objectRequiredThe lines recorded.
received_atstringRequiredRFC3339 timestamp.
receiving_location_idstringRequiredID of the Location that received the goods.
return_idstringRequiredID of the Return the goods belong to.
return_receipt_idstringRequiredUnique identifier for this return receipt, prefixed `retrc_`.
shipment_idstringID of the return shipment the goods arrived in. Absent when the receipt isn't tied to a shipment.
source_systemobject or nullRequiredSystem that recorded the observation. `null` when no source system was recorded.
statusenumRequiredWhether this is the current observation of these units or a correction replaced it.
currentsuperseded
superseded_atstringRFC3339 timestamp.
superseded_by_return_receipt_idstringID of the receipt that corrected this one. Absent while it is current.
supersedes_return_receipt_idstringID of the receipt this one corrects.
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.
return_resolution_idsarray of stringRequiredIDs of every resolution created for this Return, oldest first, including failed and canceled resolutions. Expand `return_resolutions` on `GET /v1/returns/{return_id}` to read them inline.
return_resolutionsarray of objectPresent only when `expand` includes `return_resolutions`. The resolutions in `return_resolution_ids`, in the same order.
Not returned with a customer session
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.
shipment_idsarray of stringRequiredIDs of every shipment raised to send this Return's items back, oldest first, including voided shipments. Expand `shipments` on `GET /v1/returns/{return_id}` to read them inline.
Not returned with a customer session
shipmentsarray of objectPresent only when `expand` includes `shipments`. Summaries of the shipments in `shipment_ids`, in the same order.
Not returned with a customer session
created_atstringWhen the shipment was created, in RFC3339 format.
delivered_atstringWhen the shipment was delivered, in RFC3339 format.
directionenumRequiredWhether the shipment sends items to the buyer or returns items to the merchant.
outboundreturn
fulfillment_idstringRequiredFulfillment associated with this shipment.
handed_off_atstringWhen the carrier accepted the shipment, in RFC3339 format.
package_countintegerRequiredTotal number of packages attached to the shipment, including voided packages.
return_idstringID of the Return this shipment sends back. Present only on return shipments.
shipment_idstringRequiredStable identifier of the expanded shipment.
shipped_atstringWhen the shipment was shipped, in RFC3339 format.
statusenumRequiredRead-only shipment state. - `created`: The shipment leg exists but has not been packed or handed off. - `packed`: The shipment leg is packed and awaiting carrier handoff. - `shipped`: The shipment leg was handed to the carrier. - `in_transit`: The carrier is moving the shipment through its network. - `out_for_delivery`: The shipment is on its final delivery route. - `delivered`: The carrier reported successful delivery. - `delivery_attempted`: The carrier attempted delivery but did not complete it. Follow the carrier instructions before retrying delivery. - `exception`: A carrier exception is blocking normal progress. Resolve the carrier-reported issue. - `returned`: The shipment was returned toward or to its origin. - `voided`: The shipment was voided and will not continue through delivery.
createdpackedshippedin_transitout_for_deliverydelivereddelivery_attemptedexceptionreturnedvoided
updated_atstringWhen the shipment was last updated, in RFC3339 format.
statusenumRequiredWhere the whole Return stands. Read `decision_status`, `merchandise_status`, and `resolution_status` for the part you need.
requestedopencompleteddeclinedcanceled
supported_actionsarray of enumRequiredcancelcompletedecidereopen
updated_atstringRequiredRFC3339 timestamp.
versionintegerRequiredGoes up with every change to the Return. Each activity's `return_version` is the version that activity produced. A write that takes `expected_version` or `expected_return_version` for this Return compares it with this value.
{
"buyer_actions": [],
"completion_blockers": [
{
"code": "decision_pending",
"message": "The requested return is awaiting a decision."
}
],
"completion_mode": "automatic",
"created_at": "2026-09-07T00:00:00Z",
"customer_id": "cus_01KEZF7C00TXZYEK1ATH6C8YWQ",
"decision_status": "pending",
"financial_summary": {
"collected_money": {
"amount": 0,
"currency": "USD"
},
"credit_adjustment_money": {
"amount": 0,
"currency": "USD"
},
"deduction_money": {
"amount": 0,
"currency": "USD"
},
"due_from_buyer_money": {
"amount": 0,
"currency": "USD"
},
"due_to_buyer_money": {
"amount": 0,
"currency": "USD"
},
"refunded_money": {
"amount": 0,
"currency": "USD"
},
"replacement_total_money": {
"amount": 0,
"currency": "USD"
},
"returned_discount_money": {
"amount": 0,
"currency": "USD"
},
"returned_subtotal_money": {
"amount": 5000,
"currency": "USD"
},
"returned_tax_money": {
"amount": 0,
"currency": "USD"
},
"returned_total_money": {
"amount": 5000,
"currency": "USD"
}
},
"handoff_requirements": [],
"initiated_by": "buyer",
"line_items": [
{
"accepted_quantity": 0,
"allowed_resolution_types": [
"refund",
"exchange"
],
"approved_quantity": 0,
"available_resolution_quantity": 0,
"bundle_components": [],
"canceled_quantity": 0,
"created_at": "2026-09-07T00:00:00Z",
"declined_quantity": 0,
"dispositioned_quantity": 0,
"eligibility": {
"allowed_resolution_types": [
"refund",
"exchange"
],
"eligible_quantity": 1,
"policy_adjustment_proposals": [],
"reason": "eligible_under_policy",
"reason_message": "Eligible under the return policy.",
"status": "eligible"
},
"fulfillment_id": "ful_01KEZF7C003HMXBX7F9B69B7AY",
"handed_off_quantity": 0,
"inspected_quantity": 0,
"is_inspection_required": false,
"is_policy_overridden": false,
"merchandise_status": "not_required",
"modifiers": [],
"name": "Linen shirt",
"order_line_item_id": "li_01KEZF7C00XM6VK5KNWVC3T907",
"received_quantity": 0,
"rejected_quantity": 0,
"requested_quantity": 1,
"requested_resolution_type": "exchange",
"resolution_status": "not_selected",
"resolved_quantity": 0,
"return_id": "ret_01KEZF7C00VDTZH2NK73DBK2HZ",
"return_line_item_id": "retli_01KEZF7C001NHF6JPD83VD0MRK",
"return_reason_handle": "changed_mind",
"return_reason_id": "rrsn_01KEZF7C005274REWXTZRJ4BM0",
"return_reason_name": "Changed mind",
"return_required_quantity": 0,
"return_resolution_ids": [],
"return_value": {
"discount_money": {
"amount": 0,
"currency": "USD"
},
"subtotal_money": {
"amount": 5000,
"currency": "USD"
},
"tax_money": {
"amount": 0,
"currency": "USD"
},
"total_money": {
"amount": 5000,
"currency": "USD"
},
"unit_price_money": {
"amount": 5000,
"currency": "USD"
}
},
"review_required_quantity": 0,
"selected_options": [],
"status": "requested",
"supported_actions": [],
"updated_at": "2026-09-07T00:00:00Z"
}
],
"merchandise_status": "not_required",
"metadata": {},
"order_id": "ord_01KEZF7C00RWKW7JDYTZ5A6ET0",
"resolution_status": "not_selected",
"return_disposition_ids": [],
"return_id": "ret_01KEZF7C00VDTZH2NK73DBK2HZ",
"return_inspection_ids": [],
"return_number": "R-1001",
"return_receipt_ids": [],
"return_resolution_ids": [],
"shipment_ids": [],
"status": "requested",
"supported_actions": [
"decide",
"cancel"
],
"updated_at": "2026-09-07T00:00:00Z",
"version": 1
}Create return preview#
/v1/return-previewsRequires 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
Preview return eligibility or resolution amounts without creating a Return or reserving quantity. Set mode to eligibility or resolution and send the matching input object.
Request body
Send exactly one of these
The `eligibility` variant of `CreateReturnPreviewRequest`.
eligibilityobjectRequiredThe eligibility check. Present when `mode` is `eligibility`.
order_idstringRequiredID of the Order to return items from.
selectionone ofRequiredWhich fulfilled units to check.
modeenumRequiredWhich preview to run.
eligibility
The `resolution` variant of `CreateReturnPreviewRequest`.
modeenumRequiredWhich preview to run.
resolution
resolutionone ofRequiredThe priced resolution. Present when `mode` is `resolution`.
Send exactly one of these
The `exchange` variant of `CreateReturnResolutionPreviewRequest`. The `no_monetary_action` variant of `CreateReturnResolutionPreviewRequest`. The `refund` variant of `CreateReturnResolutionPreviewRequest`. The `replacement` variant of `CreateReturnResolutionPreviewRequest`. The `store_credit` variant of `CreateReturnResolutionPreviewRequest`.
adjustmentsarray of objectFees and credits to apply to the resolution, at most 50.
expected_return_versionintegerOptional version of the parent Return. A stale value returns VERSION_CONFLICT with the Return ID and its current version.
line_itemsarray of objectRequiredReturn lines and quantities to cover, up to 100. Not allowed on a correction.
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`.
resolution_typeenumRequiredWhat the buyer gets for the approved quantity.
refundexchangereplacementstore_creditno_monetary_action
return_idstringRequiredID of the Return the resolution is for.
Response · 200
Successful response.
dataone ofRequiredResource, collection, or operation result returned by this request.
One of these shapes
The `eligibility` variant of `CreateReturnPreviewData`.
eligibilityobjectRequiredThe eligibility check. Present when `mode` is `eligibility`.
modeenumRequiredWhich preview to run.
eligibility
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 -X POST https://api.withflintpay.com/v1/return-previews \
-H "Flint-Version: 2026-09-07" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"eligibility": {
"order_id": "ord_01KEZF7C00RWKW7JDYTZ5A6ET0",
"selection": {
"line_items": [
{
"order_line_item_id": "li_01KEZF7C00XM6VK5KNWVC3T907",
"requested_quantity": 1,
"return_reason_id": "rrsn_01KEZF7C005274REWXTZRJ4BM0"
}
],
"selection_type": "line_items"
}
},
"mode": "eligibility"
}'List returns#
/v1/returnsRequires 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 Returns for the merchant, filtered by order, customer, status, decision, merchandise, resolution, or creation window. Filter by idempotency_key to recover a create whose response never arrived. Set sort_direction to asc for oldest first. Default order: created_at descending, then return_id descending.
Query parameters
created_afterstringInclusive lower bound on created_at.
created_beforestringExclusive upper bound on created_at.
customer_idstringFilter by customer id.
decision_statusarray of enumFilter by decision 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.
pendingapprovedpartially_approveddeclined
external_reference_idstringExact-match filter on the caller-owned external reference ID.
idempotency_keystringFilter by the original Idempotency-Key, after trimming surrounding whitespace. Matching is exact and case-sensitive. Returns current authorized resources, not the recorded response. A pending resource does not prove that the operation succeeded, and an empty list does not prove that it had no effect.
merchandise_statusarray of enumFilter by merchandise 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.
not_requiredawaiting_handoffin_transitpartially_receivedinspection_requiredpartially_inspectedinspection_review_requireddisposition_requiredresolvedexception
order_idstringFilter by order 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 ID, return number, external reference ID, the order's number, or the buyer's email.
receiving_location_idstringFilter by receiving location id.
resolution_statusarray of enumFilter by resolution 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.
not_selectedpendingpartially_fulfilledrequires_actionfulfilledfailed
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_numberstringFilter by return number.
return_reason_idstringFilter by return reason id.
sort_byenumField to sort by. Defaults to created_at; ties are broken by return_id.
created_at
sort_directionenumSort direction. Defaults to desc.
ascdesc
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.
requestedopencompleteddeclinedcanceled
updated_afterstringInclusive lower bound on updated_at.
updated_beforestringExclusive upper bound on updated_at.
work_typearray of enumFilter by work type. Matches only returns that are still requested or open. 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.
decisionhandoffreceiptinspectiondispositionresolutionexception
expandarray of enumInclude related objects in the response. Supported expansions: customer, 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.
customerorder
Response · 200
Successful response.
dataarray of objectRequiredResource, collection, or operation result returned by this request.
buyer_actionsarray of objectRequiredWhat the buyer can do with the return, in this order: withdraw, ship_items, then pay_balance. A buyer's read or change through a customer session on /v1/me, or in Flint's buyer account, lists all three every time; merchant reads and webhooks get an empty list. ship_items is required while handoff_requirements is not empty, due by the earliest expires_at there. pay_balance is required while a resolution waits for the buyer's payment.
canceled_atstringRFC3339 timestamp.
canceled_byobjectWho canceled the Return.
Not returned with a customer session
cancellation_reasonenumWhy the Return was canceled.
buyer_requestmerchant_requestduplicateexpiredcreated_in_errorother
cancellation_reason_messagestringDetail sent with the cancellation. Merchant reads only.
Not returned with a customer session
completed_atstringRFC3339 timestamp.
completed_byobjectWho completed the Return. `system` when Flint completed it automatically.
Not returned with a customer session
completion_blockersarray of objectRequiredWhat is still owed before the Return can complete. Empty when nothing is.
completion_modeenumautomatic completes the Return when the last completion blocker clears; manual waits for POST /v1/returns/{return_id}/complete. Reopening a Return sets it to manual.
manualautomatic
completion_reasonenumWhy the Return was completed by hand. Absent when Flint completed it automatically.
Not returned with a customer session
manual_completionexception_waivedother
completion_reason_messagestringDetail sent when the Return was completed by hand.
Not returned with a customer session
created_atstringRequiredRFC3339 timestamp.
customerobject or nullPresent only when `expand` includes `customer`; `null` when expanded and there is no related customer.
Not returned with a customer session
customer_idstringThe customer the Return belongs to.
Not returned with a customer session
decision_atstringRFC3339 timestamp.
decision_statusenumRequiredWhether the requested units were approved. `pending` until one decision covers every line.
pendingapprovedpartially_approveddeclined
external_reference_idstringCaller-owned identifier for this resource in an external system.
Not returned with a customer session
financial_summaryobjectRequiredThe Return's money in one place: the value of the returned lines, deductions and credits, and what has been refunded or collected.
handoff_requirementsarray of objectRequiredWhat the buyer still has to send back and where. Each entry leaves the list once it is satisfied, so an empty list means nothing is waiting on the buyer.
initiated_byenumRequiredWho created the Return, from the credential that sent the request: buyer for a customer session on /v1/me or Flint's hosted account, merchant for a Dashboard user, integration for an API key or partner app. It cannot be sent.
buyermerchantintegration
line_itemsarray of objectRequiredThe lines being returned.
merchandise_statusenumRequiredOn the Return, the least-finished line's value.
not_requiredawaiting_handoffin_transitpartially_receivedinspection_requiredpartially_inspectedinspection_review_requireddisposition_requiredresolvedexception
metadatamap of stringRequiredStored 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.
Not returned with a customer session
order_idstringRequiredID of the Order the Return is against.
policy_evaluationobjectHow your return policies judged the request when the Return was created.
Not returned with a customer session
resolution_statusenumRequiredWhether the buyer has received the value they are owed. Combines the Return's resolutions and its unsettled corrections.
not_selectedpendingpartially_fulfilledrequires_actionfulfilledfailed
return_disposition_idsarray of stringRequiredIDs of every disposition recorded for this Return, oldest first, including failed and canceled dispositions. Expand `return_dispositions` on `GET /v1/returns/{return_id}` to read them inline.
Not returned with a customer session
return_dispositionsarray of objectPresent only when `expand` includes `return_dispositions`. The dispositions in `return_disposition_ids`, in the same order.
Not returned with a customer session
return_idstringRequiredUnique identifier for this return, prefixed `ret_`.
return_inspection_idsarray of stringRequiredIDs of every inspection recorded for this Return, oldest first, including superseded inspections. Expand `return_inspections` on `GET /v1/returns/{return_id}` to read them inline.
Not returned with a customer session
return_inspectionsarray of objectPresent only when `expand` includes `return_inspections`. The inspections in `return_inspection_ids`, in the same order.
Not returned with a customer session
return_numberstringRequiredHuman-readable number for the Return.
return_receipt_idsarray of stringRequiredIDs of every receipt recorded for this Return, oldest first, including superseded receipts. Expand `return_receipts` on `GET /v1/returns/{return_id}` to read them inline.
Not returned with a customer session
return_receiptsarray of objectPresent only when `expand` includes `return_receipts`. The receipts in `return_receipt_ids`, in the same order.
Not returned with a customer session
return_resolution_idsarray of stringRequiredIDs of every resolution created for this Return, oldest first, including failed and canceled resolutions. Expand `return_resolutions` on `GET /v1/returns/{return_id}` to read them inline.
return_resolutionsarray of objectPresent only when `expand` includes `return_resolutions`. The resolutions in `return_resolution_ids`, in the same order.
Not returned with a customer session
shipment_idsarray of stringRequiredIDs of every shipment raised to send this Return's items back, oldest first, including voided shipments. Expand `shipments` on `GET /v1/returns/{return_id}` to read them inline.
Not returned with a customer session
shipmentsarray of objectPresent only when `expand` includes `shipments`. Summaries of the shipments in `shipment_ids`, in the same order.
Not returned with a customer session
statusenumRequiredWhere the whole Return stands. Read `decision_status`, `merchandise_status`, and `resolution_status` for the part you need.
requestedopencompleteddeclinedcanceled
supported_actionsarray of enumRequiredcancelcompletedecidereopen
updated_atstringRequiredRFC3339 timestamp.
versionintegerRequiredGoes up with every change to the Return. Each activity's `return_version` is the version that activity produced. A write that takes `expected_version` or `expected_return_version` for this Return compares it with this value.
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/returns \
-H "Flint-Version: 2026-09-07" \
-H "Authorization: Bearer YOUR_API_KEY"Successful response.
{
"data": [
{
"buyer_actions": [],
"completion_blockers": [
{
"code": "decision_pending",
"message": "The requested return is awaiting a decision."
}
],
"completion_mode": "automatic",
"created_at": "2026-09-07T00:00:00Z",
"customer_id": "cus_01KEZF7C00TXZYEK1ATH6C8YWQ",
"decision_status": "pending",
"financial_summary": {
"collected_money": {
"amount": 0,
"currency": "USD"
},
"credit_adjustment_money": {
"amount": 0,
"currency": "USD"
},
"deduction_money": {
"amount": 0,
"currency": "USD"
},
"due_from_buyer_money": {
"amount": 0,
"currency": "USD"
},
"due_to_buyer_money": {
"amount": 0,
"currency": "USD"
},
"refunded_money": {
"amount": 0,
"currency": "USD"
},
"replacement_total_money": {
"amount": 0,
"currency": "USD"
},
"returned_discount_money": {
"amount": 0,
"currency": "USD"
},
"returned_subtotal_money": {
"amount": 5000,
"currency": "USD"
},
"returned_tax_money": {
"amount": 0,
"currency": "USD"
},
"returned_total_money": {
"amount": 5000,
"currency": "USD"
}
},
"handoff_requirements": [],
"initiated_by": "buyer",
"line_items": [
{
"accepted_quantity": 0,
"allowed_resolution_types": [
"refund",
"exchange"
],
"approved_quantity": 0,
"available_resolution_quantity": 0,
"bundle_components": [],
"canceled_quantity": 0,
"created_at": "2026-09-07T00:00:00Z",
"declined_quantity": 0,
"dispositioned_quantity": 0,
"eligibility": {
"allowed_resolution_types": [
"refund",
"exchange"
],
"eligible_quantity": 1,
"policy_adjustment_proposals": [],
"reason": "eligible_under_policy",
"reason_message": "Eligible under the return policy.",
"status": "eligible"
},
"fulfillment_id": "ful_01KEZF7C003HMXBX7F9B69B7AY",
"handed_off_quantity": 0,
"inspected_quantity": 0,
"is_inspection_required": false,
"is_policy_overridden": false,
"merchandise_status": "not_required",
"modifiers": [],
"name": "Linen shirt",
"order_line_item_id": "li_01KEZF7C00XM6VK5KNWVC3T907",
"received_quantity": 0,
"rejected_quantity": 0,
"requested_quantity": 1,
"requested_resolution_type": "exchange",
"resolution_status": "not_selected",
"resolved_quantity": 0,
"return_id": "ret_01KEZF7C00VDTZH2NK73DBK2HZ",
"return_line_item_id": "retli_01KEZF7C001NHF6JPD83VD0MRK",
"return_reason_handle": "changed_mind",
"return_reason_id": "rrsn_01KEZF7C005274REWXTZRJ4BM0",
"return_reason_name": "Changed mind",
"return_required_quantity": 0,
"return_resolution_ids": [],
"return_value": {
"discount_money": {
"amount": 0,
"currency": "USD"
},
"subtotal_money": {
"amount": 5000,
"currency": "USD"
},
"tax_money": {
"amount": 0,
"currency": "USD"
},
"total_money": {
"amount": 5000,
"currency": "USD"
},
"unit_price_money": {
"amount": 5000,
"currency": "USD"
}
},
"review_required_quantity": 0,
"selected_options": [],
"status": "requested",
"supported_actions": [],
"updated_at": "2026-09-07T00:00:00Z"
}
],
"merchandise_status": "not_required",
"metadata": {},
"order_id": "ord_01KEZF7C00RWKW7JDYTZ5A6ET0",
"resolution_status": "not_selected",
"return_disposition_ids": [],
"return_id": "ret_01KEZF7C00VDTZH2NK73DBK2HZ",
"return_inspection_ids": [],
"return_number": "R-1001",
"return_receipt_ids": [],
"return_resolution_ids": [],
"shipment_ids": [],
"status": "requested",
"supported_actions": [
"decide",
"cancel"
],
"updated_at": "2026-09-07T00:00:00Z",
"version": 1
}
],
"meta": {
"api_version": "2026-09-07"
},
"request_id": "req_01KWM6N9WNGPT5DK4SVYGZXPDS"
}Create return#
/v1/returnsKey requiredRequires scope commerce.returns.write
Rate limit: write
Create a requested Return. Every line needs the return_reason_id of an active reason. With an API key, a Return that no policy matches stays available for merchant review rather than failing creation.
Request body
external_reference_idstringCaller-owned identifier for this resource in an external system.
line_itemsarray of objectRequiredThe lines to check or return, each naming an order line item.
buyer_notestringNote about this line. Some return reasons require one.
fulfillment_idstringID of the fulfillment the units were delivered in.
order_line_item_idstringRequiredID of the order line item being returned.
requested_quantityintegerRequiredWhole-number quantity; fractional quantities are not supported.
requested_resolution_typeenumOutcome requested for this line. Eligibility checks it against the policy's allowed resolution types.
refundexchangereplacementno_monetary_actionstore_credit
return_reason_idstringRequiredID of the return reason for this line. The reason must be active.
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.
order_idstringRequiredID of the Order to return items from.
Response · 201
Successful response.
dataobjectRequiredResource, collection, or operation result returned by this request.
buyer_actionsarray of objectRequiredWhat the buyer can do with the return, in this order: withdraw, ship_items, then pay_balance. A buyer's read or change through a customer session on /v1/me, or in Flint's buyer account, lists all three every time; merchant reads and webhooks get an empty list. ship_items is required while handoff_requirements is not empty, due by the earliest expires_at there. pay_balance is required while a resolution waits for the buyer's payment.
canceled_atstringRFC3339 timestamp.
canceled_byobjectWho canceled the Return.
Not returned with a customer session
cancellation_reasonenumWhy the Return was canceled.
buyer_requestmerchant_requestduplicateexpiredcreated_in_errorother
cancellation_reason_messagestringDetail sent with the cancellation. Merchant reads only.
Not returned with a customer session
completed_atstringRFC3339 timestamp.
completed_byobjectWho completed the Return. `system` when Flint completed it automatically.
Not returned with a customer session
completion_blockersarray of objectRequiredWhat is still owed before the Return can complete. Empty when nothing is.
completion_modeenumautomatic completes the Return when the last completion blocker clears; manual waits for POST /v1/returns/{return_id}/complete. Reopening a Return sets it to manual.
manualautomatic
completion_reasonenumWhy the Return was completed by hand. Absent when Flint completed it automatically.
Not returned with a customer session
manual_completionexception_waivedother
completion_reason_messagestringDetail sent when the Return was completed by hand.
Not returned with a customer session
created_atstringRequiredRFC3339 timestamp.
customerobject or nullPresent only when `expand` includes `customer`; `null` when expanded and there is no related customer.
Not returned with a customer session
customer_idstringThe customer the Return belongs to.
Not returned with a customer session
decision_atstringRFC3339 timestamp.
decision_statusenumRequiredWhether the requested units were approved. `pending` until one decision covers every line.
pendingapprovedpartially_approveddeclined
external_reference_idstringCaller-owned identifier for this resource in an external system.
Not returned with a customer session
financial_summaryobjectRequiredThe Return's money in one place: the value of the returned lines, deductions and credits, and what has been refunded or collected.
handoff_requirementsarray of objectRequiredWhat the buyer still has to send back and where. Each entry leaves the list once it is satisfied, so an empty list means nothing is waiting on the buyer.
initiated_byenumRequiredWho created the Return, from the credential that sent the request: buyer for a customer session on /v1/me or Flint's hosted account, merchant for a Dashboard user, integration for an API key or partner app. It cannot be sent.
buyermerchantintegration
line_itemsarray of objectRequiredThe lines being returned.
merchandise_statusenumRequiredOn the Return, the least-finished line's value.
not_requiredawaiting_handoffin_transitpartially_receivedinspection_requiredpartially_inspectedinspection_review_requireddisposition_requiredresolvedexception
metadatamap of stringRequiredStored 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.
Not returned with a customer session
order_idstringRequiredID of the Order the Return is against.
policy_evaluationobjectHow your return policies judged the request when the Return was created.
Not returned with a customer session
resolution_statusenumRequiredWhether the buyer has received the value they are owed. Combines the Return's resolutions and its unsettled corrections.
not_selectedpendingpartially_fulfilledrequires_actionfulfilledfailed
return_disposition_idsarray of stringRequiredIDs of every disposition recorded for this Return, oldest first, including failed and canceled dispositions. Expand `return_dispositions` on `GET /v1/returns/{return_id}` to read them inline.
Not returned with a customer session
return_dispositionsarray of objectPresent only when `expand` includes `return_dispositions`. The dispositions in `return_disposition_ids`, in the same order.
Not returned with a customer session
return_idstringRequiredUnique identifier for this return, prefixed `ret_`.
return_inspection_idsarray of stringRequiredIDs of every inspection recorded for this Return, oldest first, including superseded inspections. Expand `return_inspections` on `GET /v1/returns/{return_id}` to read them inline.
Not returned with a customer session
return_inspectionsarray of objectPresent only when `expand` includes `return_inspections`. The inspections in `return_inspection_ids`, in the same order.
Not returned with a customer session
return_numberstringRequiredHuman-readable number for the Return.
return_receipt_idsarray of stringRequiredIDs of every receipt recorded for this Return, oldest first, including superseded receipts. Expand `return_receipts` on `GET /v1/returns/{return_id}` to read them inline.
Not returned with a customer session
return_receiptsarray of objectPresent only when `expand` includes `return_receipts`. The receipts in `return_receipt_ids`, in the same order.
Not returned with a customer session
return_resolution_idsarray of stringRequiredIDs of every resolution created for this Return, oldest first, including failed and canceled resolutions. Expand `return_resolutions` on `GET /v1/returns/{return_id}` to read them inline.
return_resolutionsarray of objectPresent only when `expand` includes `return_resolutions`. The resolutions in `return_resolution_ids`, in the same order.
Not returned with a customer session
shipment_idsarray of stringRequiredIDs of every shipment raised to send this Return's items back, oldest first, including voided shipments. Expand `shipments` on `GET /v1/returns/{return_id}` to read them inline.
Not returned with a customer session
shipmentsarray of objectPresent only when `expand` includes `shipments`. Summaries of the shipments in `shipment_ids`, in the same order.
Not returned with a customer session
statusenumRequiredWhere the whole Return stands. Read `decision_status`, `merchandise_status`, and `resolution_status` for the part you need.
requestedopencompleteddeclinedcanceled
supported_actionsarray of enumRequiredcancelcompletedecidereopen
updated_atstringRequiredRFC3339 timestamp.
versionintegerRequiredGoes up with every change to the Return. Each activity's `return_version` is the version that activity produced. A write that takes `expected_version` or `expected_return_version` for this Return compares it with this value.
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 -X POST https://api.withflintpay.com/v1/returns \
-H "Flint-Version: 2026-09-07" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: a-unique-key" \
-d '{
"line_items": [
{
"buyer_note": "I changed my mind.",
"order_line_item_id": "li_01KEZF7C00XM6VK5KNWVC3T907",
"requested_quantity": 1,
"requested_resolution_type": "refund",
"return_reason_id": "rrsn_01KEZF7C005274REWXTZRJ4BM0"
}
],
"order_id": "ord_01KEZF7C00RWKW7JDYTZ5A6ET0"
}'Get return#
/v1/returns/{return_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 a Return with its line items, policy evaluation, financial summary, and completion blockers. Supports expand for the order, customer, receipts, inspections, dispositions, resolutions, shipments, and each line item's reason and fulfillment.
Path parameters
return_idstringRequiredFlint return id.
Query parameters
expandarray of enumInclude related objects in the response. Supported expansions: customer, line_items.fulfillment, line_items.return_reason, order, return_dispositions, return_inspections, return_receipts, return_resolutions, shipments. Expanded relationships are returned only when explicitly requested and authorized. Limits: at most 10 unique expand paths per request. To-many expansions are capped per path: at 100 related objects for return_dispositions, return_inspections, return_receipts, return_resolutions, and shipments; at 20 for line_items.fulfillment and line_items.return_reason.
customerline_items.fulfillmentline_items.return_reasonorderreturn_dispositionsreturn_inspectionsreturn_receiptsreturn_resolutionsshipments
curl https://api.withflintpay.com/v1/returns/ret_01KEZF7C00PG93650ZKVQNGF7X \
-H "Flint-Version: 2026-09-07" \
-H "Authorization: Bearer YOUR_API_KEY"Successful response.
{
"data": {
"buyer_actions": [],
"completion_blockers": [
{
"code": "decision_pending",
"message": "The requested return is awaiting a decision."
}
],
"completion_mode": "automatic",
"created_at": "2026-09-07T00:00:00Z",
"customer_id": "cus_01KEZF7C00TXZYEK1ATH6C8YWQ",
"decision_status": "pending",
"financial_summary": {
"collected_money": {
"amount": 0,
"currency": "USD"
},
"credit_adjustment_money": {
"amount": 0,
"currency": "USD"
},
"deduction_money": {
"amount": 0,
"currency": "USD"
},
"due_from_buyer_money": {
"amount": 0,
"currency": "USD"
},
"due_to_buyer_money": {
"amount": 0,
"currency": "USD"
},
"refunded_money": {
"amount": 0,
"currency": "USD"
},
"replacement_total_money": {
"amount": 0,
"currency": "USD"
},
"returned_discount_money": {
"amount": 0,
"currency": "USD"
},
"returned_subtotal_money": {
"amount": 5000,
"currency": "USD"
},
"returned_tax_money": {
"amount": 0,
"currency": "USD"
},
"returned_total_money": {
"amount": 5000,
"currency": "USD"
}
},
"handoff_requirements": [],
"initiated_by": "buyer",
"line_items": [
{
"accepted_quantity": 0,
"allowed_resolution_types": [
"refund",
"exchange"
],
"approved_quantity": 0,
"available_resolution_quantity": 0,
"bundle_components": [],
"canceled_quantity": 0,
"created_at": "2026-09-07T00:00:00Z",
"declined_quantity": 0,
"dispositioned_quantity": 0,
"eligibility": {
"allowed_resolution_types": [
"refund",
"exchange"
],
"eligible_quantity": 1,
"policy_adjustment_proposals": [],
"reason": "eligible_under_policy",
"reason_message": "Eligible under the return policy.",
"status": "eligible"
},
"fulfillment_id": "ful_01KEZF7C003HMXBX7F9B69B7AY",
"handed_off_quantity": 0,
"inspected_quantity": 0,
"is_inspection_required": false,
"is_policy_overridden": false,
"merchandise_status": "not_required",
"modifiers": [],
"name": "Linen shirt",
"order_line_item_id": "li_01KEZF7C00XM6VK5KNWVC3T907",
"received_quantity": 0,
"rejected_quantity": 0,
"requested_quantity": 1,
"requested_resolution_type": "exchange",
"resolution_status": "not_selected",
"resolved_quantity": 0,
"return_id": "ret_01KEZF7C00VDTZH2NK73DBK2HZ",
"return_line_item_id": "retli_01KEZF7C001NHF6JPD83VD0MRK",
"return_reason_handle": "changed_mind",
"return_reason_id": "rrsn_01KEZF7C005274REWXTZRJ4BM0",
"return_reason_name": "Changed mind",
"return_required_quantity": 0,
"return_resolution_ids": [],
"return_value": {
"discount_money": {
"amount": 0,
"currency": "USD"
},
"subtotal_money": {
"amount": 5000,
"currency": "USD"
},
"tax_money": {
"amount": 0,
"currency": "USD"
},
"total_money": {
"amount": 5000,
"currency": "USD"
},
"unit_price_money": {
"amount": 5000,
"currency": "USD"
}
},
"review_required_quantity": 0,
"selected_options": [],
"status": "requested",
"supported_actions": [],
"updated_at": "2026-09-07T00:00:00Z"
}
],
"merchandise_status": "not_required",
"metadata": {},
"order_id": "ord_01KEZF7C00RWKW7JDYTZ5A6ET0",
"resolution_status": "not_selected",
"return_disposition_ids": [],
"return_id": "ret_01KEZF7C00VDTZH2NK73DBK2HZ",
"return_inspection_ids": [],
"return_number": "R-1001",
"return_receipt_ids": [],
"return_resolution_ids": [],
"shipment_ids": [],
"status": "requested",
"supported_actions": [
"decide",
"cancel"
],
"updated_at": "2026-09-07T00:00:00Z",
"version": 1
},
"meta": {
"api_version": "2026-09-07"
},
"request_id": "req_01KWM6N9WNGPT5DK4SVYGZXPDS"
}Update return#
/v1/returns/{return_id}IdempotentRequires scope commerce.returns.write
Rate limit: write
Update caller-owned fields on a Return. Only external_reference_id and metadata are writable. Send optional expected_version to reject a stale Return version; every other change goes through a decision, operation, or resolution command.
Path parameters
return_idstringRequiredFlint return id.
Request body
expected_versionintegerOptional version of the Return. A stale value returns VERSION_CONFLICT with the current Return version.
external_reference_idstring or nullCaller-owned identifier for this resource in an external system. Send null to clear it.
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.
curl -X PATCH https://api.withflintpay.com/v1/returns/ret_01KEZF7C00PG93650ZKVQNGF7X \
-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,
"metadata": {
"support_case": "1842"
}
}'Create a return access link#
/v1/returns/{return_id}/access-linksIdempotentRequires 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: sensitive_write
Creates the link Flint's email about a Return carries, to put in buyer email or messages you send yourself. It opens the Return and its order in your Flint-hosted customer account without a sign-in. Withdrawing the Return needs the buyer to sign in. It works for 30 days or 10 opens, whichever comes first; after that the buyer signs in to see the Return. The url is a bearer credential. Flint returns it only in this response and in a retry with the same idempotency key, so send it only to the buyer and keep it out of logs. A call with a new key creates another link; earlier links keep working until they expire. When customer_account.mode is merchant_hosted it fails with `ACTION_NOT_ALLOWED` and reason `merchant_hosted_customer_accounts`, and for a Return whose order has no customer, with reason `configuration_required`. Send no request body or an empty object ({}). Idempotency is scoped to the merchant, credential, environment, and this resource's route. A replay returns the original link without extending its lifetime or replenishing its opens. Without an idempotency key, each call creates a new link and has no replay result. If Flint cannot retain a result after minting, contact support with the request ID before sending a new request.
Path parameters
return_idstringRequiredFlint return ID.
Response · 201
The link, what it opens, and when it stops working.
dataobjectRequiredResource, collection, or operation result returned by this request.
expires_atstringRequiredWhen the link stops opening the resource or signing the buyer in.
purposeenumRequiredWhat the link opens and how long it works. New purposes may be added; treat one you don't recognize as opening its resource.
order_viewsubscription_viewsubscription_managereturn_viewcustomer_account
return_urlstring or nullRequiredThe merchant destination supplied when creating a customer or subscription access link. Null when omitted, and always null for order and Return links.
urlstringRequiredThe link to send the buyer. It carries a bearer credential, so anyone with it can open the resource or sign in as the customer, as its purpose describes, until expires_at or until it reaches its open limit. The link uses the merchant's customer account host.
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 -X POST https://api.withflintpay.com/v1/returns/ret_01KEZF7C00PG93650ZKVQNGF7X/access-links \
-H "Flint-Version: 2026-09-07" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: a-unique-key" \
-d '{}'List return activities#
/v1/returns/{return_id}/activitiesRequires 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
Read the merchant history of a Return for timelines and audit. Read the referenced resources for current state. Activities are newest first by default; use sort_direction=asc for chronological order. Default order: created_at descending, then return_activity_id descending.
Path parameters
return_idstringRequiredFlint return id.
Query parameters
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.
sort_directionenumSort direction. Defaults to desc.
ascdesc
Response · 200
Successful response.
dataarray of objectRequiredResource, collection, or operation result returned by this request.
activity_typeenumRequiredWhat happened, as `<resource>.<action>`.
return.canceledreturn.completedreturn.createdreturn.decision_recordedreturn.reopenedreturn.shipment_handoff_convergedreturn.updatedreturn_disposition.canceledreturn_disposition.createdreturn_disposition.failedreturn_disposition.retriedreturn_disposition.succeededreturn_inspection.correctedreturn_inspection.createdreturn_inspection_line_item.acceptance_decidedreturn_line_item.deletedreturn_line_item.inspection_waivedreturn_line_item.line_item_addedreturn_line_item.quantity_canceledreturn_line_item.updatedreturn_receipt.correctedreturn_receipt.createdreturn_receipt_line_item.verifiedreturn_resolution.buyer_payment_requiredreturn_resolution.canceledreturn_resolution.confirmedreturn_resolution.createdreturn_resolution.effect_failedreturn_resolution.payment_failedreturn_resolution.payment_intent_updatedreturn_resolution.payment_succeededreturn_resolution.refund_failedreturn_resolution.refund_succeededreturn_resolution.releasedreturn_resolution.replacement_fulfilledreturn_resolution.replacement_fulfillment_canceledreturn_resolution.replacement_order_createdreturn_resolution.retriedreturn_resolution.updated
actorobjectRequiredWho took the action.
created_atstringRequiredRFC3339 timestamp.
quantityintegerCanceled whole-number quantity; fractional quantities are not supported. Present only for return_line_item.quantity_canceled.
reasonenumThe reason given for the action. When Flint records a failed effect, the failure code, such as `refund_creation_failed`.
additional_merchandise_receivedautomatic_receiptbuyer_paymentbuyer_requestbuyer_selectionchanged_dispositioncorrection_requiredcreated_in_errorcustomer_servicecustomer_service_exceptiondependency_recoveredduplicateduplicate_observationentry_errorevidence_missingexception_resolvedexception_waivedexpiredinspection_confirmedinspection_resultinventory_effect_failedinventory_item_unmappedlinked_effect_changedlinked_effect_retrymanual_completionmanual_correctionmanual_releasemanual_reviewmapping_correctedmerchant_approvedmerchant_discretionmerchant_requestmerchant_reviewnot_eligibleoperator_retryorder_match_confirmedotherpayment_intent_creation_failedpayment_method_updatedpolicy_correctionpolicy_overridequantity_unavailablereconciliation_correctionrefund_creation_failedrefund_line_value_unavailablereplacement_order_creation_failedresolution_effect_failedreturn_policyreturn_shipping_costrisk_reviewsafety_requirementsku_match_confirmedsource_correctionsuspected_abusetrusted_in_store_handoffwarehouse_override
reason_messagestringFree text given with the reason, or the failure message for a failed effect. Can hold staff notes, so only merchant credentials can read it.
resource_idstringRequiredThe ID of the Return or child resource the activity touched, whose type is `resource_type`.
resource_typeenumRequiredType of the resource that changed: the part of `activity_type` before the dot.
api_keyapi_request_logbalancebalance_transactionbundlebundle_componentcategorycheckout_sessioncheckout_session_customer_verificationcredit_notecredit_note_allocationcustom_domaincustomercustomer_addresscustomer_deletion_requestcustomer_email_preferencescustomer_sessioncustomer_verificationdelivery_location_setdelivery_methoddelivery_profiledelivery_quotedelivery_ratedelivery_rate_callbackdelivery_revocationdelivery_selectiondelivery_zonedemo_sessiondevicediscountdisputeemail_change_requestenvironment_grantfeedback_reportfileflint_walletflint_wallet_cardfraud_warningfulfillmentfulfillment_eventfulfillment_notificationgift_cardgift_card_funding_dispositiongift_card_loadgift_card_notificationgift_card_redemptiongift_card_transactionimageinventory_adjustmentinventory_allocation_policyinventory_allocation_policy_revisioninventory_countinventory_iteminventory_levelinventory_movementinventory_receiptinventory_reservationinventory_reservation_lineinventory_transferinventory_transfer_lineinvoiceinvoice_delivery_attemptinvoice_late_feeinvoice_line_iteminvoice_manual_paymentinvoice_payment_attemptinvoice_payment_termlocationmerchantmerchant_billing_balancemerchant_billing_entrymerchant_billing_invoicemodifiermodifier_groupmodifier_setorderorder_chargeorder_line_itemorder_line_item_modifierorder_payment_attemptorganizationpackagepackage_itempartner_apppartner_app_credentialpartner_app_installpayment_intentpayment_linkpayment_link_custom_fieldpayment_link_line_itempayment_methodpayment_method_domainpayment_reviewpayoutpayout_destinationpayout_settingsproductproduct_optionproduct_option_valueproduct_variantpromotionpromotion_codepurchase_refund_allocationrefundrefund_allocationrefund_line_item_adjustmentreportreport_downloadreturnreturn_activityreturn_dispositionreturn_inspectionreturn_inspection_line_itemreturn_line_itemreturn_policyreturn_policy_revisionreturn_reasonreturn_receiptreturn_receipt_line_itemreturn_resolutionrisk_listrisk_list_itemrisk_rulesandboxsettingsshipmentsubscriptionsubscription_delivery_migrationsubscription_line_itemsubscription_offersubscription_payment_retrysubscription_plansubscription_plan_line_itemtax_connectiontax_registrationtest_clockuserwebhook_deliverywebhook_endpointwebhook_eventworkload_identity
return_activity_idstringRequiredStable identifier of the activity.
return_idstringRequiredThe Return this activity belongs to.
return_versionintegerRequiredReturn version produced by this activity.
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/returns/ret_01KEZF7C00PG93650ZKVQNGF7X/activities \
-H "Flint-Version: 2026-09-07" \
-H "Authorization: Bearer YOUR_API_KEY"Successful response.
{
"data": [
{
"activity_type": "return.created",
"actor": {
"actor_type": "integration"
},
"created_at": "2026-09-07T00:00:00Z",
"resource_id": "ret_01KEZF7C00VDTZH2NK73DBK2HZ",
"resource_type": "return",
"return_activity_id": "retact_01KEZF7C00J26XVS5GK98PQ39D",
"return_id": "ret_01KEZF7C00VDTZH2NK73DBK2HZ",
"return_version": 1
}
],
"meta": {
"api_version": "2026-09-07"
},
"request_id": "req_01KWM6WAHG3N9Q8T2V5XRZ7C4D"
}Cancel return#
/v1/returns/{return_id}/cancelIdempotentRequires scope commerce.returns.write
Rate limit: write
Cancel a Return before any merchandise or value work commits. Cancellation is refused once a receipt, inspection, disposition, or resolution exists.
Path parameters
return_idstringRequiredFlint return 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/returns/ret_01KEZF7C00PG93650ZKVQNGF7X/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"
}'Complete return#
/v1/returns/{return_id}/completeIdempotentRequires scope commerce.returns.write
Rate limit: write
Complete a Return whose completion_mode is manual. The call fails while completion_blockers is non-empty. Automatic Returns complete themselves when the final blocker clears.
Path parameters
return_idstringRequiredFlint return 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.
reasonenumWhy you are completing the Return by hand.
manual_completionexception_waivedother
reason_messagestringOptional detail about `reason`, kept with the record.
curl -X POST https://api.withflintpay.com/v1/returns/ret_01KEZF7C00PG93650ZKVQNGF7X/complete \
-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": 4,
"reason": "manual_completion"
}'Decide return#
/v1/returns/{return_id}/decideIdempotentRequires scope commerce.returns.write
Rate limit: write
Record one decision for every requested line atomically, then open the Return. To defer a line, decline its quantity or remove it with DELETE /v1/returns/{return_id}/line-items/{return_line_item_id} and open a separate Return for it. Omit completion_mode to use the shared pinned policy mode, or automatic when none sets a mode; disagreeing policies require an explicit completion_mode. completion_blockers reports uncovered approved quantity as resolution_not_selected alongside blockers for unfinished resolutions. Start from each buildable pinned policy proposal or the no-policy defaults, replace every supplied decision field, fill release_timing, and validate the result. When an automatic refund can no longer run through the original payment's provider, the request fails with `ACTION_NOT_ALLOWED`; send automatic_resolution_type as null to resolve manually, or choose no_monetary_action.
Path parameters
return_idstringRequiredFlint return id.
Request body
completion_modeenumOmit to use the mode shared by all pinned policies that set completion_mode, or automatic when no pinned policy sets one. Conflicting pinned policy modes return 400 naming completion_mode only when completion_mode is omitted. An explicit manual or automatic value is used as sent.
manualautomatic
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.
line_itemsarray of objectRequiredOne decision for each line.
allowed_resolution_typesarray of enumOptional replacement for the entire starting list. Defaults to the buildable pinned policy proposal; otherwise refund, exchange, replacement, no_monetary_action, and store_credit in that order, independent of the original payment's refundability. The resulting list must be valid and non-empty when approved_quantity is above zero.
refundexchangereplacementno_monetary_actionstore_credit
approved_quantityintegerRequiredRequired whole-number quantity from zero through the line's requested_quantity; fractional quantities are not supported. When approved_quantity is below requested_quantity, send decline_reason; decline_reason_message is optional. Both decline fields are forbidden when all requested quantity is approved.
automatic_resolution_typeenum or nullOptional refund, store_credit, or no_monetary_action that Flint creates and confirms automatically. Omit to keep the policy proposal's value, or the absent value from no-policy defaults. Send null to resolve the line manually; clearing a policy proposal's automatic value requires override_reason. Must be in the resulting allowed_resolution_types. Exchange and replacement cannot be automated. An unavailable automatic refund or store credit fails with 409 ACTION_NOT_ALLOWED and reason refund_unavailable or store_credit_unavailable.
refundstore_creditno_monetary_actionnull
decline_reasonenumWhy the line's declined quantity is declined.
not_eligiblequantity_unavailableevidence_missingsuspected_abusemerchant_discretionother
decline_reason_messagestringOptional explanation accompanying decline_reason, up to 2048 characters (Unicode code points), counted before normalization. Requires decline_reason and is forbidden when all requested quantity is approved.
is_inspection_requiredbooleanOptional inspection requirement. Defaults to the buildable pinned policy proposal or false when no proposal can be built. The resulting requirement must be reachable with the merged merchandise quantity and release timing.
override_reasonenumRequired when a decision differs from a buildable pinned policy proposal. With a pinned policy, also required whenever approved_quantity exceeds evaluated eligible_quantity, even when no proposal can be built. The release timing fill also applies to the proposal and does not count as a deviation. Otherwise optional when a pinned policy proposal cannot be built or no deviation exists. Forbidden without a pinned policy.
customer_service_exceptionpolicy_correctionrisk_reviewmerchant_discretionother
override_reason_messagestringOptional explanation accompanying override_reason. Requires override_reason and is forbidden without a pinned policy.
receiving_location_idstringOptional receiving Location with a postal address. Defaults to the buildable pinned policy proposal or no location when no proposal can be built. Required when the resulting return_required_quantity is above zero and there is no starting location. A process receipt does not supply the decision's location.
release_timingenumOptional gate for every resolution type. Defaults to the policy proposal's timing when set. After merging supplied fields, an unset timing becomes after_inspection when return_required_quantity is above zero and inspection is required, after_receipt when return_required_quantity is above zero without inspection, or after_approval when return_required_quantity is zero. Applies to every resolution type, including exchanges and replacements. manual is held until a merchant calls POST /v1/return-resolutions/{id}/release.
after_approvalafter_handoffafter_receiptafter_inspectionmanual
return_line_item_idstringRequiredID of the Return line to act on.
return_required_quantityintegerHow much of the approved quantity the buyer must physically send back; fractional quantities are not supported. Set 0 for a returnless refund, where the buyer keeps the merchandise and the Return still settles the money.
curl -X POST https://api.withflintpay.com/v1/returns/ret_01KEZF7C00PG93650ZKVQNGF7X/decide \
-H "Flint-Version: 2026-09-07" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: a-unique-key" \
-d '{
"line_items": [
{
"approved_quantity": 1,
"receiving_location_id": "loc_01KEZF7C005QW6QDMVP0P473FZ",
"return_line_item_id": "retli_01KEZF7C001NHF6JPD83VD0MRK"
}
]
}'List return line items#
/v1/returns/{return_id}/line-itemsRequires 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 the line items on a Return with their quantity counters, eligibility, frozen display identity, and return value. Default order: created_at descending, then return_line_item_id descending.
Path parameters
return_idstringRequiredFlint return id.
Query parameters
fulfillment_idstringFilter by fulfillment id.
merchandise_statusarray of enumFilter by merchandise 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.
not_requiredawaiting_handoffin_transitpartially_receivedinspection_requiredpartially_inspectedinspection_review_requireddisposition_requiredresolvedexception
order_line_item_idstringFilter by order line item 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.
resolution_statusarray of enumFilter by resolution 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.
not_selectedpendingrequires_actionfulfilledfailed
return_reason_idstringFilter by return reason 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.
requestedopencompleteddeclinedcanceled
Response · 200
Successful response.
dataarray of objectRequiredResource, collection, or operation result returned by this request.
accepted_quantityintegerRequiredInspected units that were accepted. Whole-number quantity; fractional quantities are not supported.
allowed_resolution_typesarray of enumRequiredResolution types that can settle this line's approved quantity.
refundexchangereplacementno_monetary_actionstore_credit
approved_quantityintegerRequiredUnits the decision approved. Whole-number quantity; fractional quantities are not supported.
automatic_resolution_typeenumThe refund, store_credit, or no_monetary_action resolution Flint creates and confirms automatically. Absent when the merchant resolves manually.
refundstore_creditno_monetary_action
available_resolution_quantityintegerRequiredApproved quantity that can still be assigned to a new resolution. Every non-canceled resolution reserves its line quantity, including proposed, pending, action-required, failed, and fulfilled resolutions. Whole-number quantity; fractional quantities are not supported.
bundle_componentsarray of objectRequiredComponents of the bundle the line was sold from.
bundle_idstringID of the bundle the line was sold from.
buyer_notestringNote the buyer gave about this line. Some return reasons require one.
canceled_quantityintegerRequiredApproved units canceled later. Whole-number quantity; fractional quantities are not supported.
created_atstringRequiredRFC3339 timestamp.
decided_byobjectWho recorded the decision on this line.
decision_atstringRFC3339 timestamp.
decline_reasonenumWhy the line's declined quantity was declined.
not_eligiblequantity_unavailableevidence_missingsuspected_abusemerchant_discretionother
decline_reason_messagestringDetail sent with the decline.
declined_quantityintegerRequiredUnits the decision declined. Whole-number quantity; fractional quantities are not supported.
descriptionstringDescription of the item as sold.
dispositioned_quantityintegerRequiredUnits with a successful disposition. Whole-number quantity; fractional quantities are not supported.
eligibilityobjectRequiredHow the pinned return policy judged this line when the Return was created, with the policy revision it used.
fulfillmentobject or nullPresent only when `expand` includes `line_items.fulfillment`; `null` when expanded and there is no related fulfillment.
Not returned with a customer session
fulfillment_idstringRequiredID of the fulfillment the units were delivered in.
handed_off_quantityintegerRequiredUnits the buyer handed off for the trip back. Whole-number quantity; fractional quantities are not supported.
imageobjectImage of the item as sold.
inspected_quantityintegerRequiredUnits that have been inspected. Whole-number quantity; fractional quantities are not supported.
inspection_waived_atstringRFC3339 timestamp.
inspection_waived_byobjectWho waived inspection for this line.
inspection_waiver_reasonenumWhy inspection was waived for this line.
policy_overridetrusted_in_store_handoffmerchant_reviewother
inspection_waiver_reason_messagestringDetail sent when inspection was waived.
is_inspection_requiredbooleanWhether returned units of this line must be inspected.
is_policy_overriddenbooleanRequiredWhether the decision overrode the pinned return policy's proposal. `override_reason` says why.
merchandise_statusenumRequiredWhere this line's merchandise stands, from handoff through disposition.
not_requiredawaiting_handoffin_transitpartially_receivedinspection_requiredpartially_inspectedinspection_review_requireddisposition_requiredresolved
modifiersarray of objectRequiredModifiers selected on the order line, with their prices.
namestringRequiredName of the item as sold.
order_line_item_idstringRequiredID of the order line item the units come from.
overridden_atstringRFC3339 timestamp.
overridden_byobjectWho recorded the override.
override_reasonenumWhy the decision overrode the pinned return policy's proposal.
customer_service_exceptionpolicy_correctionrisk_reviewmerchant_discretionother
override_reason_messagestringDetail sent with the override.
product_idstringID of the catalog product the item was sold from.
received_quantityintegerRequiredUnits that arrived. Whole-number quantity; fractional quantities are not supported.
receiving_location_idstringID of the Location the buyer sends the merchandise to. Absent when none has to come back.
rejected_quantityintegerRequiredInspected units that were rejected. Whole-number quantity; fractional quantities are not supported.
release_timingenumCommitted resolution execution gate, filled for every approved line: after_inspection when merchandise and inspection are required, after_receipt when merchandise is required without inspection, or after_approval when merchandise is not required, unless the policy or decision sets a timing explicitly. Applies to every resolution type, including exchanges and replacements. manual is held until a merchant calls POST /v1/return-resolutions/{id}/release.
after_approvalafter_handoffafter_receiptafter_inspectionmanual
requested_quantityintegerRequiredUnits the request asked to return. Whole-number quantity; fractional quantities are not supported.
requested_resolution_typeenumOutcome requested for this line when it was created. Absent when none was requested.
refundexchangereplacementno_monetary_actionstore_credit
resolution_statusenumRequiredWhether the value for this line's approved quantity has been delivered.
not_selectedpendingrequires_actionfulfilledfailed
resolved_quantityintegerRequiredUnits whose resolution has finished. Whole-number quantity; fractional quantities are not supported.
return_idstringRequiredID of the Return this line belongs to.
return_line_item_idstringRequiredUnique identifier for this return line item, prefixed `retli_`.
return_reasonobject or nullPresent only when `expand` includes `line_items.return_reason`; `null` when expanded and there is no related return reason.
Not returned with a customer session
return_reason_handlestringRequiredHandle of the chosen reason, captured when the line is created or its reason changes. Later renames, deactivation or archiving don't change it.
return_reason_idstringRequiredID of the reason chosen for this line.
return_reason_namestringRequiredName of the chosen reason, captured when the line is created or its reason changes. Later renames, deactivation or archiving don't change it.
return_required_quantityintegerRequiredHow much of the approved quantity the buyer must physically send back; fractional quantities are not supported. Set 0 for a returnless refund, where the buyer keeps the merchandise and the Return still settles the money.
return_resolution_idsarray of stringRequiredIDs of the resolutions that include this line, oldest first, including failed and canceled resolutions.
return_valueobjectRequiredValue of the line's units, fixed when the line was created: what the buyer paid for them, less what was already refunded or returned.
review_required_quantityintegerRequiredInspected units still waiting for an acceptance decision. Whole-number quantity; fractional quantities are not supported.
selected_optionsarray of objectRequiredVariant options selected for the item, such as size and color.
skustringSKU of the item as sold.
statusenumRequiredWhere this line stands. Same values and meanings as the Return's `status`, applied to the line.
requestedopencompleteddeclinedcanceled
supported_actionsarray of enumRequiredcancelwaive_inspection
updated_atstringRequiredRFC3339 timestamp.
variant_idstringID of the catalog variant the item was sold from.
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/returns/ret_01KEZF7C00PG93650ZKVQNGF7X/line-items \
-H "Flint-Version: 2026-09-07" \
-H "Authorization: Bearer YOUR_API_KEY"Successful response.
{
"data": [
{
"accepted_quantity": 0,
"allowed_resolution_types": [
"refund",
"exchange"
],
"approved_quantity": 0,
"available_resolution_quantity": 0,
"bundle_components": [],
"buyer_note": "I changed my mind.",
"canceled_quantity": 0,
"created_at": "2026-09-07T00:00:00Z",
"declined_quantity": 0,
"dispositioned_quantity": 0,
"eligibility": {
"allowed_resolution_types": [
"refund",
"exchange"
],
"eligible_quantity": 1,
"policy_adjustment_proposals": [],
"reason": "eligible_under_policy",
"reason_message": "Eligible under the return policy.",
"status": "eligible"
},
"fulfillment_id": "ful_01KEZF7C003HMXBX7F9B69B7AY",
"handed_off_quantity": 0,
"inspected_quantity": 0,
"is_inspection_required": false,
"is_policy_overridden": false,
"merchandise_status": "not_required",
"modifiers": [],
"name": "Linen shirt",
"order_line_item_id": "li_01KEZF7C00XM6VK5KNWVC3T907",
"received_quantity": 0,
"rejected_quantity": 0,
"requested_quantity": 1,
"requested_resolution_type": "refund",
"resolution_status": "not_selected",
"resolved_quantity": 0,
"return_id": "ret_01KEZF7C00VDTZH2NK73DBK2HZ",
"return_line_item_id": "retli_01KEZF7C001NHF6JPD83VD0MRK",
"return_reason_handle": "changed_mind",
"return_reason_id": "rrsn_01KEZF7C005274REWXTZRJ4BM0",
"return_reason_name": "Changed mind",
"return_required_quantity": 0,
"return_resolution_ids": [],
"return_value": {
"discount_money": {
"amount": 0,
"currency": "USD"
},
"subtotal_money": {
"amount": 5000,
"currency": "USD"
},
"tax_money": {
"amount": 0,
"currency": "USD"
},
"total_money": {
"amount": 5000,
"currency": "USD"
},
"unit_price_money": {
"amount": 5000,
"currency": "USD"
}
},
"review_required_quantity": 0,
"selected_options": [],
"status": "requested",
"supported_actions": [],
"updated_at": "2026-09-07T00:00:00Z"
}
],
"meta": {
"api_version": "2026-09-07"
},
"request_id": "req_01KWM6WAHG3N9Q8T2V5XRZ7C4D"
}Add return line item#
/v1/returns/{return_id}/line-itemsIdempotentRequires scope commerce.returns.write
Rate limit: write
Add a line item to a requested Return. The response is the updated Return, not the new line.
Path parameters
return_idstringRequiredFlint return 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.
line_itemobjectRequiredThe line to add.
buyer_notestringNote about this line. Some return reasons require one.
fulfillment_idstringID of the fulfillment the units were delivered in.
order_line_item_idstringRequiredID of the order line item being returned.
requested_quantityintegerRequiredWhole-number quantity; fractional quantities are not supported.
requested_resolution_typeenumOutcome requested for this line. Eligibility checks it against the policy's allowed resolution types.
refundexchangereplacementno_monetary_actionstore_credit
return_reason_idstringRequiredID of the return reason for this line. The reason must be active.
curl -X POST https://api.withflintpay.com/v1/returns/ret_01KEZF7C00PG93650ZKVQNGF7X/line-items \
-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_item": {
"buyer_note": "I changed my mind.",
"order_line_item_id": "li_01KEZF7C00XM6VK5KNWVC3T907",
"requested_quantity": 1,
"requested_resolution_type": "refund",
"return_reason_id": "rrsn_01KEZF7C005274REWXTZRJ4BM0"
}
}'Get return line item#
/v1/returns/{return_id}/line-items/{return_line_item_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 Return line item, including its quantity counters and the reason the buyer selected.
Path parameters
return_idstringRequiredFlint return id.
return_line_item_idstringRequiredFlint return line item id.
Response · 200
Successful response.
dataobjectRequiredResource, collection, or operation result returned by this request.
accepted_quantityintegerRequiredInspected units that were accepted. Whole-number quantity; fractional quantities are not supported.
allowed_resolution_typesarray of enumRequiredResolution types that can settle this line's approved quantity.
refundexchangereplacementno_monetary_actionstore_credit
approved_quantityintegerRequiredUnits the decision approved. Whole-number quantity; fractional quantities are not supported.
automatic_resolution_typeenumThe refund, store_credit, or no_monetary_action resolution Flint creates and confirms automatically. Absent when the merchant resolves manually.
refundstore_creditno_monetary_action
available_resolution_quantityintegerRequiredApproved quantity that can still be assigned to a new resolution. Every non-canceled resolution reserves its line quantity, including proposed, pending, action-required, failed, and fulfilled resolutions. Whole-number quantity; fractional quantities are not supported.
bundle_componentsarray of objectRequiredComponents of the bundle the line was sold from.
bundle_idstringID of the bundle the line was sold from.
buyer_notestringNote the buyer gave about this line. Some return reasons require one.
canceled_quantityintegerRequiredApproved units canceled later. Whole-number quantity; fractional quantities are not supported.
created_atstringRequiredRFC3339 timestamp.
decided_byobjectWho recorded the decision on this line.
decision_atstringRFC3339 timestamp.
decline_reasonenumWhy the line's declined quantity was declined.
not_eligiblequantity_unavailableevidence_missingsuspected_abusemerchant_discretionother
decline_reason_messagestringDetail sent with the decline.
declined_quantityintegerRequiredUnits the decision declined. Whole-number quantity; fractional quantities are not supported.
descriptionstringDescription of the item as sold.
dispositioned_quantityintegerRequiredUnits with a successful disposition. Whole-number quantity; fractional quantities are not supported.
eligibilityobjectRequiredHow the pinned return policy judged this line when the Return was created, with the policy revision it used.
fulfillmentobject or nullPresent only when `expand` includes `line_items.fulfillment`; `null` when expanded and there is no related fulfillment.
Not returned with a customer session
fulfillment_idstringRequiredID of the fulfillment the units were delivered in.
handed_off_quantityintegerRequiredUnits the buyer handed off for the trip back. Whole-number quantity; fractional quantities are not supported.
imageobjectImage of the item as sold.
inspected_quantityintegerRequiredUnits that have been inspected. Whole-number quantity; fractional quantities are not supported.
inspection_waived_atstringRFC3339 timestamp.
inspection_waived_byobjectWho waived inspection for this line.
inspection_waiver_reasonenumWhy inspection was waived for this line.
policy_overridetrusted_in_store_handoffmerchant_reviewother
inspection_waiver_reason_messagestringDetail sent when inspection was waived.
is_inspection_requiredbooleanWhether returned units of this line must be inspected.
is_policy_overriddenbooleanRequiredWhether the decision overrode the pinned return policy's proposal. `override_reason` says why.
merchandise_statusenumRequiredWhere this line's merchandise stands, from handoff through disposition.
not_requiredawaiting_handoffin_transitpartially_receivedinspection_requiredpartially_inspectedinspection_review_requireddisposition_requiredresolved
modifiersarray of objectRequiredModifiers selected on the order line, with their prices.
namestringRequiredName of the item as sold.
order_line_item_idstringRequiredID of the order line item the units come from.
overridden_atstringRFC3339 timestamp.
overridden_byobjectWho recorded the override.
override_reasonenumWhy the decision overrode the pinned return policy's proposal.
customer_service_exceptionpolicy_correctionrisk_reviewmerchant_discretionother
override_reason_messagestringDetail sent with the override.
product_idstringID of the catalog product the item was sold from.
received_quantityintegerRequiredUnits that arrived. Whole-number quantity; fractional quantities are not supported.
receiving_location_idstringID of the Location the buyer sends the merchandise to. Absent when none has to come back.
rejected_quantityintegerRequiredInspected units that were rejected. Whole-number quantity; fractional quantities are not supported.
release_timingenumCommitted resolution execution gate, filled for every approved line: after_inspection when merchandise and inspection are required, after_receipt when merchandise is required without inspection, or after_approval when merchandise is not required, unless the policy or decision sets a timing explicitly. Applies to every resolution type, including exchanges and replacements. manual is held until a merchant calls POST /v1/return-resolutions/{id}/release.
after_approvalafter_handoffafter_receiptafter_inspectionmanual
requested_quantityintegerRequiredUnits the request asked to return. Whole-number quantity; fractional quantities are not supported.
requested_resolution_typeenumOutcome requested for this line when it was created. Absent when none was requested.
refundexchangereplacementno_monetary_actionstore_credit
resolution_statusenumRequiredWhether the value for this line's approved quantity has been delivered.
not_selectedpendingrequires_actionfulfilledfailed
resolved_quantityintegerRequiredUnits whose resolution has finished. Whole-number quantity; fractional quantities are not supported.
return_idstringRequiredID of the Return this line belongs to.
return_line_item_idstringRequiredUnique identifier for this return line item, prefixed `retli_`.
return_reasonobject or nullPresent only when `expand` includes `line_items.return_reason`; `null` when expanded and there is no related return reason.
Not returned with a customer session
return_reason_handlestringRequiredHandle of the chosen reason, captured when the line is created or its reason changes. Later renames, deactivation or archiving don't change it.
return_reason_idstringRequiredID of the reason chosen for this line.
return_reason_namestringRequiredName of the chosen reason, captured when the line is created or its reason changes. Later renames, deactivation or archiving don't change it.
return_required_quantityintegerRequiredHow much of the approved quantity the buyer must physically send back; fractional quantities are not supported. Set 0 for a returnless refund, where the buyer keeps the merchandise and the Return still settles the money.
return_resolution_idsarray of stringRequiredIDs of the resolutions that include this line, oldest first, including failed and canceled resolutions.
return_valueobjectRequiredValue of the line's units, fixed when the line was created: what the buyer paid for them, less what was already refunded or returned.
review_required_quantityintegerRequiredInspected units still waiting for an acceptance decision. Whole-number quantity; fractional quantities are not supported.
selected_optionsarray of objectRequiredVariant options selected for the item, such as size and color.
skustringSKU of the item as sold.
statusenumRequiredWhere this line stands. Same values and meanings as the Return's `status`, applied to the line.
requestedopencompleteddeclinedcanceled
supported_actionsarray of enumRequiredcancelwaive_inspection
updated_atstringRequiredRFC3339 timestamp.
variant_idstringID of the catalog variant the item was sold from.
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/returns/ret_01KEZF7C00PG93650ZKVQNGF7X/line-items/retli_01KEZF7C00R813VR7ECXS062QG \
-H "Flint-Version: 2026-09-07" \
-H "Authorization: Bearer YOUR_API_KEY"Successful response.
{
"data": {
"accepted_quantity": 0,
"allowed_resolution_types": [
"refund",
"exchange"
],
"approved_quantity": 0,
"available_resolution_quantity": 0,
"bundle_components": [],
"buyer_note": "I changed my mind.",
"canceled_quantity": 0,
"created_at": "2026-09-07T00:00:00Z",
"declined_quantity": 0,
"dispositioned_quantity": 0,
"eligibility": {
"allowed_resolution_types": [
"refund",
"exchange"
],
"eligible_quantity": 1,
"policy_adjustment_proposals": [],
"reason": "eligible_under_policy",
"reason_message": "Eligible under the return policy.",
"status": "eligible"
},
"fulfillment_id": "ful_01KEZF7C003HMXBX7F9B69B7AY",
"handed_off_quantity": 0,
"inspected_quantity": 0,
"is_inspection_required": false,
"is_policy_overridden": false,
"merchandise_status": "not_required",
"modifiers": [],
"name": "Linen shirt",
"order_line_item_id": "li_01KEZF7C00XM6VK5KNWVC3T907",
"received_quantity": 0,
"rejected_quantity": 0,
"requested_quantity": 1,
"requested_resolution_type": "refund",
"resolution_status": "not_selected",
"resolved_quantity": 0,
"return_id": "ret_01KEZF7C00VDTZH2NK73DBK2HZ",
"return_line_item_id": "retli_01KEZF7C001NHF6JPD83VD0MRK",
"return_reason_handle": "changed_mind",
"return_reason_id": "rrsn_01KEZF7C005274REWXTZRJ4BM0",
"return_reason_name": "Changed mind",
"return_required_quantity": 0,
"return_resolution_ids": [],
"return_value": {
"discount_money": {
"amount": 0,
"currency": "USD"
},
"subtotal_money": {
"amount": 5000,
"currency": "USD"
},
"tax_money": {
"amount": 0,
"currency": "USD"
},
"total_money": {
"amount": 5000,
"currency": "USD"
},
"unit_price_money": {
"amount": 5000,
"currency": "USD"
}
},
"review_required_quantity": 0,
"selected_options": [],
"status": "requested",
"supported_actions": [],
"updated_at": "2026-09-07T00:00:00Z"
},
"meta": {
"api_version": "2026-09-07"
},
"request_id": "req_01KWM6WAHG3N9Q8T2V5XRZ7C4D"
}Update return line item#
/v1/returns/{return_id}/line-items/{return_line_item_id}IdempotentRequires scope commerce.returns.write
Rate limit: write
Update a requested Return line item. Send null to clear buyer_note or requested_resolution_type. The response is the updated Return.
Path parameters
return_idstringRequiredFlint return id.
return_line_item_idstringRequiredFlint return line item id.
Request body
buyer_notestring or nullSend null to clear it.
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.
requested_quantityintegerWhole-number quantity; fractional quantities are not supported.
requested_resolution_typeenum or nullSend null to clear it.
refundexchangereplacementno_monetary_actionnull
return_reason_idstringID of the return reason for this line. The reason must be active.
curl -X PATCH https://api.withflintpay.com/v1/returns/ret_01KEZF7C00PG93650ZKVQNGF7X/line-items/retli_01KEZF7C00R813VR7ECXS062QG \
-H "Flint-Version: 2026-09-07" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: a-unique-key" \
-d '{
"buyer_note": "The size was too small.",
"expected_version": 1
}'Delete return line item#
/v1/returns/{return_id}/line-items/{return_line_item_id}IdempotentRequires scope commerce.returns.write
Rate limit: write
Remove a line item from a requested Return. Send optional expected_version as one query parameter to fence against the parent Return version. The response is the updated Return.
Path parameters
return_idstringRequiredFlint return id.
return_line_item_idstringRequiredFlint return line item id.
Query parameters
expected_versionintegerOptional version of the parent Return. Supply exactly once. A stale value returns VERSION_CONFLICT with the current Return version.
curl -X DELETE https://api.withflintpay.com/v1/returns/ret_01KEZF7C00PG93650ZKVQNGF7X/line-items/retli_01KEZF7C00R813VR7ECXS062QG \
-H "Flint-Version: 2026-09-07" \
-H "Authorization: Bearer YOUR_API_KEY"Cancel return line item#
/v1/returns/{return_id}/line-items/{return_line_item_id}/cancelIdempotentRequires scope commerce.returns.write
Rate limit: write
Cancel approved quantity on a Return line item. Quantity already received, inspected, dispositioned, or reserved by a resolution, including a failed one, cannot be canceled, and the conflict response names what is blocking it. Omit handback_quantity to lower the expected handback only as far as the canceled quantity requires. An explicit value cannot leave more merchandise expected than the remaining approved quantity.
Path parameters
return_idstringRequiredFlint return id.
return_line_item_idstringRequiredFlint return line item 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.
handback_quantityintegerHow many of the canceled units the buyer no longer has to send back, as a whole number; fractional quantities are not supported. Lowers return_required_quantity. Omit it to lower it only as far as the canceled quantity requires.
quantityintegerRequiredWhole-number quantity; fractional quantities are not supported.
reasonenumRequiredWhy it is being canceled.
buyer_requestmerchant_requestexpiredcreated_in_errorother
reason_messagestringOptional detail about `reason`, kept with the record.
curl -X POST https://api.withflintpay.com/v1/returns/ret_01KEZF7C00PG93650ZKVQNGF7X/line-items/retli_01KEZF7C00R813VR7ECXS062QG/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": 2,
"handback_quantity": 1,
"quantity": 1,
"reason": "buyer_request"
}'Waive return line inspection#
/v1/returns/{return_id}/line-items/{return_line_item_id}/waive-inspectionIdempotentRequires scope commerce.returns.write
Rate limit: write
Waive the inspection requirement on a Return line item so received quantity can be dispositioned and resolved without an inspection observation. Received quantity on a waived line satisfies after_inspection release timing.
Path parameters
return_idstringRequiredFlint return id.
return_line_item_idstringRequiredFlint return line item id.
Request body
expected_versionintegerOptional. The Return's current version, not the line's; a stale value returns 409 VERSION_CONFLICT.
reasonenumRequiredWhy inspection is being waived.
policy_overridetrusted_in_store_handoffmerchant_reviewother
reason_messagestringOptional detail about `reason`, kept with the record.
curl -X POST https://api.withflintpay.com/v1/returns/ret_01KEZF7C00PG93650ZKVQNGF7X/line-items/retli_01KEZF7C00R813VR7ECXS062QG/waive-inspection \
-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": "trusted_in_store_handoff"
}'Process existing return#
/v1/returns/{return_id}/processKey requiredRequires scopes commerce.returns.operations.write and commerce.returns.resolutions.write and commerce.returns.write (or the matching write scope)
Rate limit: write
Record decisions, receipts, inspections, dispositions, and resolutions for an existing requested or open Return in one request. On a requested Return, send one decision for every requested line; missing decisions fail with `ACTION_NOT_ALLOWED` and reason `status_not_reached`. Omit completion_mode to use the shared pinned policy mode, or automatic when none sets a mode; disagreeing policies require an explicit completion_mode. On an open Return, omit decision and completion_mode to keep committed values, or send those values unchanged; changed values fail with `ACTION_NOT_ALLOWED` and reason `field_locked`. completion_blockers includes resolution_not_selected for any uncovered approved quantity alongside blockers for unfinished resolutions. A line can be processed here only while it has no receipt, inspection, disposition, or resolution. For each line, received_quantity must equal its committed return_required_quantity. Send inspection exactly when the line requires inspection, with acceptance_status accepted. Refunds, payments, replacement orders, and inventory updates complete asynchronously. expected_version is optional and checked only when sent. If the Return has changed since that version, the request fails with VERSION_CONFLICT. When an automatic refund can no longer run through the original payment's provider, the request fails with `ACTION_NOT_ALLOWED`; send automatic_resolution_type as null to resolve manually, or choose no_monetary_action. Requires an idempotency key and all three scopes: commerce.returns.write, commerce.returns.operations.write, and commerce.returns.resolutions.write.
Path parameters
return_idstringRequiredFlint return id.
Request body
completion_modeenumOmit to use the mode shared by all pinned policies that set completion_mode, or automatic when no pinned policy sets one. Conflicting pinned policy modes return 400 naming completion_mode only when completion_mode is omitted. An explicit manual or automatic value is used as sent. On an open Return, omit to keep its committed mode. Sending that mode is accepted; a different mode returns 409 ACTION_NOT_ALLOWED with reason field_locked and param completion_mode.
manualautomatic
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.
line_itemsarray of objectRequiredOne decision for each line.
decisionobjectThe decision for this line, as an assertion about the committed terms.
dispositionobjectA disposition to record for this line's units.
inspectionobjectAn inspection to record for this line's units.
received_quantityintegerWhole number of units received. It must equal the line's committed return_required_quantity; fractional quantities are not supported.
resolutionobjectA resolution to create and confirm for this line.
return_line_item_idstringRequiredID of the Return line to act on.
receiptobjectA receipt to record for the Return.
external_actor_idstringYour identifier for the actor who recorded the event. Don't put secrets in this field.
external_reference_idstringCaller-owned identifier for this resource in an external system.
received_atstringRequiredWhen the event occurred, at most 5 minutes in the future.
receiving_location_idstringRequiredID of the Location that received the goods.
source_systemobjectSystem that recorded the observation. `null` when no source system was recorded.
Response · 200
Successful response.
dataobjectRequiredResource, collection, or operation result returned by this request.
returnobjectRequiredThe Return after this request's changes.
return_dispositionsarray of objectRequiredDispositions this request recorded, including any Flint created automatically.
return_inspectionsarray of objectRequiredInspections this request recorded.
return_receiptsarray of objectRequiredReceipts this request recorded.
return_resolutionsarray of objectRequiredResolutions this request created and confirmed.
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 -X POST https://api.withflintpay.com/v1/returns/ret_01KEZF7C00PG93650ZKVQNGF7X/process \
-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": [
{
"decision": {
"allowed_resolution_types": [
"refund",
"exchange"
],
"approved_quantity": 1,
"is_inspection_required": false,
"release_timing": "after_approval",
"return_required_quantity": 0
},
"return_line_item_id": "retli_01KEZF7C001NHF6JPD83VD0MRK"
}
]
}'Reopen return#
/v1/returns/{return_id}/reopenIdempotentRequires scope commerce.returns.write
Rate limit: write
Reopen a completed Return to record late compensating facts. Reopening sets completion_mode to manual, so complete the Return again with /complete once completion_blockers is empty. Confirmed money movements are never edited backward, so a monetary fix is a new correction resolution.
Path parameters
return_idstringRequiredFlint return 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 Return is being reopened.
linked_effect_changedcorrection_requiredadditional_merchandise_receivedmerchant_requestother
reason_messagestringOptional detail about `reason`, kept with the record.
curl -X POST https://api.withflintpay.com/v1/returns/ret_01KEZF7C00PG93650ZKVQNGF7X/reopen \
-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": 5,
"reason": "additional_merchandise_received"
}'Was this helpful?
