> 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/v2/returns/receive-data.md).

# Receive Data

Receive RMA exports via webhook, API or as a flat file (.csv or .tsv) to an SFTP server.

We can provide an RMA export of returns data to your Warehouse Management System (WMS). This can be sent as a flat file (.csv or .tsv) to an SFTP server, or via webhook or an API connection.

The export contains the order number, tracking number, item ID/SKU, number of items, and return reasons. If additional information (for example: text feedback) is required, this data can be transferred as well.

In the following table, you can find a list of the data fields that are included in the RMA exports.

<table><thead><tr><th width="224">Field</th><th width="217">Example</th><th width="150">Type</th><th>Remarks</th></tr></thead><tbody><tr><td><strong>Return Details</strong></td><td></td><td></td><td></td></tr><tr><td>consignmentNumber</td><td>ab938adnaduj38</td><td>string</td><td>Unique Return Portal ID.</td></tr><tr><td>trackingNumber</td><td>12345678</td><td>string</td><td>Tracking number of the parcel.</td></tr><tr><td>carrier</td><td>DHL</td><td>string</td><td>The carrier shipping the parcel.</td></tr><tr><td>orderNumber</td><td>12345678</td><td>string</td><td>Order number.</td></tr><tr><td>submittedDate</td><td>2024-12-10</td><td>date</td><td>Date the registration was submitted in format YYYY-MM-DD (ISO-8601).</td></tr><tr><td>returnMethod</td><td>inStoreReturn</td><td>string</td><td>Describes the method of return (for example: whether the return was made in store, picked up by couriers or dropped off at the post office).</td></tr><tr><td><strong>Article Details</strong></td><td></td><td></td><td></td></tr><tr><td>itemID</td><td>1223214343</td><td>string</td><td>Unique item ID.</td></tr><tr><td>SKU</td><td>1312321324</td><td>string</td><td>Unique stock keeping unit.</td></tr><tr><td>returnReason</td><td>Wrong item delivered</td><td>string</td><td>The selected return for reason.</td></tr><tr><td>problemDescription</td><td>Not what I expected</td><td>string</td><td>Descriptive reason why the item was returned.</td></tr><tr><td>compensationMethod</td><td>Exchange</td><td>string</td><td>Describes the method of compensation (for example: if a refund or exchange was issued).</td></tr><tr><td>returnQuantity</td><td>1</td><td>numeric</td><td>Quantity of returned item.</td></tr><tr><td><strong>Customer Details</strong></td><td></td><td></td><td></td></tr><tr><td>name</td><td>Bruce Wayne</td><td>string</td><td></td></tr><tr><td>street</td><td>Rue du Chardonay</td><td>string</td><td></td></tr><tr><td>zip</td><td>80339</td><td>string</td><td></td></tr><tr><td>state</td><td>Île-de-France</td><td>string</td><td></td></tr><tr><td>city</td><td>Paris</td><td>string</td><td></td></tr><tr><td>country</td><td>FR</td><td>string</td><td></td></tr><tr><td>phone</td><td>01569283</td><td>string</td><td></td></tr><tr><td>email</td><td>bruce.wayne@parcellab.com</td><td>string</td><td></td></tr></tbody></table>

## Sample RMA Exports

A sample .csv file can be found here as demonstration of the data structure:

{% file src="/files/3jiqDm4hrr8De7EaaYik" %}

A sample .json payload can be found here as demonstration of the data structure:

{% file src="/files/u2KCOD0gmBxxzcU2eCKg" %}

## Choose a Delivery Method

An RMA export is a configured data transfer to your system. Agree on the destination, authentication, trigger or schedule, field mapping, and retry handling with your parcelLab implementation contact. The example files show an export format; they are not the schema of a generic `/rma/export` endpoint.

For a system that pulls current return registrations, use the authenticated [v4 Return Registrations API](https://github.com/parcelLab/gitbook-documentation/tree/main/developers-v4/returns/return-registrations.md). It returns the v4 registration schema, which differs from the export examples on this page.

```bash
curl --get 'https://api.parcellab.com/v4/returns/return-registrations/' \
  --header "Authorization: Parcellab-API-Token ${PARCELLAB_API_TOKEN}" \
  --data-urlencode 'account=1234567' \
  --data-urlencode 'updated_at_after=2026-10-01T00:00:00Z'
```

Use an encoded token with the `read` scope; a token with `returns:read` is also accepted. Read the `results` array and follow the returned `next` link until it is `null`. The link is relative; resolve it against the API origin. Store each registration’s `external_id` so later updates replace the same record in your system. This retrieves current records, not a complete event history.

## Return Events and Payloads

Choose the event source that matches your integration:

| Source                                   | Events and payload                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| ---------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Tracking webhook                         | Shipment milestones such as `onDispatch`, `onDelivered`, and `onReturn`, with the shared [tracking webhook contract](/docs/developers/v2/data-elements/get-status-updates/webhooks.md). `onReturn` means a shipment is being returned to the sender; it does not mean a shopper has submitted a return registration.                                                                                                                                                                          |
| Configured RMA export or Journey webhook | The configured trigger and message template determine the event label and fields. The sample on this page uses `onReturnRegistration`; treat it as an example of that export configuration.                                                                                                                                                                                                                                                                                                   |
| Returns RMA Event app                    | Each active Returns RMA Event app on the account receives `event.type` `submit` when a return is submitted and `close` when it is closed. An app linked for order lookup also receives `order_lookup`. Where return expiry is configured, expired registrations are cancelled automatically; expiry is not sent to the app as an event. Its handler defines any downstream request sent to your system. These event names and the app context are separate from tracking webhook event names. |

For a configured payload, agree on the return identifier, article identifiers, quantities, return reasons, optional fields, and duplicate handling. Test the actual template against your receiver before enabling delivery. Do not assume that every account sends the sample payload unchanged.


---

# 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/v2/returns/receive-data.md?ask=<question>&goal=<user_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.