Decline a Return

Endpoint

POST /v1/returns/:return_id/decline

Declines a return. The status changes to declined. After a return is declined, a new return can be created for the same order.

Request Parameters

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

Request Body

Field	Type	Required	Description
declined_reason	string	Yes	Why the return is declined

Request

curl --request POST \
  --url 'https://api.biteship.com/v1/returns/<<RETURN_ID>>/decline' \
  --header 'authorization: <<YOUR_API_KEY>>' \
  --header 'content-type: application/json' \
  --data '{
    "declined_reason": "Item is not eligible for return"
  }'

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": "declined",
  "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": "declined",
      "description": "Return request was declined by seller. Reason: Item is not eligible for return",
      "timestamp": "2026-09-01T06:00:00.000Z",
      "user_id": "5dd599ebdefcd4158eb84700",
      "user_name": "Seller Shop"
    }
  ],
  "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": 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-01T06:00:00.000Z",
  "reviewer_id": "5dd599ebdefcd4158eb84700",
  "reviewer_name": "Seller Shop",
  "reviewed_at": "2026-09-01T06:00:00.000Z",
  "declined_reason": "Item is not eligible for return",
  "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
403	40300000	The return does not belong to your account
404	40400000	The return is not found
422	42200000	The return is already declined, or it has an active return shipment