Skip to content

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.

WorkRoutesScope
Check what can come back, or price an outcomePOST /v1/return-previews with mode: eligibility or mode: resolutioncommerce.returns.read
Request the return, then approve or decline itPOST /v1/returns, the line item routes, then POST /v1/returns/{return_id}/decidecommerce.returns.write
Record what arrived, its condition, and where it wentReceipts, inspections, and dispositionscommerce.returns.operations.write
Give the buyer their valueResolutions: refunds, store credit, exchanges, and replacementscommerce.returns.resolutions.write
Cancel, complete, or reopen/cancel, /complete, and /reopencommerce.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.

QuestionRead
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:

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

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
status on return
Final values do not change again
  • requested
    Waiting for a decision. You can cancel it, and the buyer can withdraw it.
  • open
    Some quantity was approved. Merchandise or value work may remain; read completion_blockers.
  • completed
    Every completion blocker cleared and the Return completed. /reopen returns it to open.
  • declinedFinal
    Decided with nothing approved.
  • canceledFinal
    Canceled 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 return
  • not_required
    Nothing 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_handoff
    Approved merchandise hasn't been handed off.
  • in_transit
    The buyer handed it off and nothing has arrived.
  • partially_received
    Some of the expected merchandise arrived.
  • inspection_required
    Everything arrived and none of it is inspected yet. Only lines with is_inspection_required reach the inspection statuses.
  • partially_inspected
    Some received merchandise still needs inspection.
  • inspection_review_required
    Inspected merchandise is waiting for an acceptance decision.
  • disposition_required
    Received merchandise still needs a successful disposition.
  • resolved
    Every received unit has a successful disposition.
  • exception
    On 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 return
  • not_selected
    Approved quantity has no resolution. An approved line starts here, and returns here when its only proposed resolution is canceled.
  • pending
    A resolution is proposed or executing. The resolution's own status is proposed until it is confirmed and pending after.
  • partially_fulfilled
    On the Return only. Some lines' value was delivered and other approved quantity is still unresolved.
  • requires_action
    A resolution waits on someone; see its action_required_by.
  • fulfilled
    All approved value was delivered, or all approved quantity was canceled. Read status to tell a canceled Return from a delivered one.
  • failed
    A resolution failed; see its failure_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.

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

codeCleared by
decision_pendingDeciding the Return
handoff_pendingThe buyer handing the merchandise off, or a receipt
receipt_pendingA receipt for the handed-off merchandise
inspection_pendingInspecting received merchandise
inspection_review_requiredAn acceptance decision on an inspection line
disposition_requiredA successful disposition
resolution_not_selectedCreating and confirming a resolution
resolution_pendingThe resolution's effects settling
resolution_requires_actionWhatever the resolution waits on, usually a buyer payment
resolution_failedRetrying or replacing the failed resolution
merchandise_exceptionVerifying 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_selected while it is proposed, then resolution_pending, resolution_requires_action, or resolution_failed.
  • Uncovered quantity. 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.

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:

CounterCounts
requested_quantityUnits the request asked to return
approved_quantity, declined_quantityUnits the decision approved or declined
canceled_quantityApproved units canceled later
return_required_quantityApproved units the buyer must send back. 0 means the buyer keeps them and the Return still settles the money
handed_off_quantity, received_quantityUnits the buyer handed off, and units that arrived
inspected_quantityUnits inspected
accepted_quantity, rejected_quantityInspected units with an acceptance decision either way
review_required_quantityInspected units still waiting for that decision
dispositioned_quantityUnits with a successful disposition
resolved_quantityUnits whose resolution is fulfilled
available_resolution_quantityApproved 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:

Approvedreturn_required_quantityCancelOmitted handback_quantity becomesreturn_required_quantity after
33221
32102
30200

