Edit Return API

Use this endpoint to apply post-registration edit operations to a return.

Production endpoint URL:

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

For details on access, view the overview here:

RMA Actions API

Supported Operation

Currently supported:

• cancel_exchange

What cancel_exchange Achieves

This operation reverts an exchange-oriented return back to refund-oriented processing.

When successful, it may:

• Convert exchange compensation methods to refund

• Clear uneven-exchange items

• Ensure a refund method exists (defaults to original-payment-method if missing)

• Attempt to delete related Shopify draft order

• Remove stored Shopify draft-order references from return data

• Propagate changes to backend tracking

• Tag Shopify order with parcellab_exchange_cancelled (best effort)

Request

Headers

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

JSON Body

Field	Required	Type	Rules	Description
returnId	yes	string	24-character ID	Return to edit.
lang	yes	string	min length 1	Language context.
country	yes	string	min length 1	Country/market context.
operation	yes	string	must be cancel_exchange	Edit operation.
draft	no	string	optional	Set to true for draft config.
operationPayload	no	object	optional	Operation-specific payload.
operationPayload.cancelReason	no	string	optional	Currently accepted, not persisted by this operation.

Example Request

curl \
  -X POST "https://returns-api.parcellab.com/prod/editReturnById" \
  -H "user: 1612198" \
  -H "Content-Type: application/json" \
  -d '{
    "returnId": "af0000000000000000000001",
    "lang": "en",
    "country": "us",
    "operation": "cancel_exchange",
    "operationPayload": {
      "cancelReason": "Customer requested refund instead of exchange"
    }
  }'

Success Responses (200 OK)

Updated

{
  "returnId": "af0000000000000000000001",
  "operation": "cancel_exchange",
  "action": "updated",
  "shopifyDraftOrder": {
    "attempted": true,
    "cancelled": true,
    "error": null
  },
  "exchangeArticlesUpdated": 2,
  "exchangeItemsUpdated": 2,
  "refundMethod": "original-payment-method",
  "refundMethodApplied": true,
  "draftOrderIdRemoved": true,
  "unevenExchangeArticlesCleared": 1,
  "backendTrackingUpdated": true,
  "shopifyDraftOrderDataCleared": true
}

Skipped

{
  "returnId": "af0000000000000000000001",
  "operation": "cancel_exchange",
  "action": "skipped",
  "reason": "return_already_closed",
  "shopifyDraftOrder": {
    "attempted": false,
    "cancelled": false,
    "error": null
  }
}

Common reason values:

• return_already_closed

• no_changes_required

Shopify Behavior

For Shopify-connected returns:

1. If a draft order exists, deletion is attempted.

2. If draft deletion fails, the operation can still continue and return shopifyDraftOrder.error.

3. A Shopify order tag (parcellab_exchange_cancelled) is attempted in best-effort mode (tag failure does not fail the endpoint).

Error Responses

Status	Error value	Meaning
400	Payload schema validation failed.	Missing/invalid request input.
400	Invalid request body format.	Invalid JSON body.
400	Update return failed.	Persisting return changes failed.
400	No modifiers to update is set	No valid state change could be applied.
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.