Skip to content

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.

A buyer-initiated return by mailResponse
Buyer's browserYour backendFlintopen an order, choose ReturnPOST /v1/me/return-previews (eligibility)can_buyer_request, reasons, allowed outcomesPOST /v1/me/returnsReturn in requested, initiated_by buyerreturn.decision_recorded, from your policy or your reviewreturn shipment and package with your carrier's label (API key)GET /v1/me/packages for the label and trackinglabel, then progress until return.completed
  1. Buyer's browser sends open an order, choose Return to Your backend
  2. Your backend sends POST /v1/me/return-previews (eligibility) to Flint
  3. Flint returns can_buyer_request, reasons, allowed outcomes to Your backend
  4. Your backend sends POST /v1/me/returns to Flint
  5. Flint returns Return in requested, initiated_by buyer to Your backend
  6. Flint sends return.decision_recorded, from your policy or your review to Your backend
  7. Your backend sends return shipment and package with your carrier's label (API key) to Flint
  8. Your backend sends GET /v1/me/packages for the label and tracking to Flint
  9. 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/meAPI key on /v1/returns
initiated_bybuyerintegration
Return policyEnforced: an active policy must cover each line and leave the quantity eligibleRecorded but not enforced: a line no policy covers, or one it excludes, waits for your review
Return reasonsActive reasons that apply to the item's catalog categoriesAny active reason
Request fieldsorder_id and line_items onlyAlso external_reference_id and metadata
Resolution typeChosen at create with requested_resolution_typeCan 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
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:

JSON
{
  "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, and modifiers are frozen from the order.
  • Whether to show a return button. Use can_buyer_request. It is true exactly when POST /v1/me/returns would accept the line at its eligible_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 from status yourself.
  • The deadline. expires_at is when the window closes.
  • The reasons. Offer suggested_return_reasons as 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. When is_note_required is true, ask for a note.
  • The outcomes. allowed_resolution_types lists what the buyer can ask for.
  • Fees. policy_adjustment_proposals lists 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 eligibility
  • eligible_under_policy
    A policy covers the item and some quantity can come back.
  • no_matching_policy
    No active policy covers the item, so only your staff can start a return for it.
  • policy_ineligible
    A policy excludes the item. ineligibility_reason says why.
  • return_window_expired
    The window ended at expires_at.
  • quantity_unavailable
    Less than the requested quantity can still come back.
  • reason_not_allowed
    The reason you sent isn't active or doesn't apply to the item.
  • resolution_not_allowed
    The outcome you sent isn't one the policy allows.
  • policy_conflict
    Two policies with the same priority match, so your staff decide.
  • manual_review_required
    The policy sends requests for this item to your staff for a decision.

ineligibility_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
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 a refund, store_credit, or no_monetary_action resolution. When the policy lets the buyer choose the outcome, Flint approves only a line that carries an allowed requested_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 requested until 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.

  • HTTP 409
    Reason not_offered: a line isn't one the buyer can request, and param names it, such as line_items[0] or line_items[0].requested_resolution_type. No policy covers it, it's ineligible, the reason doesn't apply to it, or the policy doesn't allow the outcome. Run the preview again and show its reason_message, or tell the buyer how to contact you.
  • HTTP 400
    Detail code REQUIRED on line_items[0].fulfillment_id: the line shipped in more than one fulfillment, and details[0].selectable_resources lists them. Send one. Detail code NOT_ALLOWED: the body has a field only an API key can send, such as external_reference_id or metadata, and param names it. Remove it. A missing buyer_note for a reason that requires one also returns INVALID_REQUEST.
  • HTTP 404
    The order isn't this buyer's, or return_reason_id names a reason that is inactive or archived. Read the order and the preview again.

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
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
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
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_actions lists withdraw, ship_items, and pay_balance, in that order, each with whether the buyer can take it now. ship_items is required while something waits to be sent, due by the earliest deadline. pay_balance is required while a resolution waits for the buyer's payment.
  • handoff_requirements lists what the buyer has to send, where (destination), any instructions, and by when (expires_at). A requirement is pending until the buyer starts sending, then in_progress. It leaves the array once satisfied, so an empty array means nothing is waiting on the buyer.
  • completion_blockers lists 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
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_actions is ["cancel"] while the buyer can withdraw, and empty otherwise. Lines have none.
  • completion_blockers keeps only handoff_pending, resolution_not_selected, resolution_requires_action, and resolution_failed, plus resolution_pending for 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.
  • metadata is 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
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.

Next steps#

Return policies and reasonsDecide what buyers can return, and make the decision automatic.Return resolutionsWhat the buyer gets for a Return, and when the money moves.Receiving and inspectingThe warehouse side of the parcel you labeled.Build your own customer accountThe rest of the account around the same customer session.

Was this helpful?