Confirm a Return

Endpoint

POST /v1/returns/:return_id/confirm

Books the return shipment and creates it as an order. The status changes to confirmed, and the return_order_* fields are filled.

The return must be approved. You can also confirm again when the previous return shipment ended as cancelled, courier_not_found, rejected, returned, or disposed.

Use Rates to choose courier_company and courier_type first.

Request Parameters

Parameter	Type	Required	Description
return_id	string	Yes	Return ID (path parameter)

Request Body

Origin and destination fields you leave out use the values stored on the return.

Field	Type	Required	Description
courier_company	string	Yes	Courier code, for example jne
courier_type	string	Yes	Courier service code, for example reg
delivery_type	string	Yes	now or scheduled
delivery_date	string	If scheduled	YYYY-MM-DD
delivery_time	string	If scheduled	HH:mm
origin_collection_method	string	No	pickup or drop_off. Default pickup
courier_insurance	integer	No	Insured value in IDR. Cannot be more than the total value of the returned items
order_note	string	No	Note on the return shipment
metadata	object	No	Your own data, saved on the return shipment
origin_contact_name	string	No	Pickup contact name
origin_contact_phone	string	No	Pickup contact phone
origin_address	string	No	Pickup address
origin_note	string	No	Pickup note
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	object	No	{ "latitude", "longitude" }
destination_contact_name	string	No	Destination contact name
destination_contact_phone	string	No	Destination contact phone
destination_address	string	No	Destination address
destination_note	string	No	Destination note
destination_address_id	string	No	Saved location ID
destination_area_id	string	No	Maps area ID
destination_postal_code	integer	No	Postal code
destination_coordinate	object	No	{ "latitude", "longitude" }

Request

curl --request POST \
  --url 'https://api.biteship.com/v1/returns/<<RETURN_ID>>/confirm' \
  --header 'authorization: <<YOUR_API_KEY>>' \
  --header 'content-type: application/json' \
  --data '{
    "courier_company": "jne",
    "courier_type": "reg",
    "delivery_type": "now",
    "origin_collection_method": "pickup",
    "courier_insurance": 165000,
    "order_note": "Return pickup"
  }'

Response

Response