An explicit handback_quantity must stay within three limits:

  • Between 0 and quantity.
  • No more than return_required_quantity minus received_quantity, since units that arrived can't be handed back.
  • Low enough that return_required_quantity doesn't end up above the remaining approved quantity. In the first row, handback_quantity: 0 would still expect 3 units from a line with 1 approved unit left, so it returns 400 INVALID_REQUEST with detail INVALID_VALUE and param: "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
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, detail INVALID_VALUE, and param: "expand". Page that collection from its list route instead, such as GET /v1/return-dispositions?return_id=ret_01J5Z8N3QK4W7Y2RB6TPVXHC9D.
  • A shipment expands to its summary. Read GET /v1/shipments/{shipment_id} for its packages. Expanding shipments also needs commerce.orders.read.
  • Child expansions work only on this single-Return read with an API key or partner app, not on GET /v1/returns or /v1/me reads.

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.

expandAddsAlso needs
orderThe order summary for order_idcommerce.orders.read
customerThe customer summary for customer_id, or null when the Return has nonecustomers.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
curl -G https://api.withflintpay.com/v1/returns \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --data-urlencode "status=requested" \
  --data-urlencode "expand=order,customer"
JSON
{
  "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_actions is ["cancel"] while the buyer can withdraw the Return, and empty otherwise. Lines carry no actions.
  • completion_blockers keeps only what the buyer can clear: handoff_pending, resolution_not_selected, resolution_requires_action, and resolution_failed, plus resolution_pending when 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, and completion_reason_message. The buyer still sees cancellation_reason.
  • Of the child ID arrays, only return_resolution_ids remains, 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.

FieldMeaning
activity_typeWhat happened, as {resource_type}.{action}, such as return.reopened or return_resolution.retried
resource_type, resource_idWhat it is about: the Return, a line, or a receipt, inspection, disposition, or resolution
actorWho acted. actor_type is buyer, merchant, integration, or system, with an actor_id when one exists
reason, reason_messageThe reason and note sent with the action. When Flint records a failed effect, they carry its failure code and message
quantityThe units canceled, only on return_line_item.quantity_canceled
return_versionThe 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:

Returncompletion_mode omittedcompletion_mode sent
RequestedThe 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 modeAccepted 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:

Requestdetails[0].reasondetails[0] namesparam
A requested line is left out of line_itemsstatus_not_reachedThe line, with current_status: requestedline_items
/process sends a requested line without decisionstatus_not_reachedThe line, with current_status: requestedline_items[0].decision, indexed to the line
/process on an open Return sends a different completion_modefield_lockedThe Return, with current_status: open and its supported_actionscompletion_mode
/process on an open Return sends a decision that differs from the committed termsfield_lockedThe line, with its status and supported_actionsline_items[0].decision, indexed to the line
An automatic refund can no longer run through the original payment's providerrefund_unavailableThe order, without current_statusline_items[0].automatic_resolution_type on /decide, line_items[0].decision.automatic_resolution_type on /process
The original payment can't fund automatic store creditstore_credit_unavailableThe order, without current_statusThe 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:

  • /process compares with the Return's version, 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's version, 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_version on POST /v1/returns/{return_id}/resolutions, or resolution.expected_return_version on POST /v1/return-previews. Both are optional.
  • DELETE /v1/returns/{return_id}/line-items/{return_line_item_id} takes the Return's version as an expected_version query 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/returns and POST /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#

  • HTTP 409
    VERSION_CONFLICTRefresh, then retry
    expected_version or expected_return_version is stale. details[0].current_version is the current version; for a stale expected_return_version, param names the field you sent and details[0] names the Return. 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. Branch on details[0].reason; Refused actions lists each one.
  • HTTP 409
    A quantity or value is above what remains. A submitted quantity names its indexed field in param, such as line_items[0].quantity when creating a resolution. Receipt verification and resolution creation can also refuse because stored records already use the capacity, and then omit param: a receipt refusal names the receipt and its status with requested_quantity and available_quantity, and a resolution refusal names the Return and its status with maximum_money floored 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.

reasonMeaning on Returns resources
already_appliedA receipt line is already verified, or an inspection line already has its acceptance decision
terminal_statusThe resource is canceled, completed, declined, fulfilled, succeeded, or superseded
status_not_reachedThe 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
archivedThe reason or policy is archived
not_offeredA buyer asked for something the policy doesn't offer through self-service, such as a line or resolution type. param names the field
refund_createdA failed resolution already created a Refund and can't be canceled. remediation.next_actions offers get_refund
refund_unavailableThe order's payment can no longer be refunded. details[0] names the order and has no current_status
store_credit_unavailableThe order's payments can't fund store credit; see Store credit
unsupported_stateAny 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.

FieldRecorded whenWho can read it
cancellation_reasonThe Return is canceledMerchants and buyers
cancellation_reason_messageThe Return is canceled with a reason_messageMerchants
canceled_byThe Return is canceledMerchants
completion_reason/complete is called with a reasonMerchants
completion_reason_message/complete is called with a reason_messageMerchants

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.

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:

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 objectRequired

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

RFC3339 timestamp.

canceled_byobject

Who canceled the Return.

Not returned with a customer session

cancellation_reasonenum

Why the Return was canceled.

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

Detail sent with the cancellation. Merchant reads only.

Not returned with a customer session

completed_atstring

RFC3339 timestamp.

completed_byobject

Who completed the Return. `system` when Flint completed it automatically.

Not returned with a customer session

completion_blockersarray of objectRequired

What is still owed before the Return can complete. Empty when nothing is.

completion_modeenum

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

  • manual
  • automatic
completion_reasonenum

Why the Return was completed by hand. Absent when Flint completed it automatically.

Not returned with a customer session

  • manual_completion
  • exception_waived
  • other
completion_reason_messagestring

Detail sent when the Return was completed by hand.

Not returned with a customer session

created_atstringRequired

RFC3339 timestamp.

customerobject or null

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

Not returned with a customer session

customer_idstring

The customer the Return belongs to.

Not returned with a customer session

decision_atstring

RFC3339 timestamp.

decision_statusenumRequired

Whether the requested units were approved. `pending` until one decision covers every line.

  • pending
  • approved
  • partially_approved
  • declined
external_reference_idstring

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

Not returned with a customer session

financial_summaryobjectRequired

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

What 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_byenumRequired

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

  • buyer
  • merchant
  • integration
line_itemsarray of objectRequired

The lines being returned.

merchandise_statusenumRequired

On the Return, the least-finished line's value.

  • not_required
  • awaiting_handoff
  • in_transit
  • partially_received
  • inspection_required
  • partially_inspected
  • inspection_review_required
  • disposition_required
  • resolved
  • exception
metadatamap of stringRequired

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

orderobject or null

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

Not returned with a customer session

order_idstringRequired

ID of the Order the Return is against.

policy_evaluationobject

How your return policies judged the request when the Return was created.

Not returned with a customer session

resolution_statusenumRequired

Whether the buyer has received the value they are owed. Combines the Return's resolutions and its unsettled corrections.

  • not_selected
  • pending
  • partially_fulfilled
  • requires_action
  • fulfilled
  • failed
return_disposition_idsarray of stringRequired

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

Present only when `expand` includes `return_dispositions`. The dispositions in `return_disposition_ids`, in the same order.

Not returned with a customer session

return_idstringRequired

Unique identifier for this return, prefixed `ret_`.

return_inspection_idsarray of stringRequired

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

Present only when `expand` includes `return_inspections`. The inspections in `return_inspection_ids`, in the same order.

Not returned with a customer session

return_numberstringRequired

Human-readable number for the Return.

return_receipt_idsarray of stringRequired

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

Present 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 stringRequired

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

Present 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 stringRequired

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

Present only when `expand` includes `shipments`. Summaries of the shipments in `shipment_ids`, in the same order.

Not returned with a customer session

statusenumRequired

Where the whole Return stands. Read `decision_status`, `merchandise_status`, and `resolution_status` for the part you need.

  • requested
  • open
  • completed
  • declined
  • canceled
supported_actionsarray of enumRequired
  • cancel
  • complete
  • decide
  • reopen
updated_atstringRequired

RFC3339 timestamp.

versionintegerRequired

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

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

POST/v1/return-previews

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

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

eligibilityobjectRequired

The eligibility check. Present when `mode` is `eligibility`.

modeenumRequired

Which preview to run.

  • eligibility

Response · 200

Successful response.

dataone ofRequired

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

metaobject

Additional information about this response.

request_idstringRequired

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

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

GET/v1/returns

Requires scope commerce.returns.operations.write or commerce.returns.policies.write or commerce.returns.read or commerce.returns.reasons.write or commerce.returns.resolutions.write or commerce.returns.write

Rate limit: read

List 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_afterstring

Inclusive lower bound on created_at.

created_beforestring

Exclusive upper bound on created_at.

customer_idstring

Filter by customer id.

decision_statusarray of enum

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

  • pending
  • approved
  • partially_approved
  • declined
external_reference_idstring

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

idempotency_keystring

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

Filter 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_required
  • awaiting_handoff
  • in_transit
  • partially_received
  • inspection_required
  • partially_inspected
  • inspection_review_required
  • disposition_required
  • resolved
  • exception
order_idstring

Filter by order id.

page_sizeinteger

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

page_tokenstring

Opaque next_page_token from the previous response. Omit on the first request. You may change `page_size` between pages. Reuse it with the same endpoint, filters, sort, and request context. Do not parse or construct tokens. An invalid, expired, or mismatched token returns a validation error.

querystring

Search by return ID, return number, external reference ID, the order's number, or the buyer's email.

receiving_location_idstring

Filter by receiving location id.

resolution_statusarray of enum

Filter 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_selected
  • pending
  • partially_fulfilled
  • requires_action
  • fulfilled
  • failed
resolution_typearray of enum

Filter by resolution type. Values are trimmed and deduplicated in first-seen order; empty or unknown entries are rejected. Values within this filter are ORed; separate filters are ANDed.

  • refund
  • exchange
  • replacement
  • store_credit
  • no_monetary_action
  • correction
return_numberstring

Filter by return number.

return_reason_idstring

Filter by return reason id.

sort_byenum

Field to sort by. Defaults to created_at; ties are broken by return_id.

  • created_at
sort_directionenum

Sort direction. Defaults to desc.

  • asc
  • desc
statusarray of enum

Filter by status. Values are trimmed and deduplicated in first-seen order; empty or unknown entries are rejected. Values within this filter are ORed; separate filters are ANDed.

  • requested
  • open
  • completed
  • declined
  • canceled
updated_afterstring

Inclusive lower bound on updated_at.

updated_beforestring

Exclusive upper bound on updated_at.

work_typearray of enum

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

  • decision
  • handoff
  • receipt
  • inspection
  • disposition
  • resolution
  • exception
expandarray of enum

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

  • customer
  • order

Response · 200

Successful response.

dataarray of objectRequired

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

metaobject

Additional information about this response.

next_page_tokenstring

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

request_idstringRequired

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

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

Successful response.

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

POST/v1/returnsKey required

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

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

line_itemsarray of objectRequired

The lines to check or return, each naming an order line item.

metadatamap of string

Caller-owned metadata. Values can't be empty strings. Keys starting with flint_ are reserved for Flint, are not returned, and cannot be written through the public API.

order_idstringRequired

ID of the Order to return items from.

Response · 201

Successful response.

dataobjectRequired

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

metaobject

Additional information about this response.

request_idstringRequired

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

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

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

Flint return id.

Query parameters

expandarray of enum

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

  • customer
  • line_items.fulfillment
  • line_items.return_reason
  • order
  • return_dispositions
  • return_inspections
  • return_receipts
  • return_resolutions
  • shipments

Response · 200

Successful response.

Same response as Create return.

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

Successful response.

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

PATCH/v1/returns/{return_id}Idempotent

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

Flint return id.

Request body

expected_versioninteger

Optional version of the Return. A stale value returns VERSION_CONFLICT with the current Return version.

external_reference_idstring or null

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

metadatamap of string or null

Caller-owned metadata. Omit this field to leave metadata unchanged. Send an object to merge by key, set a key to null to remove it, or set metadata to null to clear all caller-owned metadata. An empty object makes no change. Values can't be empty strings. Keys starting with flint_ are reserved for Flint, are not returned, and cannot be written through the public API.

Response · 200

Successful response.

Same response as Create return.

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"
    }
  }'

