Returns

This guide covers handling returns through the API: the lifecycle from a buyer's request to the refund landing, what your integration does at each stage, and how denials and exceptions stay fair and auditable. Endpoint detail is in Returns Endpoints. The rules your integration applies: windows, condition requirements, who pays return shipping: are set by the Returns and Refunds Policy. Your integration applies those rules; it does not invent them, soften them, or hardcode them from memory.

Goal and prerequisites

Goal: every return moves through named states the buyer can see: requested, authorized, in transit back, received, refunded (or denied, with the reason and the appeal path): and every refund is issued once, to the original payment method, inside the service levels.

Prerequisites: orders flowing into your systems (Orders), and the current return window and conditions read from the Returns and Refunds Policy: read them from the policy when you build and when they change, so a policy change takes effect in your integration as a configuration change, not a code change. Response and refund speeds are measured under the Service Level Requirements.

The lifecycle

1. Request. The buyer states what is being returned and why, and what they want: refund, replacement, or store credit where offered. Your integration registers the request against the order's lines.
2. Validation. The request is checked against the policy: inside the window, eligible item, eligible reason, in the condition the policy requires. Validation uses the order's record: what was bought, when, at what price: not the buyer's summary of it.
3. Authorization. A valid request is authorized: the buyer receives the authorization reference, the return instructions, and a return label where the policy places return shipping on the seller.
4. Return shipment. The buyer ships the item back. The return's state reflects the shipment's progress so the buyer can follow it.
5. Receipt. Receipt is confirmed: carrier delivery scan plus your check-in of the item and its condition. Receipt starts the refund clock; it does not wait for a weekly batch.
6. Refund. The refund is issued through Returns Endpoints against the original payment, for the amount the policy and the item's condition determine, and the return closes. How refunds settle is covered in Payments.

Each stage is a state on the return, visible to the buyer. A return the buyer cannot track is a return the buyer disputes.

Money rules for returns

• Issue every refund with an Idempotency-Key(Idempotency Keys). A retried refund request must return the original result, never issue a second refund.
• Refunds are new records, never edits. The original sale stands as a fact of history; the refund is a new, offsetting fact linked to it. Never adjust, rewrite, or delete the original order or payment to make a return "net out": accounting, disputes, and audits all depend on both records existing.
• Partial refunds are normal: one line of several returned, a restocking amount the policy permits, a shipping adjustment. State the amount and the reason on the refund so the buyer and your books read the same number.
• Refund to the original payment method wherever the API supports it. That is what the buyer expects and what the dispute process assumes.

Denials

Not every request is valid, and a denial handled well is part of the service

• Deny with the specific policy ground cited: out of window, final sale, condition: recorded on the return, in words the buyer can act on.
• Make the appeal path visible on the denial itself. A buyer who cannot find the appeal files a payment dispute instead; the dispute path is governed by the Dispute Resolution Policy, and standing consequences for mishandled returns sit in the Seller Enforcement Policy.
• Never deny by silence. An unanswered request ages against your service levels and converts to an escalation.

Exceptions

• Lost return shipment: the buyer shipped it; the carrier lost it. Follow the policy's allocation of that risk; do not hold the refund hostage to the carrier's investigation where the policy gives the buyer the benefit.
• Item received in worse condition than claimed: record the condition with evidence at check-in, adjust or deny under the policy, and tell the buyer what was found and what follows.
• Refund issued but not received: trace it through Payments Endpoints by its identifiers before telling the buyer to wait; refunds have processing time, and the trace tells you whether this one is inside it.

Every exception gets the same treatment as the standard path: a named state, a timestamp, and a defined next step. An exception without a next step is a case that never closes.

Failure handling

• Refund call rejected: read the error code (Error Codes). Common causes: the return is not in a state that accepts a refund (receipt not yet confirmed), the amount exceeds the refundable remainder on the payment, or the idempotency key was reused with a different amount: which your integration must treat as its own bug and investigate, never override.
• State drift: if your system shows a return the Platform does not (or the reverse), re-read through Returns Endpoints and adopt the Platform's state; missed events (Webhooks) are the usual cause.

What to build

• Seller-side tooling: the queue is open requests sorted by age against the service-level clock; the actions are authorize, deny with grounds, issue label, confirm receipt, refund. Every action is policy-checked before it executes.
• Buyer-facing views: show the return's state honestly, with the next step and its expected timing; on a denial, show the grounds and the appeal.
• Reporting: return rate by product and by reason is the quality signal your catalog decisions should run on: feed it back into Catalog reviews.

Returns done well are a feature buyers choose sellers by; returns done badly are churn and disputes.