> For the complete documentation index, see [llms.txt](https://developer.esw.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.esw.com/returns-api/grp-returns-api/core-concepts/tracking-and-updates.md).

# Tracking and Updates

## Tracking Events

The GRP tracking layer aggregates events from carrier APIs and normalizes them into a common milestone and event model.

{% tabs %}
{% tab title="Milestones" %}
High-level checkpoints in the return journey (e.g. `ReturnCreated`, `InTransit`, `Delivered`). One milestone is marked `isCurrentMilestone: true` — use this to drive progress indicators.
{% endtab %}

{% tab title="Events" %}
Granular carrier events with an ESW internal event code, a timestamp, and a location string. Suitable for a detailed tracking timeline.

Query by providing either a numeric `trackingReference` or the shopper's `emailAddress` in the request body. Both fields are optional but at least one must be supplied.
{% endtab %}
{% endtabs %}

{% code title="Retrieves tracking events" expandable="true" %}

```http
POST /{identifier}/tracking-events 
```

{% endcode %}

Returns tracking milestones and granular event details for a return shipment.

<details>

<summary><strong>Request Body</strong></summary>

| Field               | Type            | Description                                     |
| ------------------- | --------------- | ----------------------------------------------- |
| `trackingReference` | integer (int64) | Numeric tracking reference (e.g. `20077466295`) |
| emailAddress        | string          | Shopper email for verification                  |

</details>

<details>

<summary><strong>Response (200)</strong></summary>

| Field      | Type                | Description                                                           |
| ---------- | ------------------- | --------------------------------------------------------------------- |
| milestones | MilestoneDto\[]     | High-level checkpoints (code, dateTime, location, isCurrentMilestone) |
| events     | TrackingEventDto\[] | Detailed events (code, dateTime, location)                            |
| carrier    | string              | Carrier name (e.g. "DHL")                                             |

</details>

## Update Returns

Once a return order is created, track its journey and update its status as items are received and inspected. Call `POST /{id}/tracking-events` with a `trackingReference` (numeric) and `emailAddress`. The response contains milestones (high-level status checkpoints) and granular event details with timestamps and locations.

### Updating return order status

Use `PUT /{id}/orders/{orderRef}/return-orders/{returnOrderNum}` to update the return order status, individual item statuses (Accepted/Rejected), rejection reasons, and reason code overrides.

{% hint style="info" %}

#### **Item-level status**

Each return item can be individually accepted or rejected. Set `returnItemStatus` to `"Accepted"` or `"Rejected"` and include a `rejectionReason` for rejected items.
{% endhint %}

<br>


---

# 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://developer.esw.com/returns-api/grp-returns-api/core-concepts/tracking-and-updates.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.