> ## 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.

# $wsShipTrack - Shipment tracking

> Reference for $wsShipTrack: access shipment tracking and delivery checks for tracking displays and zip code validation in the WEBSALE frontend.

With the `$wsShipTrack` module, you can access shipment tracking and delivery checks. You can use this for example for tracking displays or zip code validation for delivery.

***

## Module overview

**Example / excerpt of** `$wsShipTrack`

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{{= $wsShipTrack | json }}
```

**JSON output**

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
  "getTracking": "ƒ()",
  "zipCodeConfirmed": "ƒ()"
}
```

Note: `ƒ()` denotes a function.

**Methods overview**

| **Method**           | **Return type** | **Description**                                                                       |
| -------------------- | --------------- | ------------------------------------------------------------------------------------- |
| `getTracking()`      | map             | Returns tracking information from a shipping service provider for specific shipments. |
| `zipCodeConfirmed()` | bool            | Returns whether the zip code for a specific order has already been confirmed.         |

***

## Templates

Shipment tracking and zip code checks are typically used in the following places:

* Order confirmation: tracking link after dispatch of the order.
* Customer account: overview of shipment tracking for past orders.
* Checkout: zip code validation for delivery options.

***

## Actions

Actions for this module that trigger changes are documented separately in the "Actions" chapter (`ShipTrack`).

***

## Variables

No variables are available for `$wsShipTrack`.

***

## Methods

### \$wsShipTrack.getTracking()

Loads tracking information from a shipping service provider for a specific tracking number. The returned data depends directly on the respective provider, so when integrating, refer to the corresponding interface of the provider (e.g. DHL API).

**Signature**\
`$wsShipTrack.getTracking(id, trackingId)`

**Return value**\
`map` - A map with the result of the tracking request.

Example of the structure returned on success:

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
  "success": true,
  "lastErrorText": "",
  "lastErrorCode": 0,
  "data": <Object>
}
```

The value under `data` is delivered directly by the provider (e.g. DHL) and therefore depends on the respective interface.

If no tracking information could be loaded, `data` is not present and `lastErrorText` and `lastErrorCode` contain the error details from the provider.

**Parameters**

| **Name**     | **Type** | **Required** | **Description**                                                                                                                         |
| ------------ | -------- | ------------ | --------------------------------------------------------------------------------------------------------------------------------------- |
| `id`         | string   | yes          | ID of the shipping service provider (e.g. `DHL`). Configured under [checkout.shipTrack](/en/frontend/funktionsubersicht/bestellablauf). |
| `trackingId` | string   | yes          | Tracking number of the shipping service provider (e.g. the DHL tracking number).                                                        |

**Example** that attempts to load tracking information.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{{ var $tracking = $wsShipTrack.getTracking('DHL', '1234567890') }}
{{ if $tracking.success }}
    // Tracking data loaded.
{{ else }}
    // No tracking data found.
{{ /if }}
```

### \$wsShipTrack.zipCodeConfirmed()

Returns whether the zip code for a specific order has already been confirmed. This check is used before displaying shipment tracking to ensure that the user is indeed the original customer.

**Signature**\
`$wsShipTrack.zipCodeConfirmed(orderId)`

**Return value**\
`bool` - `true` if the zip code for the specified order has already been confirmed, otherwise `false`.

**Parameters**

| **Name**  | **Type** | **Required** | **Description**                                                       |
| --------- | -------- | ------------ | --------------------------------------------------------------------- |
| `orderId` | string   | yes          | ID of the order for which the zip code confirmation is to be checked. |

**Example** that checks whether the zip code has been confirmed.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{{ if $wsShipTrack.zipCodeConfirmed($myOrderId) }}
    // Zip code confirmed.
{{ else }}
    // Zip code not confirmed.
{{ /if }}
```

***

## Examples

### Shipment tracking with zip code check

This example first checks whether the zip code has been confirmed and then displays a corresponding message if tracking data is available.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{{ if $wsShipTrack.zipCodeConfirmed($myOrderId) }}
    <p>Delivery to confirmed zip code.</p>
    {{ var $tracking = $wsShipTrack.getTracking('DHL', $myTrackingId) }}
    {{ if $tracking.success }}
        <p>Tracking information available.</p>
    {{ else }}
        <p>Tracking could not be loaded: {{= $tracking.lastErrorText }}</p>
    {{ /if }}
{{ else }}
    <p>Please confirm your zip code to use shipment tracking.</p>
{{ /if }}
```

***

## Related links

* [\$wsCheckout](/en/frontend/referenz/module/wscheckout)
* [checkout - Order process](/en/konfiguration/checkout-bestellablauf)
* [DHL API (external)](https://developer.dhl.com/api-reference/dhl-paket-de-sendungsverfolgung-post-paket-deutschland?language_content_entity=de\&lang=de#get-started-section)