Reschedule Pickup Order API

Use this endpoint to move an existing scheduled pickup to a new date/time window.

Production endpoint URL:

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

For details on access, view the overview here:

RMA Actions API

What This Endpoint Achieves

When successful, the API:

• Requests pickup rescheduling with the configured courier

• Stores updated pickup status on the return

• Propagates new pickup information to tracking updates

Request

Headers

Header	Required	Type
user	yes	string
Content-Type	yes	string (application/json)

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.

JSON Body

Field	Required	Type	Description
pickupDate	yes	string	New pickup date.
earliestPickupTime	no	string	Earliest requested pickup time.
latestPickupTime	no	string	Latest requested pickup time.

Example Request

curl \
  -X POST "https://returns-api.parcellab.com/prod/reschedulePickUpOrder?returnId=af0000000000000000000001&lang=en&country=us" \
  -H "user: 1612198" \
  -H "Content-Type: application/json" \
  -d '{
    "pickupDate": "2026-02-20",
    "earliestPickupTime": "08:00",
    "latestPickupTime": "16:00"
  }'

Success Response (200 OK)

{
  "returnId": "af0000000000000000000001",
  "status": true,
  "pickUpStatus": {
    "pickupWindow": "2026-02-20T08:00:00-2026-02-20T16:00:00",
    "pickupConfirmationCode": "ABC123"
  }
}

Field	Type	Meaning
returnId	string	Return ID affected.
status	boolean	true when reschedule flow succeeded.
pickUpStatus	object	Courier-provided updated pickup status payload.

Notes

• This endpoint applies to returns with an existing scheduled pickup.

• If no reschedulable pickup exists, the request may fail with a business error.

• Depending on merchant configuration, an external RMA update export may also run.

Error Responses

Status	Error value	Meaning
400	Payload schema validation failed.	Missing/invalid request input.
400	Pickup order could not be rescheduled.	Courier reschedule failed.
400	RMA export failed.	External RMA update export failed.
400	No modifiers to update is set	No state change could be applied.
400	Pickup failed to be stored on the database.	DB update failed after courier success.
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.