Skip to content

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:

  1. The decision. What the buyer asked for, and what you approved.
  2. The merchandise. What was handed off, received, inspected, and where it ended up.
  3. 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 buildingStart here
Anything, for the first timeYour first return
A buyer starts a return and sends it back by mailBuyer-initiated returns
Staff take merchandise back at a registerYour first return: items are here
A warehouse or 3PL records what arrivedReceiving and inspecting
Refunds, store credit, exchanges, and replacementsReturn resolutions
The rules: windows, fees, who pays shippingReturn 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.

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

Return statusStartFinal
  • 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#

Decision statusStartFinal
  • 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#

Merchandise status: handoff and receiptStartFinal
  • 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
Merchandise status: inspection and dispositionStartFinal
  • 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 to disposition_required, or straight to resolved when 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. exception appears 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. exception replaces the Return's merchandise_status, and a merchandise_exception blocker 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 one resolved line and one in_transit line is in_transit. A line the buyer keeps doesn't hold the Return back, so one resolved line and one not_required line make the Return resolved.

The value#

Resolution statusStartFinal
  • 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:

  1. failed when any line or correction has failed.
  2. requires_action when any is waiting on a person.
  3. fulfilled once all remaining approved value is delivered.
  4. partially_fulfilled when some lines are fulfilled and other approved quantity is unresolved. Only the Return reports this value.
  5. pending while resolutions are proposed or executing.
  6. not_selected before 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.

Fieldpending means
decision_statusNo decision yet
resolution_status on a Return or lineA resolution is proposed or executing
ReturnResolution.statusThe resolution is confirmed and executing. One that isn't confirmed yet is proposed
ReturnDisposition.statusThe 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 knowRead
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
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: 0 with a decline_reason for 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#

JobHow
A return window, per product, category, or everythingA policy's scope and return_window
Final sale itemsA higher-priority policy scoped to them with eligibility_result: "ineligible"
Charge a restocking feerestocking_fee on the policy revision
Make the buyer pay return shippingreturn_shipping.payer: "buyer"
Swap for a different size or variantAn exchange resolution with replacement line items
Give store credit instead of money backA store_credit resolution, which refunds onto new gift cards
Send a replacement and collect nothingA replacement resolution
"Keep it, we'll refund you"Approve with return_required_quantity: 0
Approve less than the buyer asked forA smaller approved_quantity on the line
Refund only once the goods are backrelease_timing of after_receipt or after_inspection
Accept a gift returnA 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 closedRetry the failed resolution with gift_card_refund_destination: "new_gift_card"
Let a warehouse record arrivals without refund rightsA 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_components lists 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 the order_line_item_id and fulfillment_id it 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_id and return_resolution_id, which are also filters on GET /v1/refunds; Refunds you create directly carry neither. Flint creates the Refund for you, so you don't send a refund_type. If the processor or your balance rejects it, the Refund is recorded with status: "failed" and a failure_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. With customer_email_delivery.returns set to flint_sends, Flint emails each card to the buyer; with merchant_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 a sellable disposition at the receiving location when verified merchandise arrives, after an accepted inspection when one is required. Under manual, 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 in shipment_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.

ScopeAuthority
commerce.returns.readEligibility, Returns, child records, activities, previews, and access links
commerce.returns.writeCreate and edit Return requests, decide, waive inspection, cancel approved line quantity, cancel, complete, and reopen
commerce.returns.operations.writeRecord receipts, inspections, and dispositions, and verify, decide, retry, or cancel them
commerce.returns.resolutions.writeCreate, edit, confirm, release, retry, and cancel resolutions, and collect a buyer's balance in checkout
commerce.returns.policies.writeCreate, edit, version, and archive policies
commerce.returns.reasons.writeCreate, 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:

