Skip to main content
POST
/
api
/
ReturnInventory
/
UpdateReturnInventoryHandling
Update return inventory handling
curl --request POST \
  --url https://api.returnshelper.com/uat/user/api/ReturnInventory/UpdateReturnInventoryHandling \
  --header 'Content-Type: application/json' \
  --header 'x-rr-apikey: <api-key>' \
  --header 'x-rr-apitoken: <api-key>' \
  --data '
{
  "returnInventoryId": 123,
  "handlingCode": "<string>"
}
'
{
  "correlationId": "<string>",
  "meta": {
    "status": 123,
    "data": {},
    "errorCode": "<string>",
    "error": {}
  }
}
Updates the handling decision on a single return inventory record — i.e. tells the warehouse what to do with a parcel they’ve received. The most common write call after the warehouse has logged a return; from this point the inventory follows the chosen handling path (restock, dispose, recall, resend, etc.).

​
When to call

  • After your CS or operations team has decided on the handling.

​
Required fields

  • returnInventoryId — long; must exist and belong to your account. Received from the newInventoryCreated webhook event when a parcel is logged at the warehouse; cache it on your side so you can act on it later. The webhook stream is the source of truth for inventory IDs.
  • handlingCode — string, must be one of the codes returned by Get all handling types. Cannot be rsd (resend) or tbc (to-be-confirmed) directly — those flow through dedicated endpoints. Common values: ohd (on-hold), rtn (return), rst (restock), dsp (dispose).
One explicit exception: if the current handlingStatusCode is pending and the new handling is ohd (on-hold), the call is always allowed — useful for putting an inventory on hold while you investigate. You cannot update handling if:
  • The inventory has any pending VAS (value-added service) requests on its line item. Cancel or complete the VAS first via Get all VAS and the VAS endpoints.

​
Side effects

  • handlingCode and handlingStatusCode on the inventory record are updated.
  • If the new handling is not ohd or oth (others), the RMA mapping is locked to prevent RMA swap operations on this inventory.
  • Cancel return inventory handling — undo a handling decision before the warehouse acts on it.
  • Create recall by return inventory IDs — to flow a recalled inventory through the dedicated recall pipeline rather than handling.
  • Create resend order — for the resend pathway (which also can’t be reached via this endpoint directly).
  • Webhooks — newInventoryCreated, vasUpdated, the inventory-handling-complete event, and notifyUserRmaSwapped deliver inventory lifecycle to your endpoint.

Authorizations

​
x-rr-apikey
string
header
required

Your API key

​
x-rr-apitoken
string
header
required

Your API token — keep this private

Body

application/json
​
returnInventoryId
integer<int64>
required

Return inventory ID to update handling for

​
handlingCode
string
required

Handling code to apply

Response

Success

Universal response envelope. Successful responses include the business payload as additional top-level fields alongside correlationId and meta. Failed responses (auth errors, validation errors) only populate correlationId and meta, with meta.errorCode and meta.error describing the failure.

​
correlationId
string | null

Unique correlation ID for tracing the request through Return Helper systems.

​
meta
object

Application-level metadata for every API response. Inspect status and errorCode to detect soft-error responses (validation failures arrive as HTTP 200 with meta.status: 400).