Buyer-initiated returns
A buyer opens an order in your account pages, picks an item, says why, and gets a label. Flint checks the request against your return policy, records it as the buyer's own, and tracks the parcel and the money afterward. Your pages call /v1/me with a customer session, and your backend adds the label with an API key.
Flint's hosted customer account already offers all of this. Build it yourself when you run your own account (customer_account.mode merchant_hosted) or want returns inside your app; Customer accounts compares the two. Either way, buyers can only start a return that an active return policy covers, so write one first. For a buyer standing at your counter, see Your first return.
- Buyer's browser sends open an order, choose Return to Your backend
- Your backend sends POST /v1/me/return-previews (eligibility) to Flint
- Flint returns can_buyer_request, reasons, allowed outcomes to Your backend
- Your backend sends POST /v1/me/returns to Flint
- Flint returns Return in requested, initiated_by buyer to Your backend
- Flint sends return.decision_recorded, from your policy or your review to Your backend
- Your backend sends return shipment and package with your carrier's label (API key) to Flint
- Your backend sends GET /v1/me/packages for the label and tracking to Flint
- Your backend returns label, then progress until return.completed to Buyer's browser
The session secret stays on your server: the browser calls your backend, and your backend calls /v1/me. Relay /v1/me through your backend covers that relay.
Use the customer session, not your API key#
Send the buyer's requests with their customer session. Flint then checks that every order and Return belongs to that buyer, holds each request to your policy, and records the Return as the buyer's. Your server could create the same Return on /v1/returns with an API key, but Flint can't tell who is asking, so it applies none of those checks.
Customer session on /v1/me | API key on /v1/returns | |
|---|---|---|
initiated_by | buyer | integration |
| Return policy | Enforced: an active policy must cover each line and leave the quantity eligible | Recorded but not enforced: a line no policy covers, or one it excludes, waits for your review |
| Return reasons | Active reasons that apply to the item's catalog categories | Any active reason |
| Request fields | order_id and line_items only | Also external_reference_id and metadata |
| Resolution type | Chosen at create with requested_resolution_type | Can also change later with PATCH /v1/returns/{return_id}/line-items/{return_line_item_id} |
initiated_by comes from the credential and can't be sent. With an API key, your server has to read can_buyer_request from a preview and refuse the request itself, and a front-end mistake can show one buyer another buyer's order. Keep the API key for staff who create a Return for the buyer, at a counter or in a support tool.
Offer the return on the order page#
Read one order with GET /v1/me/orders/{order_id} and look at its start_return buyer action. It is available when at least one delivered item can be returned now, and its due_at is the last moment any of them can. Otherwise unavailable_reason says why: not_in_state before anything is delivered, nothing_to_return when everything delivered is already in a Return, window_closed when the return window ended, or store_policy when your policies cover none of what's left. A list of orders leaves start_return out, because only a read of one order checks eligibility.
Show what can come back#
When the buyer chooses to return something, run an eligibility preview. It evaluates every delivered item on the order that isn't already in a Return, so your pages never work out what earlier Returns consumed.
curl -X POST https://api.withflintpay.com/v1/me/return-previews \
-H "Authorization: Bearer flint_cses_example" \
-H "Content-Type: application/json" \
-d '{
"mode": "eligibility",
"eligibility": {
"order_id": "ord_1kmn0aExample",
"selection": { "selection_type": "all_remaining_fulfilled" }
}
}'
Each entry in data.eligibility.line_items describes one order line on one fulfillment. Trimmed to one line, an eligible mug reads:
{
"order_line_item_id": "li_1kmn0aExample",
"fulfillment_id": "ful_1kmn0aExample",
"name": "Stoneware mug",
"sku": "MUG-STONE-12",
"selected_options": [],
"modifiers": [],
"bundle_components": [],
"can_buyer_request": true,
"eligibility": {
"status": "eligible",
"reason": "eligible_under_policy",
"reason_message": "This item is eligible under the matched return policy.",
"eligible_quantity": 2,
"expires_at": "2026-11-27T00:00:00Z",
"allowed_resolution_types": ["refund", "exchange"],
"policy_adjustment_proposals": []
},
"suggested_return_reasons": [
{
"return_reason_id": "rrsn_1T6HXAX0CEXP6YA5K1T392KJE6",
"handle": "damaged",
"name": "Arrived damaged",
"is_note_required": true
}
]
}
That is enough to render the whole screen without another read:
- The item.
name,sku,image,selected_options, andmodifiersare frozen from the order. - Whether to show a return button. Use
can_buyer_request. It istrueexactly whenPOST /v1/me/returnswould accept the line at itseligible_quantity: a policy covers it, it isn't ineligible, some quantity is left, and you offer at least one reason for it. Don't work it out fromstatusyourself. - The deadline.
expires_atis when the window closes. - The reasons. Offer
suggested_return_reasonsas the choices, up to 20 per line. Each is active and applies to the item, so two lines on one order can offer different lists. Whenis_note_requiredistrue, ask for a note. - The outcomes.
allowed_resolution_typeslists what the buyer can ask for. - Fees.
policy_adjustment_proposalslists the restocking or return shipping fees your policy will take, so the buyer sees them before committing.
When can_buyer_request is false, show reason_message, a sentence written for the buyer. Branch on reason when you want your own wording:
reason on buyer return line item eligibilityineligibility_reason appears only with policy_ineligible. It is the reason the excluding policy declares: final_sale, product_excluded, category_excluded, market_restricted, channel_restricted, outside_return_window, or other. Flint checks an excluding policy before the return window, so a final-sale item reports final_sale even after its window has passed. Use it to show "Final sale" instead of a general message.
To check particular lines, send selection_type: "line_items" with at least one line. Each needs order_line_item_id and requested_quantity, and can add fulfillment_id, return_reason_id, and requested_resolution_type. When you send a reason or an outcome, Flint checks it the way create does, so you can confirm the buyer's choices before submitting.
A preview reserves nothing and can go stale as soon as it returns. Treat it as what to show, not a promise: create checks everything again.
Create the request#
Send the order, then each line with its quantity and the reason the buyer picked. Include buyer_note when the reason requires one, and fulfillment_id from the preview so a line that shipped in more than one parcel is unambiguous. Send the outcome the buyer chose as requested_resolution_type, one of the line's allowed_resolution_types. There is no /v1/me route to change it afterward.
curl -X POST https://api.withflintpay.com/v1/me/returns \
-H "Authorization: Bearer flint_cses_example" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: ret-ord_1kmn0aExample-li_1kmn0aExample" \
-d '{
"order_id": "ord_1kmn0aExample",
"line_items": [
{
"order_line_item_id": "li_1kmn0aExample",
"fulfillment_id": "ful_1kmn0aExample",
"requested_quantity": 1,
"return_reason_id": "rrsn_1T6HXAX0CEXP6YA5K1T392KJE6",
"buyer_note": "The handle cracked in the box.",
"requested_resolution_type": "refund"
}
]
}'
Idempotency-Key is required. Generate it once when the buyer submits and send the same key on a retry, so a double click or a lost response returns the same Return instead of creating a second one.
The response is 201 with the Return in requested, initiated_by: "buyer", and decision_status: "pending". Each line carries the item's frozen name, SKU, and image, so your Return page needs no call to Orders. What happens next depends on your policy:
- Automatic approval. Flint decides the Return shortly after create and sends
return.decision_recorded. Under an automatic resolution mode it also creates and confirms arefund,store_credit, orno_monetary_actionresolution. When the policy lets the buyer choose the outcome, Flint approves only a line that carries an allowedrequested_resolution_type, which is why you send it at create. An exchange or replacement resolution always waits for your staff. - Manual review. The Return stays
requesteduntil your staff decide it.
The buyer can't approve, receive, or resolve their own Return. Everything after create is your policy, your staff, or your warehouse.
Let the buyer compare outcomes#
Refund or exchange is a real choice, and buyers choose badly when the numbers are guesses. Once the Return exists, preview each outcome you want to show and let Flint price it:
curl -X POST https://api.withflintpay.com/v1/me/return-previews \
-H "Authorization: Bearer flint_cses_example" \
-H "Content-Type: application/json" \
-d '{
"mode": "resolution",
"resolution": {
"return_id": "ret_1kmn0aExample",
"resolution_type": "exchange",
"line_items": [
{ "return_line_item_id": "retli_1kmn0aExample", "quantity": 1 }
],
"replacement_line_items": [
{ "type": "variant", "variant_id": "var_1kmn0aExample", "quantity": 1 }
]
}
}'
resolution_type must be one the line allows. For store_credit, leave out replacement_line_items. For an exchange, a buyer can pick only catalog merchandise: each replacement is type: "variant" with variant_id or type: "bundle" with bundle_id, plus quantity. A replacement's name, description, sku, or unit_price_money, and the resolution's pricing_basis or adjustments, are for API keys and return 400 INVALID_REQUEST with detail code NOT_ALLOWED. A type the line doesn't allow returns 409 ACTION_NOT_ALLOWED with reason not_offered.
The response's data.resolution has what each option means for the buyer: buyer_refund_amount_money to refund, buyer_payment_amount_money to collect, credit_adjustment_money as store credit, and deduction_money for fees, with returned_total_money and replacement_total_money behind them. based_on_return_version is the Return version it was priced against, so you can tell a preview from before the Return changed. A preview approves, reserves, and starts nothing.
Return resolutions explains each outcome and when its money moves.
Return labels and tracking#
Return shipping uses the same shipment resource as outbound delivery, with direction: "return". Flint doesn't buy labels: your backend gets one from your carrier or 3PL, then records it with an API key once the Return is decided. Wait for return.decision_recorded. Before a decision, or after the Return is canceled or completed, creating the shipment returns 409 ACTION_NOT_ALLOWED.
Create the shipment under the fulfillment the item shipped in, the line's fulfillment_id, and list the Return lines it carries:
curl -X POST https://api.withflintpay.com/v1/fulfillments/ful_1kmn0aExample/shipments \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: ret_1kmn0aExample-shipment" \
-d '{
"direction": "return",
"return_id": "ret_1kmn0aExample",
"return_line_items": [
{ "return_line_item_id": "retli_1kmn0aExample", "quantity": 1 }
]
}'
A return shipment needs return_id and at least one line, and can't create packages inline. Each line must belong to that Return and fulfillment and appear once (400 INVALID_REQUEST on return_line_items otherwise). Its quantity can't exceed what the buyer still has to send back, the line's return_required_quantity less what other return shipments declare (409 LIMIT_EXCEEDED). direction is fixed once created.
Then add the parcel with its label and tracking. A return package starts in created and names which of the shipment's lines it carries:
curl -X POST https://api.withflintpay.com/v1/shipments/shp_1kmn0aExample/packages \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: ret_1kmn0aExample-package" \
-d '{
"status": "created",
"carrier": "usps",
"tracking_number": "9400100000000000000000",
"label_url": "https://labels.example.com/ret_1kmn0aExample.pdf",
"external_system": "returns_portal",
"return_line_items": [
{ "return_line_item_id": "retli_1kmn0aExample", "quantity": 1 }
]
}'
label_url must be an absolute HTTPS URL, and one that isn't Flint's needs external_system. A return package can't be created as shipped and takes no items.
The buyer reads it with their session: GET /v1/me/shipments?return_id=ret_1kmn0aExample finds the return shipment, and GET /v1/me/packages?shipment_id=shp_1kmn0aExample returns the parcel's label_url, tracking_number, and tracking_url. The buyer's package reads include return labels only, never your outbound ones.
When the carrier scans the parcel, send { "action": "mark_shipped" } to POST /v1/packages/{package_id}/transitions. That sets the shipment's handed_off_at and counts the parcel toward each line's handed_off_quantity. A line whose release_timing is after_handoff releases its refund then, on drop-off rather than on arrival. Arrival and inspection are in Receiving and inspecting.
Track it back#
Read the Return with GET /v1/me/returns/{return_id}, or list the buyer's Returns with GET /v1/me/returns. Three fields tell the buyer where they stand:
buyer_actionslistswithdraw,ship_items, andpay_balance, in that order, each with whether the buyer can take it now.ship_itemsis required while something waits to be sent, due by the earliest deadline.pay_balanceis required while a resolution waits for the buyer's payment.handoff_requirementslists what the buyer has to send, where (destination), anyinstructions, and by when (expires_at). A requirement ispendinguntil the buyer starts sending, thenin_progress. It leaves the array once satisfied, so an empty array means nothing is waiting on the buyer.completion_blockerslists what still stands between the Return and completion that the buyer can act on.
A buyer who changes their mind withdraws the request while it is still requested:
curl -X POST https://api.withflintpay.com/v1/me/returns/ret_1kmn0aExample/cancel \
-H "Authorization: Bearer flint_cses_example" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: ret_1kmn0aExample-withdraw" \
-d '{ "reason": "buyer_request" }'
Once the Return is decided, withdrawing returns 409 ACTION_NOT_ALLOWED. Offer it only while withdraw is available.
What a buyer's read leaves out#
A customer session reads a narrower Return than your API key does, because the buyer can't receive, inspect, or approve their own Return:
supported_actionsis["cancel"]while the buyer can withdraw, and empty otherwise. Lines have none.completion_blockerskeeps onlyhandoff_pending,resolution_not_selected,resolution_requires_action, andresolution_failed, plusresolution_pendingfor a resolution the buyer can pay now. Decision, warehouse, and other merchant work is left out, so a Return waiting on you doesn't read as stuck to the buyer.metadatais always empty, and merchant-only fields are removed.
Webhooks for your own pages#
Drive emails and page refreshes from webhooks rather than polling. Merchant webhooks carry the full Return with an empty buyer_actions, so read the buyer's view with the session when you render for them.
When the buyer owes money#
An exchange for something more expensive leaves a balance, and the buyer pays it in a checkout session. While one can be collected, the Return's pay_balance action is available and required, and its pay_balance.return_resolution_ids lists the resolutions to pay, oldest first. Read each with GET /v1/me/return-resolutions/{return_resolution_id} to show buyer_payment_amount_money, then create its checkout:
curl -X POST https://api.withflintpay.com/v1/me/return-resolutions/retres_1kmn0aExample/checkout-sessions \
-H "Authorization: Bearer flint_cses_example" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: retres_1kmn0aExample-checkout" \
-d '{ "return_url": "https://cedarandstone.com/account/returns/ret_1kmn0aExample" }'
The route returns 201 when it creates the session and 200 when it returns the open one again. Redirect the buyer to data.url, or send "surface": "embedded" to take the payment on your own page. return_url must be an address of your customer account. Pay a Return balance covers the action and its rules, and Return resolutions covers what happens when the payment fails.
