Returns
A Return takes merchandise back against an Order and settles what the buyer is owed. It applies your return policy, records what arrived and where it went, moves stock, and creates the Refunds, gift cards, replacement Orders, and payments that give the buyer their value. Use a Return whenever goods come back, and for a refund where the buyer keeps them. POST /v1/refunds moves money only: it skips eligibility, restocking fees, inspection, and inventory, and it requires a refund_type.
New to returns? Start with Your first return, which walks through POST /v1/returns/{return_id}/process for an item in your hands and the approve-first path for mail-in.
A Return tracks three things that move at their own pace:
- The decision. What the buyer asked for, and what you approved.
- The merchandise. What was handed off, received, inspected, and where it ended up.
- The value. What the buyer gets, through Refunds, gift cards, replacement Orders, and payments.
They come apart in practice. A refund can succeed while the parcel is still in transit, and a parcel can arrive before anyone approves the Return. Each track has its own status field, decision_status, merchandise_status, and resolution_status, and the Return's status says where the whole Return stands. When every track settles, the Return completes and Flint sends return.completed.
Pick your integration#
Most integrations use a handful of the Returns routes. Find the row that describes what you're building.
| What you're building | Start here |
|---|---|
| Anything, for the first time | Your first return |
| A buyer starts a return and sends it back by mail | Buyer-initiated returns |
| Staff take merchandise back at a register | Your first return: items are here |
| A warehouse or 3PL records what arrived | Receiving and inspecting |
| Refunds, store credit, exchanges, and replacements | Return resolutions |
| The rules: windows, fees, who pays shipping | Return policies and reasons |
Every flow writes the same facts. Create the Return with POST /v1/returns, then record each step with its own route, or commit the next set of decisions, receipts, inspections, dispositions, and resolutions together with POST /v1/returns/{return_id}/process. A counter return usually does everything in one process call; a mail-in return records each step as it happens.
The objects#
Everything hangs off one Return, which belongs to one Order.
Order
└── Return .......................... the request, and your decision on it
├── Return line items .......... one per order line, each with its own quantities
├── Receipts ................... what physically arrived
├── Inspections ................ what condition it was in, when the decision requires a check
├── Dispositions ............... where it went: back on sale, damaged, donated, discarded
├── Return shipments ........... labels and tracking for the parcel coming back
└── Resolutions ................ what the buyer gets
├── Refunds ............... money back on the original payment, or store credit on new gift cards
├── Replacement Order ..... merchandise going back out
└── PaymentIntents ........ when an exchange leaves a balance due
The Return lists every child by ID, and GET /v1/returns/{return_id} can expand receipts, inspections, dispositions, resolutions, and shipments in the same read. See Read a whole Return.
Receipts and inspections are observations. Once recorded they aren't edited: you correct one by recording a superseding observation, so the physical history stays intact.
How the statuses move#
The Return#
- 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
A Return starts requested. The decision opens it when any quantity is approved and declines it when none is. You can cancel a requested Return, and the buyer can withdraw one. declined and canceled are final.
You can cancel an open Return while nothing irreversible is recorded against it: no current receipt or inspection, no disposition or resolution that isn't canceled, and no return shipment that isn't voided. supported_actions lists cancel when you can. Canceling the last approved quantity on its lines also cancels the Return.
An open Return completes when its last completion blocker clears. Under completion_mode: automatic that happens on its own. Under manual you call POST /v1/returns/{return_id}/complete, which refuses while any blocker remains. completed isn't final: POST /v1/returns/{return_id}/reopen returns the Return to open so you can record late facts, such as a correction, and switches completion_mode to manual, so the Return stays open until you complete it again.
The decision#
- pending moves to approved on every unit
- pending moves to partially_approved on some units
- pending moves to declined on no units
decision_status is pending until the decision, which covers every line at once (see Deciding covers every line). It doesn't change afterwards. Approved quantity canceled later shows in the line's canceled_quantity, and reopening keeps the decision.
The merchandise#
- awaiting_handoff moves to in_transit on handoff
- in_transit moves to partially_received on some arrive
- partially_received moves to inspection_required on rest arrive
- partially_received moves to disposition_required on no inspection
- inspection_required moves to partially_inspected
- inspection_required moves to inspection_review_required
- partially_inspected moves to disposition_required
- inspection_review_required moves to disposition_required
- disposition_required moves to resolved
A line's merchandise_status is not_required until the decision. It stays not_required when the buyer keeps the goods (return_required_quantity: 0), and approval moves a line whose goods must come back to awaiting_handoff.
Flint recalculates the status from the line's quantities after each handoff, receipt, inspection, and disposition, so a line skips any status its quantities pass over. Merchandise handed over at a counter can go from awaiting_handoff to inspection_required, disposition_required, or resolved in one process call. A superseding receipt or inspection can move the status back.
- Inspection. A line goes through the inspection statuses only when its decision set
is_inspection_required. Without it, the line moves from receipt todisposition_required, or straight toresolvedwhen the policy's automatic receipt disposition dispositions the units on arrival. Waiving inspection before anything is inspected takes the line out of the inspection statuses the same way. - Exceptions.
exceptionappears on the Return, never on a line. A current receipt holds a unit that is unverified, because Flint couldn't match it to a line, or excess, because more arrived than the line expected, and that unit has no successful disposition.exceptionreplaces the Return'smerchandise_status, and amerchandise_exceptionblocker stays, until someone verifies the unit against a line or dispositions it. See Receiving and inspecting. - Rollup. Otherwise the Return reports its least-finished line's status, in this order:
awaiting_handoff,in_transit,partially_received,inspection_required,partially_inspected,inspection_review_required,disposition_required,resolved,not_required. A Return with oneresolvedline and onein_transitline isin_transit. A line the buyer keeps doesn't hold the Return back, so oneresolvedline and onenot_requiredline make the Returnresolved.
The value#
- not_selected moves to pending on proposed
- pending moves to fulfilled on delivered
- pending moves to partially_fulfilled on some lines
- partially_fulfilled moves to fulfilled on all remaining value
- pending moves to requires_action on waits
- requires_action moves to pending on resumes
- pending moves to failed on fails
- failed moves to pending on retry
An approved line's resolution_status is not_selected until a resolution covers it. Proposing one moves the line to pending, and canceling the proposal returns it to not_selected when no other resolution covers the line. requires_action means a resolution is waiting on a person, such as a buyer paying an exchange balance, and failed means one stopped. See Confirmed is not the same as paid.
Each line reports not_selected, pending, requires_action, fulfilled, or failed. The Return rolls them up in this order of precedence:
failedwhen any line or correction has failed.requires_actionwhen any is waiting on a person.fulfilledonce all remaining approved value is delivered.partially_fulfilledwhen some lines are fulfilled and other approved quantity is unresolved. Only the Return reports this value.pendingwhile resolutions are proposed or executing.not_selectedbefore any is proposed.
Fully declined and fully canceled lines don't count as unfinished work. A correction that hasn't settled keeps the Return at pending, requires_action, or failed.
Canceled quantity owes the buyer nothing, so it counts as settled. A line whose approved quantity is all canceled reports resolution_status: fulfilled and merchandise_status: not_required, and so does a Return canceled by canceling its last approved quantity. Read status, not resolution_status, to tell a canceled Return from one whose value was delivered.
What pending means#
The same word means something different on each field, so read it with its field name.
| Field | pending means |
|---|---|
decision_status | No decision yet |
resolution_status on a Return or line | A resolution is proposed or executing |
ReturnResolution.status | The resolution is confirmed and executing. One that isn't confirmed yet is proposed |
ReturnDisposition.status | The disposition is waiting for inventory to apply it |
merchandise_status has no pending; each of its waiting statuses names the work left. Completion blockers draw the same line as the resolution's own status: a proposed resolution reports resolution_not_selected, and only a confirmed one reports resolution_pending.
Which status answers which question#
Read the field that answers your question rather than inferring it from a neighbor.
| You want to know | Read |
|---|---|
| Did we say yes? | decision_status |
| Did the goods come back? | merchandise_status |
| Did the buyer get their value? | resolution_status |
| What is still outstanding? | completion_blockers |
| Is the whole Return finished? | status, or the return.completed event |
Build on completion_blockers. It is the authoritative list of what is still owed, and each entry names the Return line it belongs to and, where one exists, the receipt, inspection, disposition, or resolution holding it up. An empty array means nothing is outstanding. The Returns reference lists every code and what clears it.
Resolution blockers come in two kinds, and one line can carry both. Each unfinished resolution on a line adds a blocker that names it in return_resolution_id: resolution_not_selected while it is proposed, then resolution_pending, resolution_requires_action, or resolution_failed. Approved quantity that no resolution covers adds a resolution_not_selected blocker without a return_resolution_id whenever the line's available_resolution_quantity is 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.
Warning: Wait for return.completed, not for the refund
A resolution can finish while merchandise work is still open. If a job needs every obligation cleared, act 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.
Build a returns queue#
GET /v1/returns filters by the work left. work_type matches Returns that are still requested or open and need that kind of work: decision, handoff, receipt, inspection, disposition, resolution, or exception. Separate values with commas to match any of them. Add expand=order,customer so each row carries its order number and buyer:
curl "https://api.withflintpay.com/v1/returns?work_type=receipt,inspection&expand=order,customer" \
-H "Authorization: Bearer YOUR_API_KEY"
Each row then has an order summary and a customer summary, or customer: null on a guest order. Read the buyer's email from order.buyer_contact.email, which a guest order records too. expand=order needs commerce.orders.read and expand=customer needs customers.read. Page tokens stay valid when you add or drop expand.
For a search box, query matches a return ID, return number, external reference ID, order number, or buyer email. The list also filters by status, the three track statuses, resolution_type, receiving_location_id, order_id, and customer_id. See Show order and buyer on a list of Returns.
Deciding covers every line#
One decision opens the Return for all of its lines. POST /v1/returns/{return_id}/decide, and POST /v1/returns/{return_id}/process on a requested Return, take a decision for every requested line and record them together or not at all, so a line can't stay requested while the rest of the Return opens. If a line has no decision, nothing is recorded and the request returns 409 ACTION_NOT_ALLOWED with details[0].reason: status_not_reached. details[0] names the line with resource_type: return_line_item, its resource_id, and current_status: requested. param is line_items when the line is left out, and line_items[0].decision, indexed to the line, when process sends the line without a decision.
To settle part of a request now and the rest later, take the deferred line out of this decision and open a separate Return for it when you're ready:
- Decline it. Send
approved_quantity: 0with adecline_reasonfor that line. - Remove it. Before deciding, call
DELETE /v1/returns/{return_id}/line-items/{return_line_item_id}, then decide the remaining lines.
Once the Return is open, its decisions and completion_mode are committed. Process on an open Return keeps them when you omit them and accepts them sent unchanged; a changed value returns 409 ACTION_NOT_ALLOWED with details[0].reason: field_locked. Deciding and processing has the defaults and every refusal.
What you can model#
| Job | How |
|---|---|
| A return window, per product, category, or everything | A policy's scope and return_window |
| Final sale items | A higher-priority policy scoped to them with eligibility_result: "ineligible" |
| Charge a restocking fee | restocking_fee on the policy revision |
| Make the buyer pay return shipping | return_shipping.payer: "buyer" |
| Swap for a different size or variant | An exchange resolution with replacement line items |
| Give store credit instead of money back | A store_credit resolution, which refunds onto new gift cards |
| Send a replacement and collect nothing | A replacement resolution |
| "Keep it, we'll refund you" | Approve with return_required_quantity: 0 |
| Approve less than the buyer asked for | A smaller approved_quantity on the line |
| Refund only once the goods are back | release_timing of after_receipt or after_inspection |
| Accept a gift return | A refund goes to the original payer and payment method; a store_credit resolution gives the value as new gift cards instead |
| Refund to a gift card that was closed | Retry the failed resolution with gift_card_refund_destination: "new_gift_card" |
| Let a warehouse record arrivals without refund rights | A key with only commerce.returns.operations.write |
Two rules shape what a Return can hold:
- A bundle returns as one line. The Return line names the bundle's order line, and
bundle_componentslists its components for display and inventory lineage. You can't return one component on its own. - A correction can't leave the buyer owing money. A correction can reduce a credit to zero, but the buyer pays only through a checkout and a correction has no order to check out. See Fixing one after it settled.
Where returns meet the rest of Flint#
Returns reuse resources you have already integrated.
- Orders. The Return names an
order_id, and each line names theorder_line_item_idandfulfillment_idit came from. As value settles, Flint recalculates the order's refunded and balance amounts and appends to its activity log. - Refunds. A resolution that refunds, including store credit, creates an ordinary Refund on the same order, drawn from the same refundable balance. It carries
return_idandreturn_resolution_id, which are also filters onGET /v1/refunds; Refunds you create directly carry neither. Flint creates the Refund for you, so you don't send arefund_type. If the processor or your balance rejects it, the Refund is recorded withstatus: "failed"and afailure_reason, it stays linked to the resolution, and the Return follows that outcome. - Gift cards. Store credit, and gift card value sent to
new_gift_card, arrive as new gift cards. Withcustomer_email_delivery.returnsset toflint_sends, Flint emails each card to the buyer; withmerchant_sends, you deliver it. See Delivering the gift card. - Credit notes. On an invoiced order, committed Return lines and issued, non-void credit notes share each invoice line's remaining quantity and billed value. A Return request holds its line value until that quantity is declined or canceled. Creating or editing a Return beyond the shared remainder returns
409 ACTION_NOT_ALLOWED. - Inventory. A disposition is what moves stock, through an inventory receipt and movements at a Location. Under the policy's default
receipt_disposition_mode: automatic, Flint creates asellabledisposition at the receiving location when verified merchandise arrives, after an accepted inspection when one is required. Undermanual, stock doesn't change until a disposition you create succeeds. Untracked merchandise has no inventory effect. - Shipments. Return labels and tracking use the same shipment resource as outbound delivery, with
direction: return. The Return lists its shipments inshipment_ids. See Return labels and tracking.
Scopes#
Returns split write authority, so a store, a warehouse, and a support tool can each hold only what they need.
| Scope | Authority |
|---|---|
commerce.returns.read | Eligibility, Returns, child records, activities, previews, and access links |
commerce.returns.write | Create and edit Return requests, decide, waive inspection, cancel approved line quantity, cancel, complete, and reopen |
commerce.returns.operations.write | Record receipts, inspections, and dispositions, and verify, decide, retry, or cancel them |
commerce.returns.resolutions.write | Create, edit, confirm, release, retry, and cancel resolutions, and collect a buyer's balance in checkout |
commerce.returns.policies.write | Create, edit, version, and archive policies |
commerce.returns.reasons.write | Create, edit, and archive merchant reasons |
Any Returns write scope can also read Returns and their records. It gains no sibling write authority, so a warehouse key records physical facts without being able to refund. POST /v1/returns/{return_id}/process writes across all three areas and requires commerce.returns.write, commerce.returns.operations.write, and commerce.returns.resolutions.write.
Webhooks#
An action on the Return itself sends its own event: return.created, return.decision_recorded, return.canceled, return.completed, or return.reopened, or return.updated for an edit. Every change to a line, receipt, inspection, disposition, or resolution sends return.updated with the Return, plus that record's own event when it has one. Subscribe to the specific Return events when you need to know about cancellation or reopening, because return.updated doesn't fire for them.
Subscribe to what your system acts on:
| Integration | Start with |
|---|---|
| Merchant returns system | return.created, return.decision_recorded, return.updated, return.canceled, return.completed, return.reopened, return_resolution.updated |
| Buyer portal | No merchant subscription. Use buyer notifications and the buyer's own reads; see Buyer-initiated returns |
| Point of sale | return.updated, return.canceled, return.completed, return_disposition.updated, return_resolution.updated |
| Warehouse or WMS | return.decision_recorded, return.canceled, return_receipt.created, return_receipt.verified, return_inspection.created, return_inspection.acceptance_decided, return_disposition.updated |
| ERP or finance | return.completed, return_resolution.updated, refund.succeeded, refund.failed, payment_intent.succeeded, payment_intent.payment_failed, order.updated, inventory_receipt.created, inventory_level.updated |
Deduplicate on event ID, acknowledge quickly, and read the resource when your next action depends on its current version, because event order doesn't guarantee resource state. Payloads are in the webhook events catalog.
Why a Return was canceled, completed, or reopened#
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 it ended with a read instead of keeping your own record. This canceled Return is abridged:
{
"data": {
"return_id": "ret_01J5Z8N3QK4W7Y2RB6TPVXHC9D",
"status": "canceled",
"canceled_at": "2026-07-03T14:30:00Z",
"canceled_by": { "actor_type": "merchant", "actor_id": "usr_01J5Z7R2D8M4XK6WQ1T9BNVF3H" },
"cancellation_reason": "created_in_error",
"cancellation_reason_message": "Wrong order selected"
},
"request_id": "req_01KWM689BCKPEYZ9916SY9AZRN"
}
A canceled resolution or disposition carries the same three fields. canceled_by and the message are for merchants; a buyer reading a canceled Return sees cancellation_reason only. The return.canceled, return_resolution.updated, and return_disposition.updated webhooks send the resource, so they carry the fields too.
Actions that can happen more than once, such as reopening a Return or retrying a resolution, have no reason field on the resource, because a field would show only the latest one. Their reasons are in the Return's activities.
| You want to know | Read |
|---|---|
| Why a Return was canceled | cancellation_reason on the Return |
| Why a resolution or disposition was canceled | cancellation_reason on that resource |
| Why someone completed a Return by hand | completion_reason on the Return. Automatic completion has none |
| Why a Return was reopened, or a resolution or disposition was retried or released | The Return's activities |
The values and who can read each field are in Cancellation and completion reasons.
Return activities#
A Return's activities are a read-only history of what was recorded against it. Each row is one action: who took it, which resource it touched, the reason they gave, and the Return version it produced. Use them for a support timeline or an audit trail.
/v1/returns/{return_id}/activitiesRequired API key scopes: commerce.returns.operations.write, commerce.returns.policies.write, commerce.returns.read, commerce.returns.reasons.write, commerce.returns.resolutions.write or commerce.returns.writeReference for GET /v1/returns/{return_id}/activitiesThe Return's activity history, newest first by default. Needs a merchant credential.
Activities narrate; they aren't a source of state. To know where a Return stands, read the Return and its children, and to react as things happen, use webhooks instead of polling this list. Activities are merchant-only because reason_message often holds staff notes, so there is no buyer route; the buyer-visible fact is cancellation_reason on the Return.
Fetch the history in chronological order with sort_direction=asc:
curl "https://api.withflintpay.com/v1/returns/ret_1kmn0aExample/activities?sort_direction=asc" \
-H "Authorization: Bearer YOUR_API_KEY"
{
"data": [
{
"return_activity_id": "retact_01KWJZ8ZD3EDT7F78T82TZ6JXD",
"return_id": "ret_1kmn0aExample",
"activity_type": "return.decision_recorded",
"resource_type": "return",
"resource_id": "ret_1kmn0aExample",
"actor": { "actor_type": "merchant", "actor_id": "usr_01J5Z7R2D8M4XK6WQ1T9BNVF3H" },
"return_version": 2,
"created_at": "2026-07-03T14:30:00Z"
},
{
"return_activity_id": "retact_01KWJZ8ZE1P6H1M3F0Z34B0K1R",
"return_id": "ret_1kmn0aExample",
"activity_type": "return_resolution.effect_failed",
"resource_type": "return_resolution",
"resource_id": "retres_1kmn0aExample",
"actor": { "actor_type": "system" },
"reason": "refund_creation_failed",
"reason_message": "The refund could not be created.",
"return_version": 4,
"created_at": "2026-07-03T14:31:12Z"
},
{
"return_activity_id": "retact_01KWJZ8ZF7GXQ0S6E29Z4K3VD",
"return_id": "ret_1kmn0aExample",
"activity_type": "return_resolution.retried",
"resource_type": "return_resolution",
"resource_id": "retres_1kmn0aExample",
"actor": { "actor_type": "merchant", "actor_id": "usr_01J5Z7R2D8M4XK6WQ1T9BNVF3H" },
"reason": "dependency_recovered",
"reason_message": "Payment provider is back",
"return_version": 5,
"created_at": "2026-07-03T15:02:40Z"
},
{
"return_activity_id": "retact_01KWJZ8ZG2AEK5R5RZ025PX0S5",
"return_id": "ret_1kmn0aExample",
"activity_type": "return_line_item.quantity_canceled",
"resource_type": "return_line_item",
"resource_id": "retli_1kmn0aExample",
"actor": { "actor_type": "merchant", "actor_id": "usr_01J5Z7R2D8M4XK6WQ1T9BNVF3H" },
"reason": "buyer_request",
"quantity": 1,
"return_version": 6,
"created_at": "2026-07-03T15:20:00Z"
},
{
"return_activity_id": "retact_01KWJZ8ZH9CAZK2XBKGRQXB4A",
"return_id": "ret_1kmn0aExample",
"activity_type": "return.completed",
"resource_type": "return",
"resource_id": "ret_1kmn0aExample",
"actor": { "actor_type": "merchant", "actor_id": "usr_01J5Z7R2D8M4XK6WQ1T9BNVF3H" },
"reason": "manual_completion",
"return_version": 7,
"created_at": "2026-07-04T09:15:00Z"
},
{
"return_activity_id": "retact_01KWJZ8ZJ4N1V8D0YF2B7C3TQ",
"return_id": "ret_1kmn0aExample",
"activity_type": "return.reopened",
"resource_type": "return",
"resource_id": "ret_1kmn0aExample",
"actor": { "actor_type": "merchant", "actor_id": "usr_01J5Z7R2D8M4XK6WQ1T9BNVF3H" },
"reason": "correction_required",
"reason_message": "Restocking fee was applied twice",
"return_version": 8,
"created_at": "2026-07-06T11:48:00Z"
}
],
"next_page_token": null,
"request_id": "req_01KWM689BCKPEYZ9916SY9AZRN"
}
Read top to bottom, that log tells the story of a Return that needed attention:
return.decision_recordedopens the Return. Decisions carry no reason, so the row has none.return_resolution.effect_failedis Flint recording that the refund couldn't be created. The actor issystem, andreasonholds the failure code. The resolution'sfailure_codeandfailure_messagegive its current state.return_resolution.retriedis a merchant retrying the same resolution once the provider recovered. A retry can happen again, which is why its reason lives here and not on the resolution.return_line_item.quantity_canceledis the only type with aquantity: one unit was taken off the Return line.return.completedwithmanual_completionis a person calling/complete. A Return that completes on its own records the same type with asystemactor and no reason.return.reopenedsays why a completed Return went back toopen. Reopening clears the Return'scompletion_reason, but thereturn.completedrow still shows it.
Each row's return_version is the Return version after that action, so you can line a row up with the version in a webhook or a VERSION_CONFLICT error.
Handle unknown types gracefully#
activity_type and reason are extensible. Render a value you don't recognize as a generic row, so a new type doesn't break your timeline. The types Flint records:
| Group | Types |
|---|---|
| Return | return.created, return.updated, return.decision_recorded, return.canceled, return.completed, return.reopened, return.shipment_handoff_converged |
| Return lines | return_line_item.line_item_added, return_line_item.updated, return_line_item.deleted, return_line_item.inspection_waived, return_line_item.quantity_canceled |
| Receipts | return_receipt.created, return_receipt.corrected, return_receipt_line_item.verified |
| Inspections | return_inspection.created, return_inspection.corrected, return_inspection_line_item.acceptance_decided |
| Dispositions | return_disposition.created, return_disposition.retried, return_disposition.canceled, return_disposition.succeeded, return_disposition.failed |
| Resolutions | return_resolution.created, return_resolution.updated, return_resolution.confirmed, return_resolution.released, return_resolution.retried, return_resolution.canceled, return_resolution.effect_failed, return_resolution.refund_succeeded, return_resolution.refund_failed, return_resolution.payment_intent_updated, return_resolution.payment_succeeded, return_resolution.payment_failed, return_resolution.buyer_payment_required, return_resolution.replacement_order_created, return_resolution.replacement_fulfilled, return_resolution.replacement_fulfillment_canceled |
reason is the reason sent with the action, so its values come from that action's own list in the API reference. Two kinds come from Flint itself: automatic_receipt marks a disposition Flint created when a receipt or acceptance decision settled merchandise under automatic receipt disposition, and failure codes such as refund_creation_failed mark failures Flint recorded.
Versions, retries, and errors#
Guard against concurrent changes#
Send expected_version from the resource you read to reject a write when someone else changed it first. It is optional on actions and scalar updates, and required when a PATCH replaces an owned collection, such as a resolution's line_items. PATCH /v1/returns/{return_id} takes it in the body, and DELETE /v1/returns/{return_id}/line-items/{return_line_item_id} takes it as a query parameter.
It always compares with the resource the route acts on. Verifying a receipt line checks the receipt's version and deciding an inspection line checks the inspection's, so a change to the Return alone doesn't make them stale. Creating a resolution (POST /v1/returns/{return_id}/resolutions) and previewing one (resolution.expected_return_version on POST /v1/return-previews) assert the Return's version instead, as expected_return_version.
Retry safely#
Idempotency-Key is required on the writes that can move stock or money: creating a Return (POST /v1/returns and POST /v1/me/returns), because an automatic policy can approve and refund it; recording receipts, inspections, and dispositions, because each can move stock or create dispositions; and 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 recover a create whose response you lost, see Recovery by key.
Errors#
Refused actions covers the reasons shared across the API.
