> ## Documentation Index
> Fetch the complete documentation index at: https://dokumentation.websale.de/llms.txt
> Use this file to discover all available pages before exploring further.

# SHIPTRACK- (shipment tracking)

> Query the shipment status at the shipping service provider and output it in the template: trigger the request, check for success, evaluate error codes and break down the response via the JSON interface.

Once a buyer has placed their order, they want to know where the parcel is right now. Shipment tracking fetches this information directly from the shipping service provider and makes it available in the template.

Four tags are enough for this, and they build on one another. One tag triggers the request, a second tells you whether it succeeded, a third gives the reason in case of an error, and the fourth returns the provider's response for further processing.

* Guide: DHL shipment tracking
* Guide: Post AT shipment tracking

> [!NOTE]
>
> All four tags are permitted on all templates. The feature must be enabled in the shop, and the access credentials for each provider are in the `ShipTrack` section of the shop configuration. Each entry there has an identifier that you use to address it in the template.

## Triggering the request

`SHIPTRACK-Get()` takes two arguments: the identifier of the configuration entry and the tracking number. Both may come from another tag.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
~SHIPTRACK-Get(DHL,$DC-FPtrackingNumber_StripHTML$)~
```

> [!WARNING]
>
> The tag triggers a request to the shipping service provider and waits for its response. Place it exactly once and only where the result is needed. On an overview page with many shipments, every occurrence becomes a separate request.

> [!WARNING]
>
> `SHIPTRACK-Get()` is exclusively a single tag and requires both arguments. If one is missing, or if one is empty after tag-in-tag resolution, the whole tag is considered invalid and produces a message in the template.

> [!NOTE]
>
> If you pass a tag as an argument, replace its tilde characters with dollar signs, as in the example.

> [!NOTE]
>
> The shop system supports three providers: DHL, the Austrian Post and the Swiss Post connection. Which one is meant is defined in the configuration entry, not in the tag. In the template, nothing changes apart from the identifier in the first argument.

## Was the request successful

`SHIPTRACK-OK` exists only as a bracketing. It applies if the last request ran without errors.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
~SHIPTRACK-Get(DHL,$DC-FPtrackingNumber_StripHTML$)~

{SHIPTRACK-OK}
   <p>Aktueller Status Ihrer Sendung:</p>
   ...
{/SHIPTRACK-OK}

{!SHIPTRACK-OK}
   <p>Zu dieser Sendung liegen derzeit keine Informationen vor.</p>
{/!SHIPTRACK-OK}
```

> [!WARNING]
>
> The order in the template matters. `SHIPTRACK-OK`, `SHIPTRACK-LastErrorCode` and `SHIPTRACK-JSONResult` refer to the **last** request and must therefore come after `SHIPTRACK-Get()`. Before it, no request has taken place yet.

## Tracing errors

`SHIPTRACK-LastErrorCode` outputs the code of the last request.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{!SHIPTRACK-OK}
   <p>Die Sendungsverfolgung ist derzeit nicht erreichbar. Fehlercode ~SHIPTRACK-LastErrorCode~.</p>
{/!SHIPTRACK-OK}
```

| Code | Meaning |
| - | - |
| 0 | the request was successful |
| 1 | shipment tracking is not enabled in the shop |
| 2 | the identifier is empty |
| 3 | the tracking number is empty |
| 4 | there is no configuration entry for this identifier |
| 5 | the configuration entry does not name a known provider |
| 1000 and above | the provider rejected the request or did not respond |

> [!NOTE]
>
> Codes 1, 4 and 5 indicate an incomplete configuration, not a problem with the shipment. A code of 1000 or above, on the other hand, comes from the provider itself, for example in the case of an unknown tracking number, a rejected login or a timeout.

> [!NOTE]
>
> In practice, you cannot reach codes 2 and 3 from a template. An empty argument already makes `SHIPTRACK-Get()` fail as an invalid tag beforehand, so the request never takes place.

> [!WARNING]
>
> As a bracketing, `SHIPTRACK-LastErrorCode` applies if there is an error, that is, for a code greater than zero. The negative bracketing therefore does not mean "no code available" but "no error", and is equivalent to `SHIPTRACK-OK`. The previous documentation describes the corresponding example differently.

## Evaluating the response

`SHIPTRACK-JSONResult` returns the provider's complete response as JSON. You pass it to the JSON interface and access the individual details there.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{SHIPTRACK-OK}
   ~EJD-SetRawDataInput($SHIPTRACK-JSONResult$)~
   ~EJD-LoadData(intern,rawdatainput,shiptrack)~
{/SHIPTRACK-OK}
```

The structure of the response comes from the provider and differs from provider to provider. With DHL, the most recently reported status is in the header of the record, followed by the list of individual events.

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
    "data": {
        "data": {
            "-piece-code": "00340435088500530592",
            "-last-event-timestamp": "10.06.2021 09:51",
            "-status": "Die Sendung wurde erfolgreich zugestellt.",
            "-product-name": "Warenpost",
            "data": [
                {
                    "-name": "piece-event",
                    "-event-timestamp": "09.06.2021 14:21",
                    "-event-status": "Die Sendung wurde elektronisch angekündigt.",
                    "-event-location": "",
                    "-standard-event-code": "VA"
                },
                {
                    "-name": "piece-event",
                    "-event-timestamp": "10.06.2021 09:51",
                    "-event-status": "Die Sendung wurde erfolgreich zugestellt.",
                    "-event-location": "",
                    "-standard-event-code": "ZU"
                }
            ]
        }
    }
}
```

> [!NOTE]
>
> DHL responds in XML. The shop system converts the response to JSON before output. That explains the leading hyphens on the keys: they mark former XML attributes. The Austrian Post already delivers JSON, so these hyphens are absent there.

> [!WARNING]
>
> Only evaluate `SHIPTRACK-JSONResult` within `SHIPTRACK-OK`. Without a preceding successful request, the output is not usable.

> [!NOTE]
>
> The field names within the response are defined by the provider, not by the shop system. They can change without anything changing in the shop. Therefore, catch missing fields with the check tags of the JSON interface instead of relying on their presence.

Reference: EJD- (JSON interface)

## Tags at a glance

| Tag | Single tag | Area tag | Negative area tag | Loop tag |
| - | - | - | - | - |
| `SHIPTRACK-Get()` | yes | – | – | – |
| `SHIPTRACK-OK` | – | yes | yes | – |
| `SHIPTRACK-LastErrorCode` | yes | yes | yes | – |
| `SHIPTRACK-JSONResult` | yes | yes | yes | – |

All four tags are permitted on all templates. The last three require a preceding `SHIPTRACK-Get()`.

## Related topics

* Guide: DHL shipment tracking
* Guide: Post AT shipment tracking
* Reference: EJD- (JSON interface)
* Reference: `ShipTrack` section in the shop configuration


## Related topics

- [$wsShipTrack - Shipment tracking](https://dokumentation.websale.de/en/frontend/referenz/module/wsshiptrack.md)
- [checkout - Order flow](https://dokumentation.websale.de/en/konfiguration/checkout-bestellablauf.md)
- [Shipping and delivery](https://dokumentation.websale.de/en/v8s/referenz/konfigurationen/shopkonfiguration-shop-config/versand-und-lieferung.md)
- [Configuration deep links](https://dokumentation.websale.de/en/admin-interface/konfigurations-deeplinks.md)
- [$wsOrderHistory - Order history](https://dokumentation.websale.de/en/frontend/referenz/module/wsorderhistory.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.