Returns Endpoints

This document covers the returns endpoints: listing and reading return requests for your orders, approving or declining a return, confirming receipt and inspection, and issuing the refund or store credit that closes the return. Buyer-facing return rights are governed by the Returns and Refunds Policy; seller obligations are governed by the Return and Refund Policy: Sellers (Return and Refund Policy — Sellers). This document states the endpoint mechanics.

Access through the developer API is issued by the Company and is limited by seller type: manufacturer and supplier accounts receive API access for importing data, under the Developer Agreement and the API Access Tiers. Nothing in this document grants broader access.

Endpoints

Method	Path	Purpose
GET	`/returns`	List returns for your orders, newest first, paginated
GET	`/returns/{id}`	Read one return, with lines, inspection, and refund state
POST	`/returns/{id}/approve`	Approve a requested return and issue return instructions
POST	`/returns/{id}/decline`	Decline a requested return, with a reason
POST	`/returns/{id}/receive`	Confirm the returned goods arrived and record inspection
POST	`/returns/{id}/refund`	Issue the refund or store credit for an inspected return

All paths are relative to the base URL https://www.aapawz.com/api. Collections paginate as specified in Pagination and Filtering (Pagination & Filtering). Refund writes accept an Idempotency-Key header (Idempotency Keys) and shall carry one: a retried refund request must never pay twice.

The return object

{
  "id": "ret_47pn83",
  "return_number": "RMA-2026-00319",
  "order_id": "ord_64kx20",
  "order_number": "AAP-2026-104821",
  "status": "approved",
  "reason": "changed_mind",
  "requested_at": "2026-10-15T11:04:52Z",
  "approved_at": "2026-10-15T13:20:10Z",
  "received_at": null,
  "completed_at": null,
  "lines": [
    {
      "id": "rline_01",
      "order_line_id": "line_01",
      "product_id": "prod_8f3ka9",
      "seller_sku": "ACME-DOGFOOD-10LB",
      "quantity_requested": 1,
      "quantity_received": null,
      "quantity_approved": null,
      "condition": null,
      "disposition": null
    }
  ],
  "refund": null
}

Returns are opened by the buyer, or by the Company on the buyer's behalf; sellers do not open returns against their own orders through the API. Field and status definitions are in Data Types and Enums.

The return lifecycle

Status	Meaning
`requested`	The buyer has asked to return; awaiting your decision.
`approved`	Approved; return instructions and label issued to the buyer.
`awaiting_package`	Approved; the buyer has not yet handed over the package.
`in_transit`	The return package is on its way.
`received`	The package arrived; awaiting inspection.
`inspection`	Inspection is under way.
`approved_for_refund`	Inspection passed; the refund may be issued.
`rejected`	Declined, or inspection failed; no refund is due.
`restocked`	Approved goods are back in sellable stock.
`refunded`	The refund or store credit has been issued.
`exchanged`	Closed by a replacement shipment instead of a refund.
`completed`	Closed.
`cancelled`	Withdrawn by the buyer or the Company.

Status moves in this order. There are two distinct approvals: approved (the goods are expected back) and approved_for_refund (inspection has decided money may move). A return cannot move to refunded without passing inspection, except where the Returns and Refunds Policy directs a refund without return of the goods.

Approving, declining, receiving

Approve with POST /returns/{id}/approve; the response carries the updated return with return_label_url where a prepaid label applies. Decline with a reason the buyer will see

{
  "reason": "outside_window",
  "note": "This item was delivered more than 60 days ago."
}

On receipt, record what actually arrived, line by line

{
  "lines": [
    {
      "id": "rline_01",
      "quantity_received": 1,
      "quantity_approved": 1,
      "condition": "unopened",
      "disposition": "restock"
    }
  ]
}

condition is one of unopened, opened_unused, used, damaged. disposition is one of restock, refurbish, dispose. Recording a restock disposition does not itself change stock: put approved goods back on hand with an inventory adjustment (Inventory Endpoints), so the movement history stays complete.

Issuing the refund

POST /returns/ret_47pn83/refund
Authorization: Bearer <your-api-key>
Idempotency-Key: refund-ret_47pn83
Content-Type: application/json

{
  "method": "original_payment",
  "amount": "24.99",
  "currency": "USD"
}

method is original_payment or store_credit. A return references exactly one of the two, never both.
amount may not exceed the unrefunded balance of the original payment (Payments Endpoints). Partial refunds: for fewer lines, or less than the line value where inspection reduced the approved quantity: are supported.
The refund object returned carries id, status (pending, completed, failed), amount, currency, method, and processed_at. Refund state also arrives as the return.refunded event (Webhook Event Schemas).

Events and errors

Subscribe to return.requested, return.approved, return.received, and return.refunded (Webhook Event Schemas) to drive warehouse and accounting workflows. The underlying order is read under Orders Endpoints and its shipment under Fulfillment Endpoints.

Status	Code	Cause
404	`not_found`	No return with that `id` exists in your account
409	`invalid_state`	The action is not available in the return's current status
422	`amount_exceeds_balance`	`amount` exceeds the payment's unrefunded balance
422	`validation_failed`	A required field is missing or a value is not allowed

Error bodies follow Error Codes.

Fulfillment Endpoints

Payments Endpoints