> For the complete documentation index, see [llms.txt](https://docs.parcellab.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.parcellab.com/docs/developers/returns/receive-order-data.md). # 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. {% hint style="info" %} The fields shown below are the core RMA export fields. Additional return-registration fields can be included when required by your integration. {% endhint %} ## 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](/docs/developers/data-elements/get-status-updates.md#configure-tracking-webhooks). 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](/docs/developers/returns/return-registrations.md). ## Sample RMA Export The following example shows the core fields in the nested webhook and API representation: ```json { "external_id": "95c35493-41aa-44f8-9154-5a25cbbc1865", "reference": "ORDER-123456", "status": "submitted", "refund_method": "refund", "return_labels": [ { "tracking_number": "RET-123456", "courier": "dhl", "type": "shipping", "is_pickup": false, "delivery_status": "Pending" } ], "articles_return": [ { "line_item_id": "ITEM-001", "sku": "TSHIRT-BLUE-M", "return_reason": "size:too_small", "return_reason_pretty": "Too small", "problem_description": "Sleeves are too short", "compensation_method": "refund", "return_quantity": 1 } ], "customer_first_name": "Bruce", "customer_last_name": "Wayne", "customer_address": { "first_name": "Bruce", "last_name": "Wayne", "address_line": "1 Example Street", "address_line_extra": "Apartment 4", "postal_code": "75001", "region_code": "IDF", "city": "Paris", "country_iso3": "FRA" }, "customer_phone": "+33123456789", "customer_email": "bruce.wayne@example.com" } ``` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.parcellab.com/docs/developers/returns/receive-order-data.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.