Create a Return

Endpoint

POST /v1/returns

Creates a return request against a delivered order. Requires return tracking (Free+). Production keys count against your monthly Returns quota (no overage). See Plans & limits.

return_items[].name must match an item name on the original order. returned_quantity cannot exceed the ordered quantity. Provide one reason object per returned unit (reasons.length must equal returned_quantity).

If origin is sent, name, phone, and address are required, plus at least one location anchor (address_id, area_id, postal_code, or coordinate). Location priority is address_id → area_id → coordinate → postal_code.

Example request

curl --request POST \
  --url https://api.biteship.com/v1/returns \
  --header 'authorization: <<YOUR_API_KEY>>' \
  --header 'content-type: application/json' \
  --data '{
    "original_order_id": "5dd599ebdefcd4158eb8470b",
    "reference_id": "RET-1001",
    "origin": {
      "name": "John Doe",
      "phone": "081234567890",
      "address": "Lebak Bulus MRT",
      "postal_code": 12310,
      "note": "Near the gas station"
    },
    "return_items": [
      {
        "name": "Black L",
        "returned_quantity": 1,
        "reasons": [
          {
            "reason_code": "wrong_size",
            "note": "Ordered L, received M"
          }
        ]
      }
    ]
  }'

Body

Field	Type	Required	Description
original_order_id	string	Yes	Delivered order ID.
origin	object	Yes	Pickup of the return package (typically the buyer).
origin.name	string	Yes	Contact name.
origin.phone	string	Yes	Contact phone.
origin.address	string	Yes	Street address.
origin.address_id	string	No	Saved location ID.
origin.area_id	string	No	Maps area ID.
origin.postal_code	integer	No	Postal code.
origin.coordinate.latitude	number	No	Latitude.
origin.coordinate.longitude	number	No	Longitude.
origin.note	string	No	Pickup note.
destination	object	No	Where the return is sent (typically the seller). Defaults to the original order origin. Same shape as origin.
return_items	array	Yes	Non-empty. Item names must be unique in the request.
return_items[].name	string	Yes	Must match an item name on the original order.
return_items[].returned_quantity	integer	Yes	Units to return. Must be ≤ ordered quantity.
return_items[].reasons	array	Yes	One entry per returned unit.
return_items[].reasons[].reason_code	string	Yes	See reason codes below.
return_items[].reasons[].reason_value	string	If other	Custom label. Required when reason_code is other. Ignored for other codes.
return_items[].reasons[].note	string	No	Extra detail.
reference_id	string	No	Your reference. Must be unique among non-declined returns. Defaults to the return ID.

Reason codes

reason_code	Label
wrong_item	Wrong Item
wrong_size	Wrong Size
defect	Defect
missing_part	Missing Part
expired	Expired
other	Other (reason_value required)

Response (201)

{
  "success": true,
  "code": 20100000,
  "id": "66f0a1b2c3d4e5f678901234",
  "user_id": "5dd5...",
  "organization_id": null,
  "original_order": {
    "id": "5dd599ebdefcd4158eb8470b",
    "courier_code": "jne",
    "courier_service_code": "reg",
    "waybill_id": "JNE1234567890",
    "origin": {},
    "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",
      "sku": null,
      "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,
  "reference_id": "RET-1001",
  "created_at": "2026-09-01T04:00:00.000Z",
  "updated_at": "2026-09-01T04:00:00.000Z"
}