Retrieve Returns

Listing and retrieving returns require the return page entitlement (Grow+).

List returns

Endpoint

GET /v1/returns

Cursor pagination by created_at (newest first). Default limit is 10.

Query	Type	Description
status_in	string	Comma-separated statuses, e.g. requested,in_review,approved.
has_return_order	string	true or false. Filter by whether a return shipment exists.
cursor	string	ISO-8601 created_at cursor. Omit for the first page.
limit	integer	Page size. Default 10.

next_cursor is older returns; prev_cursor is newer returns.

Example

GET /v1/returns?status_in=requested,in_review&limit=20

Response

{
  "success": true,
  "cursor": "2026-09-01T12:00:00.000Z",
  "prev_cursor": null,
  "next_cursor": "2026-08-20T08:00:00.000Z",
  "returns": []
}

Get a return

Endpoint

GET /v1/returns/:id

Please assume fields may be null. Pass with_return_order=true to embed the reverse order after confirm.

Example

GET /v1/returns/66f0a1b2c3d4e5f678901234?with_return_order=true

Response

{
  "success": true,
  "code": 20000000,
  "id": "66f0a1b2c3d4e5f678901234",
  "user_id": "5dd5...",
  "organization_id": null,
  "original_order": {
    "id": "5dd599ebdefcd4158eb8470b",
    "courier_code": "jne",
    "courier_service_code": "reg",
    "waybill_id": "JNE1234567890",
    "origin": {
      "name": "Amir",
      "phone": "088888888888",
      "address": "Plaza Senayan...",
      "area_id": null,
      "postal_code": 10270,
      "country_name": "Indonesia",
      "country_code": "ID",
      "administrative_division_level1_name": "DKI Jakarta",
      "administrative_division_level2_name": "Jakarta Selatan",
      "administrative_division_level3_name": null,
      "administrative_division_level4_name": null,
      "coordinate": { "latitude": -6.2253114, "longitude": 106.7993735 },
      "note": null
    },
    "destination": {},
    "created_at": "2026-08-01T04:00:00.000Z",
    "delivered_at": "2026-08-04T10:00:00.000Z"
  },
  "return_items": [
    {
      "id": "...",
      "name": "Black L",
      "description": "White Shirt",
      "category": "fashion",
      "sku": null,
      "weight": 200,
      "height": 10,
      "length": 10,
      "width": 10,
      "value": 165000,
      "ordered_quantity": 1,
      "returned_quantity": 1,
      "reasons": [
        {
          "reason_code": "wrong_size",
          "reason_value": "Wrong Size",
          "note": "Ordered L, received M"
        }
      ]
    }
  ],
  "status": "requested",
  "history": [
    {
      "status": "requested",
      "description": "Return request initiated by buyer.",
      "timestamp": "2026-09-01T04:00:00.000Z",
      "user_id": "5dd5...",
      "user_name": "Amir"
    }
  ],
  "origin": {},
  "destination": {},
  "return_order_id": null,
  "return_order_waybill_id": null,
  "return_order_courier_code": null,
  "return_order_courier_service_code": null,
  "return_order_created_at": null,
  "created_at": "2026-09-01T04:00:00.000Z",
  "updated_at": "2026-09-01T04:00:00.000Z",
  "reviewer_id": null,
  "reviewer_name": null,
  "reviewed_at": null,
  "declined_reason": null,
  "delivered_at": null,
  "reference_id": "RET-1001"
}