Cancel Pickup Order API

Use this endpoint to cancel a previously scheduled pickup for an existing return.

Production endpoint URL:

https://returns-api.parcellab.com/prod/cancelPickUpOrder

For details on access, view the overview here:

RMA Actions API

What This Endpoint Achieves

When successful, the API cancels pickup with the courier and rolls the return back to a pre-submission state.

Main effects:

• Cancels scheduled pickup(s)

• Resets return status to created

• Sets submitted to false

• Clears submittedAt

• Clears returnLabel

• Resets article return flags for re-submission flow

Request

Headers

Header	Required	Type
user	yes	string

Query Parameters

Parameter	Required	Type	Notes
returnId	yes	string	24-character return ID.
lang	yes	string	Language context.
country	yes	string	Country/market context.
draft	no	string	Set to true for draft config.

Body

No request body is required.

Example Request

curl \
  -X POST "https://returns-api.parcellab.com/prod/cancelPickUpOrder?returnId=af0000000000000000000001&lang=en&country=us" \
  -H "user: 1612198"

Success Response (200 OK)

{
  "returnId": "af0000000000000000000001",
  "status": true
}

Field	Type	Meaning
returnId	string	Return ID affected.
status	boolean	true when cancellation + state reset succeeded.

Notes

• If pickup was never scheduled (or no cancellable change can be applied), the request may fail with a business error.

• Depending on merchant configuration, an external RMA cancellation export may also be triggered.

Error Responses

Status	Error value	Meaning
400	Payload schema validation failed.	Missing/invalid request input.
400	RMA cancel failed.	External RMA cancellation export failed.
400	Pickup order could not be cancelled.	Courier pickup cancellation failed.
400	No modifiers to update is set	No state change could be applied.
400	Update return failed.	Return update persistence failed.
403	FORBIDDEN	returnId is not accessible in caller context.
404	User not found.	Merchant context not found.
404	Order does not exist.	returnId not found.
500	implementation-defined	Unexpected server error.