Glossary

A short reference for non-engineering readers (project managers, operations, customer success) who need to bridge “what the warehouse calls it” with “what the API and webhooks call it”. Terms are grouped by lifecycle stage. For each term you get a one-line definition, the API object or webhook event it corresponds to, and a pointer to the most relevant endpoint or page.

​

Pre-arrival

​

Return Shipment

The pre-arrival object you create via the API to declare that a parcel is on its way back to a Return Helper warehouse. Carries the service type, origin address, parcel dimensions, item list, and total value. Identified by shipmentId.

• Create: Create Return Shipment
• List (backfill only): List Shipments
• Schema: CreateReturnShipmentRequest

​

Label

The shipping label generated for a Return Shipment. Generation is asynchronous — the API call to create the shipment queues a label request and returns labelRequestStatusCode: queued; the actual label URL arrives later via webhook.

• Webhook: Label result (category: labelGenerated / action: labelGenerated)
• Key fields: labelUrl, trackingNumber, shipmentId (use shipmentId to match, never labelId)

​

RMA (Return Merchandise Authorization)

A globally unique identifier assigned by the warehouse when a parcel arrives. Return Helper uses RMA — not the carrier tracking number — as the primary communication identifier, because tracking numbers can collide across or within carriers, and because a single parcel can split into multiple RMAs via VAS.

• Format: <warehouse prefix>-<warehouse ID>-<YYMMDD>-<env letter><sequence>-<check digits> (split parcels add a 2-digit split sequence)
• Webhook: RMA updated (category: notifyUserRmaSwapped)
• Detail: Getting Started → RMA

​

Custom Field Map

Arbitrary key-value metadata you attach to a Return Shipment. Stored verbatim by Return Helper and echoed back in relevant webhook events. Maximum 24 entries per return.

• Field: customFieldMap on Return Shipment, parcel items, and several webhook payloads

​

Warehouse arrival

​

Return Inventory

The post-arrival object created at the warehouse when a parcel is received and processed. Identified by returnInventoryId. A single Return Shipment may produce multiple Return Inventory records (one per package or per line item, depending on the shipment).

• Get: Get Return Inventory Details
• List (backfill only): List Return Inventories
• Webhook: Inventory created (category: newInventoryCreated)

​

Unknown Shipment

A parcel that arrives at the warehouse without a matching seller-created Return Shipment, but is later identified as belonging to a seller. When assigned, it flows into your account as a Return Inventory.

• Webhook: Unknown shipment assigned (category: rsl / action: assignUnknown)
• Payload includes: returnInventoryId, shipmentId, returnRequestId, and any inventory images captured before assignment

​

Inventory Image

Photographs taken at the warehouse showing the parcel contents and condition. The image URL list arrives via webhook whenever the warehouse adds, replaces, or removes an image.

• Webhook: Image updated (category: rrli / action: changeLineItemImage)

​

Warehouse Arrival Event

The moment the warehouse marks the parcel as received. Delivered via webhook; this is the canonical “the parcel is here” signal.

• Webhook: Warehouse shipment arrived (v2) (category: rsl / action: markShipmentArrive)

​

Post-arrival handling

​

Handling Instruction

A directive that tells the warehouse what to do with a Return Inventory after arrival. The available handling types are Dispose, On-hold, Resend, Recall, and VAS (defined below).

• Update: Update Return Inventory Handling
• Cancel: Cancel Return Inventory Handling
• Webhook: Inventory handling complete (category: rinv / action: completeInventoryHandling)

​

Dispose

The warehouse destroys / discards the inventory. Applied via the standard handling instruction with the dispose handling code.

​

On-hold

The warehouse holds the inventory without processing. Used when you need time to decide. Applied via the standard handling instruction with the on-hold handling code.

​

Resend

The warehouse re-ships the inventory to a new destination (typically a different buyer). Created as a separate object referencing one or more returnInventoryId values.

• Create: Create Resend Order
• Cancel: Cancel Resend Order
• Webhook: Resend status update (category: resend / action: updateResendStatus)

​

Recall

The warehouse ships the inventory to Return Helper’s Hong Kong consolidation warehouse for centralised processing. Accepts up to 100 returnInventoryId values per call. To send a bulk of inventories to a destination of your own choosing, use Consolidate Shipping Order instead.

• Create: Create Recall by Return Inventory IDs
• Webhook: Recall status update (category: recall / action: recallUpdateStatus)

​

VAS (Value-Added Services)

A family of operations the warehouse performs on the inventory — for example splitting an inventory into multiple items, repacking, or item inspection. When VAS splits an inventory, each resulting piece gets its own RMA.

• Create: Create VAS by Return Inventory ID
• Webhook (completion): VAS update (category: rrliv / action: vasUpdated)
• Webhook (split): Split line item (category: lineItemVasReturnInventoryLineItem / action: splitLineItem)

​

FBA (Fulfilled by Amazon)

​

FBA Shipment

A shipment of FBA-eligible product sent to a Return Helper warehouse for downstream processing (restock, replenish, recall, dispose, etc.). Identified by fbaShipmentId.

• Create: Create FBA Shipment
• List (backfill only): List FBA Shipments

​

FBA Instruction

A directive on FBA inventory at the warehouse — restock, replenish, recall, dispose, or “others”. Created by FNSKU + quantity rather than returnInventoryId.

• Create: Create FBA Instructions
• List (backfill only): List FBA Instructions

​

FNSKU

Amazon’s per-product fulfilment SKU. Used everywhere FBA inventory is referenced, in place of returnInventoryId.

• Lookup current quantity: Get FBA Warehouse Inventory List by FNSKU

​

Consolidate Shipping

​

Consolidate Shipping Order

A multi-inventory consolidation where several Return Inventory records are packed together and shipped as one outbound parcel set. Used to reduce shipping cost when sending inventory back to the seller.

• Create: Create Consolidate Shipping Order
• Confirm: Confirm Consolidate Shipping Order
• Webhook (cost): Consolidate shipping cost updated
• Webhook (completion): Consolidate order completed

​

Auth & integration plumbing

​

API Key and API Token

The pair of credentials your server sends on every authenticated request, as the x-rr-apikey and x-rr-apitoken headers. Issued in the User Portal under Settings → Signing Key and API Token.

• Detail: Introduction → Authentication

​

Signing Key

A Base64-encoded shared secret Return Helper uses to sign webhook requests. Your receiver verifies the returnhelper-signature header against the raw body using this key. Issued in the User Portal alongside the API key.

• Detail: Webhooks → Signature Verification

​

Webhook / Notification

The mechanism by which Return Helper delivers asynchronous events (label results, warehouse events, handling completion, etc.) to your server. Delivered as HTTPS POST requests with a signed body. Webhooks are the canonical data-exchange channel — list endpoints are for one-time backfill only.

• Detail: Webhooks

​

Idempotency Key

A unique value you generate for each state-changing request, sent as the x-returnhelper-idempotency-key header. Return Helper deduplicates retries of the same key so a network retry does not create a duplicate shipment / resend / recall / VAS / FBA shipment.

• Detail: Introduction → Idempotency

​

correlationId

A request identifier returned in every API response envelope. Log it on your side; Return Helper support uses it to trace specific requests.

• Detail: Introduction → Error Handling

​

notificationId

A unique identifier on every webhook event. Use it as the idempotency key in your webhook receiver to deduplicate redelivered events.

• Detail: Webhooks → Event Delivery