{
  "success": true,
  "code": 20000000,
  "id": "66f0a1b2c3d4e5f678901234",
  "user_id": "5dd599ebdefcd4158eb84700",
  "organization_id": null,
  "original_order": {
    "id": "5dd599ebdefcd4158eb8470b",
    "courier_code": "jne",
    "courier_service_code": "reg",
    "waybill_id": "WYB-0987654321",
    "origin": {
      "name": "Seller Shop",
      "phone": "081234567891",
      "address": "Plaza Senayan, Jl. Asia Afrika No. 8",
      "area_id": null,
      "postal_code": 10270,
      "country_name": "Indonesia",
      "country_code": "ID",
      "administrative_division_level1_name": "DKI Jakarta",
      "administrative_division_level2_name": "Jakarta Pusat",
      "administrative_division_level3_name": "Tanah Abang",
      "administrative_division_level4_name": null,
      "coordinate": {
        "latitude": -6.2253114,
        "longitude": 106.7993735
      },
      "note": null
    },
    "destination": {
      "name": "John Doe",
      "phone": "081234567890",
      "address": "Lebak Bulus MRT",
      "area_id": null,
      "postal_code": 12310,
      "country_name": "Indonesia",
      "country_code": "ID",
      "administrative_division_level1_name": "DKI Jakarta",
      "administrative_division_level2_name": "Jakarta Selatan",
      "administrative_division_level3_name": "Cilandak",
      "administrative_division_level4_name": null,
      "coordinate": {
        "latitude": -6.2893,
        "longitude": 106.7743
      },
      "note": "Near the gas station"
    },
    "created_at": "2026-08-01T04:00:00.000Z",
    "delivered_at": "2026-08-04T10:00:00.000Z"
  },
  "return_items": [
    {
      "id": "66f0a1b2c3d4e5f678901235",
      "name": "Black L",
      "description": "White Shirt",
      "category": "fashion",
      "sku": "SHIRT-BLK-L",
      "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": "confirmed",
  "history": [
    {
      "status": "requested",
      "description": "Return request initiated by buyer.",
      "timestamp": "2026-09-01T04:00:00.000Z",
      "user_id": "5dd599ebdefcd4158eb84700",
      "user_name": "John Doe"
    },
    {
      "status": "in_review",
      "description": "Return request is being reviewed by seller.",
      "timestamp": "2026-09-01T05:00:00.000Z",
      "user_id": "5dd599ebdefcd4158eb84700",
      "user_name": "Seller Shop"
    },
    {
      "status": "approved",
      "description": "Return request was approved by seller.",
      "timestamp": "2026-09-01T06:00:00.000Z",
      "user_id": "5dd599ebdefcd4158eb84700",
      "user_name": "Seller Shop"
    },
    {
      "status": "confirmed",
      "description": "Return order was created by seller. Courier: jne. Waybill: WYB-1234567890",
      "timestamp": "2026-09-01T07:00:00.000Z",
      "user_id": "5dd599ebdefcd4158eb84700",
      "user_name": "Seller Shop",
      "return_order_id": "66f1b2c3d4e5f67890123456",
      "return_order_waybill_id": "WYB-1234567890",
      "return_order_courier_code": "jne",
      "return_order_courier_service_code": "reg"
    }
  ],
  "origin": {
    "name": "John Doe",
    "phone": "081234567890",
    "address": "Lebak Bulus MRT",
    "area_id": null,
    "postal_code": 12310,
    "country_name": "Indonesia",
    "country_code": "ID",
    "administrative_division_level1_name": "DKI Jakarta",
    "administrative_division_level2_name": "Jakarta Selatan",
    "administrative_division_level3_name": "Cilandak",
    "administrative_division_level4_name": null,
    "coordinate": {
      "latitude": -6.2893,
      "longitude": 106.7743
    },
    "note": "Near the gas station"
  },
  "destination": {
    "name": "Seller Shop",
    "phone": "081234567891",
    "address": "Plaza Senayan, Jl. Asia Afrika No. 8",
    "area_id": null,
    "postal_code": 10270,
    "country_name": "Indonesia",
    "country_code": "ID",
    "administrative_division_level1_name": "DKI Jakarta",
    "administrative_division_level2_name": "Jakarta Pusat",
    "administrative_division_level3_name": "Tanah Abang",
    "administrative_division_level4_name": null,
    "coordinate": {
      "latitude": -6.2253114,
      "longitude": 106.7993735
    },
    "note": null
  },
  "return_order_id": "66f1b2c3d4e5f67890123456",
  "return_order_waybill_id": "WYB-1234567890",
  "return_order_courier_code": "jne",
  "return_order_courier_service_code": "reg",
  "return_order_created_at": "2026-09-01T07:00:00.000Z",
  "created_at": "2026-09-01T04:00:00.000Z",
  "updated_at": "2026-09-01T07:00:00.000Z",
  "reviewer_id": "5dd599ebdefcd4158eb84700",
  "reviewer_name": "Seller Shop",
  "reviewed_at": "2026-09-01T06:00:00.000Z",
  "declined_reason": null,
  "delivered_at": null,
  "reference_id": "RET-1001"
}

Errors

HTTP	Code	When
400	40000000	The request body is invalid. details lists each invalid field and the reason
400	40002020	The origin or destination area cannot be found. Check the postal code or coordinate
403	40300000	The return does not belong to your account
404	40400000	The return is not found
422	42200000	The return is not approved, or its previous return shipment has not ended
422	42200000	courier_insurance is more than the total value of the returned items
422	42200000	The origin or destination location is incomplete or not found
500	50000000	The return shipment could not be created