List return activities#

GET/v1/returns/{return_id}/activities

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

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_idstringRequired

Flint return id.

Query parameters

page_sizeinteger

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

page_tokenstring

Opaque next_page_token from the previous response. Omit on the first request. You may change `page_size` between pages. Reuse it with the same endpoint, filters, sort, and request context. Do not parse or construct tokens. An invalid, expired, or mismatched token returns a validation error.

sort_directionenum

Sort direction. Defaults to desc.

  • asc
  • desc

Response · 200

Successful response.

dataarray of objectRequired

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

metaobject

Additional information about this response.

next_page_tokenstring

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

request_idstringRequired

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

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

Successful response.

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

POST/v1/returns/{return_id}/cancelIdempotent

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

Flint return id.

Request body

expected_versioninteger

Version last read from the resource returned in `data` (the primary resource for a result object). The write fails with `VERSION_CONFLICT` if it has changed. Requiredness depends on the operation and fields being changed.

reasonenumRequired

Why it is being canceled.

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

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

Response · 200

Successful response.

Same response as Create return.

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#

POST/v1/returns/{return_id}/completeIdempotent

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

Flint return id.

Request body

expected_versioninteger

Version last read from the resource returned in `data` (the primary resource for a result object). The write fails with `VERSION_CONFLICT` if it has changed. Requiredness depends on the operation and fields being changed.

