Receive Order Data
Receive RMA exports via webhook, API or as a flat file (.csv or .tsv) to an SFTP server.
parcelLab can send return merchandise authorization (RMA) data to your Warehouse Management System (WMS) by webhook or through an API connection. We can also provide a flat .csv or .tsv file through SFTP.
Webhook and API payloads use the snake_case field paths below. Flat-file exports contain the same data, but repeated objects such as return labels and articles are flattened into rows or columns as agreed during implementation.
Configure Return Webhooks
A return-registration export needs an integration for your account. Creating an API token or registering a return does not, by itself, subscribe your system to webhooks.
Ask your parcelLab representative to configure the RMA export or Returns RMA Event app. Provide the receiver URL, authentication requirements, required payload fields, and the point in the returns process when your system needs the data. For an app-based integration, the app must have an active live deployment for the account.
The Returns RMA Event app receives these lifecycle event types in event.type:
submit
The return registration is submitted. Use this for a new submitted RMA.
close
The return registration is closed.
RETURN_CREATED is not a built-in event name for this integration. If your receiver requires that name, agree on the mapping and outgoing payload with parcelLab. The app receives event and returnRegistration; the payload sent to your receiver depends on the configured integration.
expire is a return-event mapping that configures automatic cancellation of expired returns; it does not send an event to the app. order_lookup is a request to retrieve order data, not a return-status notification. Carrier events, such as return drop-off or delivery, use tracking webhook triggers.
Test a return through submission and closure, then confirm that your receiver gets the expected payload at each configured step.
RMA Export Fields
Return details
external_id
95c35493-41aa-44f8-9154-5a25cbbc1865
UUID v4
Unique return registration identifier generated by parcelLab.
reference
ORDER-123456
string
Retailer reference for the original order. This value is not guaranteed to be unique.
status
submitted
string
Current return registration status.
refund_method
refund
string
Refund method code selected by the customer. Available codes depend on the Returns Portal configuration.
return_labels[].tracking_number
RET-123456
string or null
Tracking number or barcode for the return label.
return_labels[].courier
dhl
string
Courier or drop-off code for the return label.
return_labels[].type
shipping
string
Return label type: shipping or custom.
return_labels[].is_pickup
false
boolean
Whether the return label represents a courier pickup.
return_labels[].delivery_status
Pending
string
Current shipping stage of the return label.
Returned article details
articles_return[].line_item_id
ITEM-001
string
Retailer identifier for the line item.
articles_return[].sku
TSHIRT-BLUE-M
string or null
Stock keeping unit for the line item.
articles_return[].return_reason
size:too_small
string or null
Full configured return-reason path.
articles_return[].return_reason_pretty
Too small
string or null
Customer-facing text for the selected return reason.
articles_return[].problem_description
Sleeves are too short
string or null
Additional problem description supplied for the returned article.
articles_return[].compensation_method
refund
string or null
Configured compensation method code for the returned article.
articles_return[].return_quantity
1
integer or null
Quantity of the article being returned.
Customer details
customer_first_name
Bruce
string or null
Customer's first name.
customer_last_name
Wayne
string or null
Customer's last name.
customer_address.address_line
1 Example Street
string
Street address, including the house number.
customer_address.address_line_extra
Apartment 4
string or null
Additional address information, such as an apartment or company name.
customer_address.postal_code
75001
string
Postal or ZIP code.
customer_address.region_code
IDF
string or null
State, province, or region code, when available.
customer_address.city
Paris
string
City.
customer_address.country_iso3
FRA
string
ISO 3166-1 alpha-3 country code.
customer_phone
+33123456789
string or null
Customer's phone number.
customer_email
bruce.wayne@example.com
string or null
Customer's email address.
For the complete REST API response schema, see Return Registrations.
Sample RMA Export
The following example shows the core fields in the nested webhook and API representation:
Last updated
Was this helpful?