IntegrationStart with
Merchant returns systemreturn.created, return.decision_recorded, return.updated, return.canceled, return.completed, return.reopened, return_resolution.updated
Buyer portalNo merchant subscription. Use buyer notifications and the buyer's own reads; see Buyer-initiated returns
Point of salereturn.updated, return.canceled, return.completed, return_disposition.updated, return_resolution.updated
Warehouse or WMSreturn.decision_recorded, return.canceled, return_receipt.created, return_receipt.verified, return_inspection.created, return_inspection.acceptance_decided, return_disposition.updated
ERP or financereturn.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:

Response
{
  "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 knowRead
Why a Return was canceledcancellation_reason on the Return
Why a resolution or disposition was canceledcancellation_reason on that resource
Why someone completed a Return by handcompletion_reason on the Return. Automatic completion has none
Why a Return was reopened, or a resolution or disposition was retried or releasedThe 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.

GET/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}/activities

The 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
curl "https://api.withflintpay.com/v1/returns/ret_1kmn0aExample/activities?sort_direction=asc" \
  -H "Authorization: Bearer YOUR_API_KEY"
Response
{
  "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:

  1. return.decision_recorded opens the Return. Decisions carry no reason, so the row has none.
  2. return_resolution.effect_failed is Flint recording that the refund couldn't be created. The actor is system, and reason holds the failure code. The resolution's failure_code and failure_message give its current state.
  3. return_resolution.retried is 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.
  4. return_line_item.quantity_canceled is the only type with a quantity: one unit was taken off the Return line.
  5. return.completed with manual_completion is a person calling /complete. A Return that completes on its own records the same type with a system actor and no reason.
  6. return.reopened says why a completed Return went back to open. Reopening clears the Return's completion_reason, but the return.completed row 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:

GroupTypes
Returnreturn.created, return.updated, return.decision_recorded, return.canceled, return.completed, return.reopened, return.shipment_handoff_converged
Return linesreturn_line_item.line_item_added, return_line_item.updated, return_line_item.deleted, return_line_item.inspection_waived, return_line_item.quantity_canceled
Receiptsreturn_receipt.created, return_receipt.corrected, return_receipt_line_item.verified
Inspectionsreturn_inspection.created, return_inspection.corrected, return_inspection_line_item.acceptance_decided
Dispositionsreturn_disposition.created, return_disposition.retried, return_disposition.canceled, return_disposition.succeeded, return_disposition.failed
Resolutionsreturn_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#

  • HTTP 400
    Detail REQUIRED with param: expected_version when a PATCH that replaces an owned collection omits it. Detail REQUIRED with selectable_resources listing the candidates when an order line could belong to more than one fulfillment and you didn't send its fulfillment_id; param is line_items[0].fulfillment_id when creating or processing a Return, line_item.fulfillment_id when adding a line, or eligibility.selection.line_items[0].fulfillment_id in an eligibility preview.
  • HTTP 409
    VERSION_CONFLICTRefresh, then retry
    expected_version or expected_return_version is stale. details[0].current_version is the current version, so re-read and decide again. Without param, the write lost a race with another write: re-read and retry.
  • HTTP 409
    The state of a resource refuses the action. details[0] names that resource, which can be the Return, a line, a receipt or inspection line, a disposition, a resolution, a reason, or a policy, with its current_status and, when it publishes them, its supported_actions. Branch on details[0].reason; Return writes lists each one. Change the state or the request before you try again.
  • HTTP 409
    A quantity or value is above what remains. Submitted quantities name the field in param, such as line_items[0].quantity on a resolution. Receipt verification and resolution creation also refuse when stored records already use the capacity: read the receipts or resolutions and cancel the conflicting one first.
  • HTTP 500
    INTERNAL_ERRORRetry the same request
    Reason repair_required means a stored invariant is broken in a way caller actions can't produce. Contact Flint support with the request_id.

Refused actions covers the reasons shared across the API.

Next steps#

Your first returnTake an item back and refund it in sandbox, at the counter or by mail.Return policies and reasonsThe rules every Return is evaluated against.Returns API referenceEvery field, status, and route.

Was this helpful?