Review, confirm, and cancel

These actions require the return page entitlement (Grow+). Each successful call returns the return object (same shape as Retrieve).

Typical sequence: review → approve → confirm. Decline instead of approve when you reject the request. Cancel only after a return shipment exists.

Review

Endpoint

POST /v1/returns/:id/review

Moves the return to in_review. No body. Rejected if a return order already exists.

Approve

Endpoint

POST /v1/returns/:id/approve

Moves the return to approved. No body. Cannot approve a return that is already approved or declined, or that already has an active return order.

Decline

Endpoint

POST /v1/returns/:id/decline

Moves the return to declined. Cannot decline a return that already has an active return order.

Body

{
  "declined_reason": "Item is not eligible for return"
}

Field	Type	Required	Description
declined_reason	string	Yes	Why the request is declined.

Confirm

Endpoint

POST /v1/returns/:id/confirm

Books the reverse shipment. The return must be approved (or a previous return order must be in a finished negative status such as cancelled, rejected, courier_not_found, returned, or disposed). Creates an order and sets return_order_id, waybill, and courier fields.

Omitted origin / destination fields fall back to the values stored on the return. Insurance cannot exceed the total value of returned items.

Body

{
  "courier_company": "jne",
  "courier_type": "reg",
  "delivery_type": "now",
  "origin_collection_method": "pickup",
  "courier_insurance": 165000,
  "order_note": "Return pickup"
}

Field	Type	Required	Description
courier_company	string	Yes	Courier code, e.g. jne.
courier_type	string	Yes	Service code, e.g. 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 exceed returned items value.
order_note	string	No	Note on the return order.
metadata	object	No	Passed through to the return order.
origin_contact_name	string	No	Override pickup contact.
origin_contact_phone	string	No	Override pickup phone.
origin_address	string	No	Override pickup address.
origin_note	string	No	Override 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	Override seller contact.
destination_contact_phone	string	No	Override seller phone.
destination_contact_email	string	No	Seller email.
destination_address	string	No	Override seller address.
destination_note	string	No	Override 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" }.

Use Rates to choose courier_company and courier_type before confirming.

Cancel

Endpoint

POST /v1/returns/:id/cancel

Cancels the return order (the reverse shipment). The return must already have a return_order_id. Same cancellation codes as Cancel an Order.

Body

{
  "cancellation_reason_code": "change_courier",
  "cancellation_reason": "Need a different courier"
}

Field	Type	Required	Description
cancellation_reason_code	string	Yes	change_courier, change_address, change_item, change_recipient, pickup_delay, no_confirmation, price_discrepancy, item_not_ready, or others.
cancellation_reason	string	No	Extra detail.