Cancel RMA API

Use this endpoint to cancel an already-created return (RMA).

Production endpoint URL:

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

For details on access, view the overview here:

RMA Actions API

What This Endpoint Achieves

When successful, the API:

• Marks the return as cancelled

• Stores an optional cancellation reason

• Updates return tracking status in parcelLab backend systems

• Attempts to cancel related Shopify entities (draft order and return), when they exist

Endpoint

Property	Value
Method	POST
Path	/cancelRma
Content type	application/json
Authentication	user header (required)

Request

Headers

Header	Required	Type	Description
user	yes	string	Merchant/customer identifier provided by parcelLab.
Content-Type	yes	string	Must be application/json.

Body

Field	Required	Type	Rules	Description
returnId	yes	string	exactly 24 characters	Return ID to cancel.
lang	yes	string	min length 1	Return language.
country	yes	string	min length 1	Market/country context.
cancelReason	no	string	optional	Free-text reason saved as return status reason.

cancelReason constraints

There is currently no enforced enum or structured format for cancelReason.

• Accepted type: string

• Optional field

• No predefined list of allowed values

• No regex/length restriction enforced by this endpoint

Behavior details:

• If omitted, saved status reason is null

• If an empty string is sent, it is treated as no reason and stored as null

Example Request

curl \
  -X POST "https://returns-api.parcellab.com/prod/cancelRma" \
  -H "user: 1612198" \
  -H "Content-Type: application/json" \
  -d '{
    "returnId": "af0000000000000000000001",
    "lang": "en",
    "country": "us",
    "cancelReason": "Customer changed mind"
  }'

Success Response (200 OK)

{
  "returnId": "af0000000000000000000001",
  "hasDraftOrder": true,
  "draftOrderCloseError": null,
  "hasReturn": true,
  "returnCloseError": null
}

Response fields

Field	Type	Meaning
returnId	string	Cancelled return ID.
hasDraftOrder	boolean	A Shopify draft order was found and a delete attempt was made.
draftOrderCloseError	string | null	Error message from Shopify draft order deletion, if deletion failed.
hasReturn	boolean	A Shopify return was found and a cancel attempt was made.
returnCloseError	string | null	Error message from Shopify return cancellation, if cancellation failed.

What It Does In Shopify

If the cancelled return is linked to Shopify, the endpoint attempts:

1. Draft order deletion (draftOrderDelete) when a draft order exists.

2. Return cancellation (returnCancel) when a Shopify return exists.

Important:

• Shopify failures do not automatically fail the whole cancellation request.

• You must inspect draftOrderCloseError and returnCloseError in the 200 response to confirm Shopify-side success.

Error Responses

Status	Error value	Meaning
400	Payload schema validation failed.	Missing/invalid request fields.
400	Invalid request body format.	Body is not valid JSON.
400	RMA cancel failed.	Upstream/customer-specific cancel export failed.
400	Update return failed.	Return update could not be persisted.
403	FORBIDDEN	Return does not belong to requesting user and lang context.
404	User not found.	Merchant configuration not found.
404	Order does not exist.	Return ID not found.
500	implementation-defined	Unexpected server error.

Standard error payload:

{
  "code": 400,
  "error": "Payload schema validation failed.",
  "details": "..."
}