reasonenum

Why you are completing the Return by hand.

  • manual_completion
  • exception_waived
  • other
reason_messagestring

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

Response · 200

Successful response.

Same response as Create return.

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#

POST/v1/returns/{return_id}/decideIdempotent

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

Flint return id.

Request body

completion_modeenum

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

  • manual
  • automatic
expected_versioninteger

Version last read from the resource returned in `data` (the primary resource for a result object). The write fails with `VERSION_CONFLICT` if it has changed. Requiredness depends on the operation and fields being changed.

line_itemsarray of objectRequired

One decision for each line.

Response · 200

Successful response.

Same response as Create return.

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#

GET/v1/returns/{return_id}/line-items

Requires scope commerce.returns.operations.write or commerce.returns.policies.write or commerce.returns.read or commerce.returns.reasons.write or commerce.returns.resolutions.write or commerce.returns.write

Rate limit: read

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

Flint return id.

Query parameters

fulfillment_idstring

Filter by fulfillment id.

merchandise_statusarray of enum

Filter 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_required
  • awaiting_handoff
  • in_transit
  • partially_received
  • inspection_required
  • partially_inspected
  • inspection_review_required
  • disposition_required
  • resolved
  • exception
order_line_item_idstring

Filter by order line item id.

page_sizeinteger

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

