Skip to content
You're viewing the API v4 documentation, recommended for new integrations.
For the complete documentation index, see llms.txt. This page is also available as Markdown.

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.

The fields shown below are the core RMA export fields. Additional return-registration fields can be included when required by your integration.

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:

Event
When it occurs

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

Field
Example
Type
Description

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?