Skip to main content

Overview

Return API Introduction

Return objects manage buyer-initiated returns of a delivered order. You create a return request, review it, then confirm a reverse shipment (the return order) back to the seller.

Creating a return requires return tracking, which is included on Free and above. Listing, retrieving, and the review / approve / decline / confirm / cancel flow require the return page entitlement (Grow and above). Monthly return quota: Free 10, Grow 200, Scale 1,000, Enterprise unlimited. See Plans & limits.

Endpoints
POST   /v1/returns
GET    /v1/returns
GET    /v1/returns/:id
POST   /v1/returns/:id/review
POST   /v1/returns/:id/approve
POST   /v1/returns/:id/decline
POST   /v1/returns/:id/confirm
POST   /v1/returns/:id/cancel

Buyers can also submit a return from the hosted return page (https://return.biteship.com). Those public routes are not merchant API-key endpoints.

Status flow​

Typical path: create → review → approve → confirm. After confirm, shipment statuses follow the Order status flow on the nested return order.

StatusDescription
requestedReturn created. Waiting for seller review.
in_reviewSeller marked the request as in review.
approvedSeller approved. Ready to book a return shipment.
declinedSeller declined. Include declined_reason.
confirmedReturn order (shipment) created. return_order_id and waybill are set.
deliveredReturn package delivered to the seller (copied from the return order).
cancelledReturn order cancelled after confirm.

requested → in_review → approved or declined → confirmed → delivered or cancelled.

Rules​

  • The original order must belong to your account and already be delivered.
  • Only one active return is allowed per original order (a declined return does not block a new request).
  • Origin is the pickup of the return package (typically the buyer). Destination is where the package is sent (typically the seller). If you omit destination on create, it defaults to the original order's origin.
  • Confirming a return creates a reverse order. That return shipment counts against your returns quota, not your orders quota.