RMA Actions API

Control the return after it’s created: cancel, reschedule pickup, add labels, and manage exchange updates via one API surface.

API Basics

Base URL

Production base URL: https://returns-api.parcellab.com/prod

Endpoint URL format: https://returns-api.parcellab.com/prod/<endpoint>

Authentication

All endpoints in this set are POST requests.

All requests require the user header.

Header	Required	Type	Description
user	yes	string	Merchant/customer identifier assigned by parcelLab.
Content-Type	yes	string	Required for POST requests with a JSON body. Use application/json.

All requests also require the following identifier in the request payload (either JSON body or query parameters, depending on the endpoint):

Payload key	Required	Type	Description
returnId	yes	string	Return session identifier.

Data Access Model

The user and returnId keys are both user-facing values in this API model.

Treat returnId as an RMA session identifier that is:

• Valid for the specific user

• Valid for up to 30 days

• Randomly generated and not realistically brute-forceable

This means returnId can be shown to the customer as part of the return flow, but it should only be used within the intended return context.

Access checks are still enforced server-side:

• The return must belong to the provided user

• The return must match the provided lang context (where applicable)

If these checks fail, the request is rejected (403 FORBIDDEN).

Response Model

Find details below on common structures of API responses.

Success responses

• Successful calls return 2xx and a JSON object.

• Response shape is endpoint-specific.

Error responses

Most errors follow this structure:

{
  "code": 400,
  "error": "Payload schema validation failed.",
  "errorMessage": "Optional additional message",
  "details": {}
}

Fields

• code: HTTP status code

• error: stable error message/code string

• errorMessage: optional user-friendly or upstream detail

• details: optional diagnostic data

Common Error Values

The following values appear across these post-registration endpoints:

Error value	Typical meaning
Payload schema validation failed.	Required field missing/invalid type.
Invalid request body format.	Request body is not valid JSON.
FORBIDDEN	Return does not belong to caller/context or operation forbidden.
User not found.	Unknown or inactive merchant config for provided context.
Order does not exist.	returnId not found.
Update return failed.	Return update failed during persistence.
No modifiers to update is set.	No valid state change could be applied.

Endpoint-specific docs list additional business-specific errors.

Retry hint header

Error responses include header x-retryable with true or false to indicate whether retry may make sense.

API Routes

• Add Label API POST /addLabelById Add an additional return label (generated or manual).

• Edit Return API POST /editReturnById Apply post-registration edit operations, currently only cancelling the exchange for an existing return in Shopify, forcing it to fall back to the specified refund method instead. If the user did not specify a preferred refund method during registration because they only opted for exchange, the refund will be issued to the original payment method.

• Cancel RMA API POST /cancelRma Cancel an already-created return and sync cancellation state.

• Cancel Pickup Order API POST /cancelPickUpOrder Cancel scheduled pickup and roll return back to pre-submission state

• Reschedule Pickup Order API POST /reschedulePickUpOrder Reschedule a pickup date/time window