Process Return API

Use this endpoint to process an existing return and release refund or exchange actions where applicable.

Production endpoint URL:

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

For details on access, view the overview here:

RMA Actions API

What This Endpoint Achieves

When successful, the API closes the return in parcelLab and can trigger Shopify return processing actions.

Depending on request flags and merchant configuration, it can:

• Mark the return as closed

• Issue a refund for eligible Shopify return line items

• Refund original shipping costs

• Release an exchange draft order

• Apply accepted/rejected article decisions

• Store the scanner identifier in customFields.scanAs

• Update return tracking status and Shopify order tags in parcelLab backend systems

Request

Headers

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

JSON Body

Field	Required	Type	Description
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.
isRefundEligible	no	boolean	Controls whether eligible Shopify return line items should be refunded.
isOriginalShippingRefundEligible	no	boolean	Controls whether original shipping costs should be refunded during Shopify refund processing.
isCompleteDraftOrderEligible	no	boolean	Controls whether an exchange draft order should be released.
acceptedArticles	no	array	Article-level processing decisions. See accepted article fields below.
scanAs	no	string	Scanner or operator identifier to store on the return.

acceptedArticles fields

Each acceptedArticles item is a return article object. The endpoint accepts existing article fields from the return document and the processing fields below.

Minimum required fields for each item:

Field	Required	Type	Description
articleNo	yes	string	Article number/SKU used for matching.
articleName	yes	string	Article display name.
articleImageUrl	yes	string	Article image URL.
quantity	yes	number	Quantity to process. Must be an integer for close processing.
returnReason	yes	string	Return reason code or text.
prettyProductId	yes	string	Display product identifier.
prettyReturnReason	yes	string	Display return reason.

These fields are enforced by the request schema when acceptedArticles is sent. After schema validation, the endpoint performs an additional processing guard that rejects acceptedArticles when it is null, when it is not an array, or when any item does not have a non-empty articleNo and integer quantity.

Additional processing fields:

Field	Required	Type	Description
accepted	no	boolean	Marks the article as accepted.
rejected	no	boolean	Marks the article as rejected.
rejectionReason	no	string	Reason for rejecting the article.
rejectionDetails	no	string	Additional rejection details.
acceptedQuantity	no	number	Quantity accepted for processing.
originalQuantity	no	number	Original returned quantity before processing changes.
updatedCondition	no	string	Updated article condition recorded during processing.

Example Request

curl \
  -X POST "https://returns-api.parcellab.com/prod/closeById" \
  -H "user: 1612198" \
  -H "Content-Type: application/json" \
  -d '{
    "returnId": "af0000000000000000000001",
    "lang": "en",
    "country": "us",
    "isRefundEligible": true,
    "isOriginalShippingRefundEligible": false,
    "isCompleteDraftOrderEligible": true,
    "scanAs": "scanner-123",
    "acceptedArticles": [
      {
        "articleNo": "SKU-1001",
        "articleName": "T-Shirt",
        "articleImageUrl": "https://example.com/t-shirt.jpg",
        "quantity": 1,
        "returnReason": "fit",
        "prettyProductId": "SKU-1001",
        "prettyReturnReason": "Did not prefer fit",
        "accepted": true,
        "acceptedQuantity": 1
      }
    ]
  }'

Success Responses (200 OK)

Processed

{
  "returnId": "af0000000000000000000001"
}

Skipped

{
  "returnId": "af0000000000000000000001",
  "action": "skipped",
  "reason": "return_already_closed"
}

Common reason values:

• return_already_closed

• shopify_return_already_closed

• concurrent_close_in_progress

Business Rules

• This endpoint is intended for Shopify-backed returns.

• If refund or exchange flags are disabled, the return can still be closed without issuing the corresponding refund or exchange action.

• acceptedArticles can reduce or exclude refunded quantities. For example, an article with quantity: 0 is not refunded.

• If Shopify already reports the return as closed, cancelled, or declined, parcelLab updates the local return status and returns a skipped response.

• Concurrent requests for the same return are guarded so only one close process runs at a time.

Error Responses

Status	Error value	Meaning
400	Payload schema validation failed.	Missing/invalid request input, including required fields inside acceptedArticles items.
400	Invalid request body format.	Body is not valid JSON.
400	One or more payload fields failed validation. Fields: acceptedArticles	acceptedArticles is null, not an array, or contains an item that fails the additional articleNo and integer quantity processing guard.
400	FORBIDDEN	The configured returns order API interface does not support this processing action.
400	No modifiers to update is set	No valid state change could be applied.
400	Shopify draft order could not be completed.	Exchange draft-order completion failed.
400	Shopify return could not be closed.	Shopify return processing failed.
400	Update return failed.	Return update could not be persisted.
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.