page_tokenstring

Opaque next_page_token from the previous response. Omit on the first request. You may change `page_size` between pages. Reuse it with the same endpoint, filters, sort, and request context. Do not parse or construct tokens. An invalid, expired, or mismatched token returns a validation error.

resolution_statusarray of enum

Filter 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_selected
  • pending
  • requires_action
  • fulfilled
  • failed
return_reason_idstring

Filter by return reason id.

statusarray of enum

Filter by status. Values are trimmed and deduplicated in first-seen order; empty or unknown entries are rejected. Values within this filter are ORed; separate filters are ANDed.

  • requested
  • open
  • completed
  • declined
  • canceled

Response · 200

Successful response.

dataarray of objectRequired

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

metaobject

Additional information about this response.

next_page_tokenstring

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

request_idstringRequired

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

curl https://api.withflintpay.com/v1/returns/ret_01KEZF7C00PG93650ZKVQNGF7X/line-items \
  -H "Flint-Version: 2026-09-07" \
  -H "Authorization: Bearer YOUR_API_KEY"

Successful response.

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

POST/v1/returns/{return_id}/line-itemsIdempotent

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

Flint return id.

Request body

expected_versioninteger

Version last read from the resource returned in `data` (the primary resource for a result object). The write fails with `VERSION_CONFLICT` if it has changed. Requiredness depends on the operation and fields being changed.

line_itemobjectRequired

The line to add.

Response · 200

Successful response.

Same response as Create return.

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#

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

Flint return id.

return_line_item_idstringRequired

Flint return line item id.

Response · 200

Successful response.

dataobjectRequired

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

metaobject

Additional information about this response.

request_idstringRequired

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

curl https://api.withflintpay.com/v1/returns/ret_01KEZF7C00PG93650ZKVQNGF7X/line-items/retli_01KEZF7C00R813VR7ECXS062QG \
  -H "Flint-Version: 2026-09-07" \
  -H "Authorization: Bearer YOUR_API_KEY"

Successful response.

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

PATCH/v1/returns/{return_id}/line-items/{return_line_item_id}Idempotent

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

Flint return id.

return_line_item_idstringRequired

Flint return line item id.

Request body

buyer_notestring or null

Send null to clear it.

expected_versioninteger

Version last read from the resource returned in `data` (the primary resource for a result object). The write fails with `VERSION_CONFLICT` if it has changed. Requiredness depends on the operation and fields being changed.

requested_quantityinteger

Whole-number quantity; fractional quantities are not supported.

requested_resolution_typeenum or null

Send null to clear it.

  • refund
  • exchange
  • replacement
  • no_monetary_action
  • null
return_reason_idstring

ID of the return reason for this line. The reason must be active.

Response · 200

Successful response.

Same response as Create return.

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#

DELETE/v1/returns/{return_id}/line-items/{return_line_item_id}Idempotent

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

Flint return id.

return_line_item_idstringRequired

Flint return line item id.

Query parameters

expected_versioninteger

Optional version of the parent Return. Supply exactly once. A stale value returns VERSION_CONFLICT with the current Return version.

Response · 200

Successful response.

Same response as Create return.

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#

POST/v1/returns/{return_id}/line-items/{return_line_item_id}/cancelIdempotent

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

Flint return id.

return_line_item_idstringRequired

Flint return line item id.

Request body

expected_versioninteger

Version last read from the resource returned in `data` (the primary resource for a result object). The write fails with `VERSION_CONFLICT` if it has changed. Requiredness depends on the operation and fields being changed.

handback_quantityinteger

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

quantityintegerRequired

Whole-number quantity; fractional quantities are not supported.

reasonenumRequired

Why it is being canceled.

  • buyer_request
  • merchant_request
  • expired
  • created_in_error
  • other
reason_messagestring

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

Response · 200

Successful response.

Same response as Create return.

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#

POST/v1/returns/{return_id}/line-items/{return_line_item_id}/waive-inspectionIdempotent

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

Flint return id.

return_line_item_idstringRequired

Flint return line item id.

Request body

expected_versioninteger

Optional. The Return's current version, not the line's; a stale value returns 409 VERSION_CONFLICT.

reasonenumRequired

Why inspection is being waived.

  • policy_override
  • trusted_in_store_handoff
  • merchant_review
  • other
reason_messagestring

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

Response · 200

Successful response.

Same response as Create return.

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#

POST/v1/returns/{return_id}/processKey required

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

Flint return id.

Request body

completion_modeenum

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

  • manual
  • automatic
expected_versioninteger

Version last read from the resource returned in `data` (the primary resource for a result object). The write fails with `VERSION_CONFLICT` if it has changed. Requiredness depends on the operation and fields being changed.

line_itemsarray of objectRequired

One decision for each line.

receiptobject

A receipt to record for the Return.

Response · 200

Successful response.

dataobjectRequired

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

metaobject

Additional information about this response.

request_idstringRequired

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

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

POST/v1/returns/{return_id}/reopenIdempotent

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

Flint return id.

Request body

expected_versioninteger

Version last read from the resource returned in `data` (the primary resource for a result object). The write fails with `VERSION_CONFLICT` if it has changed. Requiredness depends on the operation and fields being changed.

reasonenumRequired

Why the Return is being reopened.

  • linked_effect_changed
  • correction_required
  • additional_merchandise_received
  • merchant_request
  • other
reason_messagestring

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

Response · 200

Successful response.

Same response as Create return.

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?