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

# $wsOrderHistory - Order history

> Reference for $wsOrderHistory: load the customer's past orders, retrieve order details and enable reorders directly from the account area.

With the `$wsOrderHistory` module, you can load and display the order history of a logged-in customer in the frontend. This allows customers to view their past orders, retrieve order details, and place reorders, for example. In this section, you will learn how to load the order list and individual orders.

***

## Module overview

**Example / excerpt of** `$wsOrderHistory`

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

**JSON output**

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

**Note:** `ƒ()` denotes a function.

**Methods overview**

| **Method**   | **Return type** | **Description**                              |
| ------------ | --------------- | -------------------------------------------- |
| `loadList()` | array           | Returns a list of the last 50 orders.        |
| `load()`     | map             | Returns a single order based on an order ID. |

***

## Templates

The order history can be loaded in any template and is typically integrated into the account area. Logged-in customers can view it in the template `orderHistory.htm`.

***

## Variables

No variables are available for `$wsOrderHistory`.

***

## Methods

### \$wsOrderHistory.loadList()

Returns a list of the last 50 orders.

**Signature**\
`$wsOrderHistory.loadList()`

**Return value**\
`Array` - List of order maps.

**Example** that loads the order history into a variable.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{{ var $myOrderListVariable = $wsOrderHistory.loadList() }}
```

### \$wsOrderHistory.load()

Returns a single order based on an order ID.

**Signature**\
`$wsOrderHistory.load(orderId)`

**Return value**\
`Map` - Order map with all order data.

**Parameters**

| **Name**  | **Type** | **Required** | **Description**               |
| --------- | -------- | ------------ | ----------------------------- |
| `orderId` | string   | yes          | ID of the order to be loaded. |

**Example** that loads an order into a variable.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{{ var $order = $wsOrderHistory.load("12345") }}
```

<Info>
  By using the `$wsOrderHistory.load` function, various variables are available to retrieve and output order data. Below is an overview of which variables are available.
</Info>

### Order data (return value of \$wsOrderHistory.load())

First, it is necessary to assign the map with the order data, as shown in the example above, to a local variable. This can then be used at various places in the template.

**JSON output of the variable:**

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
  "general": {
    "orderId": "...",
    "dateTime": "...",
    "shopId": "...",
    "subshopId": "...",
    "sessionId": "...",
    "shopLanguage": "...",
    "testMode": true/false
  },
  "order": {
    "priceType": "...",
    "currencyIso": "...",
    "currencySymbol": "...",
    "defaultTaxRate": "...",
    "paymentId": "...",
    "paymentOrderText": "...",
    "delivererId": "...",
    "delivererOrderText": "...",
    "deliveryCost": "...",
    "deliveryTaxRate": "...",
    "subtotal": "...",
    "total": "...",
    "tax": "...",
    "totalDiscount": "..."
  },
  "customer": {
    "accountType": "...",
    "accountId": "...",
    "email": "...",
    "ipAddress": "..."
  },
  "orderList": {
    "items": [...]
  },
  "billAddress": { ... },
  "shippingAddress": { ... },
  "freeFields": { ... },
  "deliveryStatus": { ... }
}
```

**Variables overview**

General variables:

| **Variable**   | **Type** | **Description**                                     |
| -------------- | -------- | --------------------------------------------------- |
| `general`      | map      | Map with general information about the order.       |
| `orderId`      | string   | ID of the order.                                    |
| `dateTime`     | string   | Date and time of the order.                         |
| `shopId`       | string   | ID of the shop in which the order was placed.       |
| `subshopId`    | string   | ID of the subshop in which the order was placed.    |
| `sessionId`    | string   | ID of the session in which the order was placed.    |
| `shopLanguage` | string   | Language of the shop in which the order was placed. |
| `testMode`     | bool     | Checks whether the order was executed in test mode. |

Order information:

| **Variable**         | **Type** | **Description**                                                        |
| -------------------- | -------- | ---------------------------------------------------------------------- |
| `order`              | map      | Map with data about the order (prices, shipping, payment method, etc.) |
| `priceType`          | string   | Price type: `"net"` or `"gross"`.                                      |
| `currencyIso`        | string   | ISO code of the currency (e.g. `"EUR"`).                               |
| `currencySymbol`     | string   | Currency symbol (e.g. `"€"`).                                          |
| `defaultTaxRate`     | string   | Standard tax rate.                                                     |
| `paymentId`          | string   | ID of the payment method.                                              |
| `paymentOrderText`   | string   | Description of the payment method.                                     |
| `delivererId`        | string   | ID of the shipping method.                                             |
| `delivererOrderText` | string   | Description of the shipping method.                                    |
| `deliveryCost`       | string   | Shipping costs.                                                        |
| `deliveryTaxRate`    | string   | Tax rate of the shipping costs.                                        |
| `subtotal`           | string   | Goods value of the order.                                              |
| `total`              | string   | Total price of the order.                                              |
| `tax`                | string   | Total taxes of the order.                                              |
| `totalDiscount`      | string   | Total discount of the order.                                           |

Customer information:

| **Variable**  | **Type** | **Description**                                   |
| ------------- | -------- | ------------------------------------------------- |
| `customer`    | map      | Map with data about the buyer.                    |
| `accountType` | string   | Account type: `"Guest"` or `"Existing customer"`. |
| `accountId`   | string   | ID of the account.                                |
| `email`       | string   | Email of the buyer.                               |
| `ipAddress`   | string   | IP address of the buyer.                          |

Additional information:

| **Variable**      | **Type** | **Description**                                                                                                                                                                                                                 |
| ----------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `orderList`       | map      | Map with data about ordered items.                                                                                                                                                                                              |
| `items`           | array    | List of ordered products.                                                                                                                                                                                                       |
| `billAddress`     | map      | Map with billing address data.                                                                                                                                                                                                  |
| `shippingAddress` | map      | Map with shipping address data.                                                                                                                                                                                                 |
| `freeFields`      | map      | Map with free fields specified with the order.                                                                                                                                                                                  |
| `deliveryStatus`  | map      | Delivery status of the order (tracking data or manual status text). Only present when a delivery status has been set in the Admin Interface. Details see [Delivery status (`deliveryStatus`)](#delivery-status-deliverystatus). |

#### Delivery status (`deliveryStatus`)

The `deliveryStatus` area contains the delivery status of the order. It is only present when a delivery status has been set for the order in the Admin Interface. Therefore always check the field with `{{ if $order.deliveryStatus }}` before outputting it.

The delivery status is maintained in the Admin Interface under Orders and is distinguished in two ways:

**Scope** (`type`):

* `global` – The status applies to the entire order (all products are delivered in one package).
* `splitted` – The order is delivered in multiple packages; each package carries its own status and a list of the items it contains.

**Status kind** (with `global`: `statusType`; with `splitted`, per package: `deliveryStatusType`):

* `tracking` – A tracking number (`trackingNumber`) and a shipping service provider (`trackingVendorId`) have been recorded. `trackingVendorId` corresponds to the `id` of the [checkout.shipTrack](/en/konfiguration/checkout-bestellablauf#checkout-shiptrack-paketverfolgung) configuration.
* `manual` – A freely worded status text has been entered in the Admin Interface.

`deliveryStatus` is only provided by [`load()`](#wsorderhistory-load). The entries from [`loadList()`](#wsorderhistory-loadlist) do not contain the field – if needed, reload the order via its ID.

Structure for a global status with tracking data:

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
  "deliveryStatus": {
    "type": "global",
    "statusType": "tracking",
    "data": {
      "trackingNumber": "5586666654788855",
      "trackingVendorId": "dhl"
    }
  }
}
```

Structure for a global manual status:

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
  "deliveryStatus": {
    "type": "global",
    "statusType": "manual",
    "data": {
      "status": "Being picked"
    }
  }
}
```

Structure for delivery in multiple packages (`splitted`):

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
  "deliveryStatus": {
    "type": "splitted",
    "packages": [
      {
        "deliveryStatusType": "tracking",
        "data": {
          "trackingNumber": "5586666654788855",
          "trackingVendorId": "dhl"
        },
        "items": [
          {
            "basketId": "62e484ee2283dcab7c14",
            "productId": "237-53337",
            "name": "NextGen X562",
            "quantity": "1.00"
          }
        ]
      }
    ]
  }
}
```

Fields at a glance:

| **Key**                           | **Type** | **Description**                                                                                                                              |
| --------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `type`                            | string   | Scope of the status: `global` (whole order) or `splitted` (per package).                                                                     |
| `statusType`                      | string   | Only for `type: "global"`: kind of status – `tracking` or `manual`.                                                                          |
| `data`                            | map      | Only for `type: "global"`: the status data (see below).                                                                                      |
| `data.trackingNumber`             | string   | Tracking number of the shipping provider (with `tracking`).                                                                                  |
| `data.trackingVendorId`           | string   | ID of the [checkout.shipTrack](/en/konfiguration/checkout-bestellablauf#checkout-shiptrack-paketverfolgung) configuration (with `tracking`). |
| `data.status`                     | string   | Manually entered status text (with `manual`).                                                                                                |
| `packages`                        | array    | Only for `type: "splitted"`: list of packages.                                                                                               |
| `packages[$i].deliveryStatusType` | string   | Kind of status of this package: `tracking` or `manual`.                                                                                      |
| `packages[$i].data`               | map      | Status data of the package (fields as above; with `manual`, the field is called `manualStatus` here).                                        |
| `packages[$i].items`              | array    | Items of the order contained in this package (including `basketId`, `productId`).                                                            |

**Example** \
Display the delivery status of an order. Before display, [`$wsShipTrack.zipCodeConfirmed()`](/en/frontend/referenz/module/wsshiptrack#wsshiptrack-zipcodeconfirmed) is used to check whether the customer has confirmed the ZIP code of the order; if not, the confirmation form of the `ConfirmZipCode` action is shown.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{{ var $order = $wsOrderHistory.load($wsViews.current.params.orderHistorySelect) }}
{{ if $order.deliveryStatus }}
  {{ if $wsShipTrack.zipCodeConfirmed($order.general.orderId) }}

    {{ if $order.deliveryStatus.type == 'global' }}
      {{# Delivery status for the entire order #}}
      {{ if $order.deliveryStatus.statusType == 'manual' }}
        <p><b>Delivery status:</b> {{= $order.deliveryStatus.data.status }}</p>
      {{ /if }}
      {{ if $order.deliveryStatus.statusType == 'tracking' }}
        <p><b>Tracking number:</b> {{= $order.deliveryStatus.data.trackingNumber }}</p>
        <p><b>Shipping provider:</b> {{= $order.deliveryStatus.data.trackingVendorId }}</p>
      {{ /if }}
    {{ /if }}

    {{ if $order.deliveryStatus.type == 'splitted' }}
      {{# Delivery status per package #}}
      {{ foreach $package in $order.deliveryStatus.packages }}
        {{ if $package.deliveryStatusType == 'manual' }}
          <p><b>Delivery status:</b> {{= $package.data.manualStatus }}</p>
        {{ /if }}
        {{ if $package.deliveryStatusType == 'tracking' }}
          <p><b>Tracking number:</b> {{= $package.data.trackingNumber }}</p>
          <p><b>Shipping provider:</b> {{= $package.data.trackingVendorId }}</p>
        {{ /if }}
        {{ foreach $packageItem in $package.items }}
          <p>{{= $packageItem.name }} ({{= $packageItem.quantity }} pcs)</p>
        {{ /foreach }}
      {{ /foreach }}
    {{ /if }}

  {{ else }}
    {{# ZIP not yet confirmed: show confirmation form #}}
    {{ var $actionConfirmZipCode = $wsActions.create('ConfirmZipCode') }}
    <form method="post" action="{{= $wsViews.current.url() }}">
      <input type="hidden" name="wsact" value="{{= $actionConfirmZipCode.id }}">
      <input type="hidden" name="wscsrf" value="{{= $actionConfirmZipCode.csrf }}">
      <input type="hidden" name="orderId" value="{{= $order.general.orderId }}">
      <p>Please confirm the ZIP code of the delivery address to see the delivery status:</p>
      <input type="text" name="zipCode">
      <button type="submit">Confirm</button>
    </form>
  {{ /if }}
{{ /if }}
```

**Result**\
If the delivery status is set and the ZIP code has been confirmed, either the manual status text or the tracking information is shown, depending on the configuration – with package delivery per package including the contained items. As long as the ZIP code has not been confirmed, the confirmation form is shown instead.

***

## Example for displaying order history data

### Display order data

After an order has been loaded from the order history and assigned to a variable, the order data can be accessed via the available maps.

In this example, the order is assigned to the variable `$myOrder`. The order data can be loaded from this variable and freely placed in the template.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{{if $wsViews.current.params.orderHistorySelect}}
	{{var $myOrder = $wsOrderHistory.load($wsViews.current.params.orderHistorySelect)}}
{{ /if }}
```

### General map - general info

The map `$myOrder.general` loads general information such as order ID and order date.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
Order ID: {{= $myOrder.general.orderId }}
Order date: {{= $myOrder.general.dateTime }}
Shop ID: {{= $myOrder.general.shopId }}
Subshop ID: {{= $myOrder.general.subshopId }}
Session ID: {{= $myOrder.general.sessionId }}
Shop language: {{= $myOrder.general.shopLanguage }}
Order placed in test mode: {{ if $myOrder.general.testMode }}True{{ /if }}
```

### Order map - info about the order

The map `$myOrder.order` loads technical info such as costs, payment method, shipping method, and discounts of the order.

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
Price "net" or "gross": {{= $myOrder.order.priceType }}
ISO code of the currency: {{= $myOrder.order.currencyIso }}
Currency symbol: {{= $myOrder.order.currencySymbol }}
Standard tax rate: {{= $myOrder.order.defaultTaxRate }}
ID of payment method: {{= $myOrder.order.paymentId }}
Description of payment method: {{= $myOrder.order.paymentOrderText }}
ID of shipping method: {{= $myOrder.order.delivererId }}
Description of shipping method: {{= $myOrder.order.delivererOrderText }}
Extra costs of shipping method: {{= $myOrder.order.deliveryCost }}
Tax rate of shipping costs: {{= $myOrder.order.deliveryTaxRate }}
Goods value: {{= $myOrder.order.subtotal }}
Total price: {{= $myOrder.order.total }}
Total taxes: {{= $myOrder.order.tax }}
Total discount: {{= $myOrder.order.totalDiscount }}
```

### Customer map - customer info

The map `$myOrder.customer` loads customer info such as address and customer number.

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
Account type ("Guest" or "Existing customer"): {{= $myOrder.customer.accountType }}
Account ID: {{= $myOrder.customer.accountId }}
Buyer's email: {{= $myOrder.customer.email }}
Buyer's IP address: {{= $myOrder.customer.ipAddress }}
```

***

## Actions

No actions are available for `$wsOrderHistory`. For confirming the ZIP code before displaying the delivery status, see the `ConfirmZipCode` action of the [\$wsShipTrack](/en/frontend/referenz/module/wsshiptrack) module.

***

## Related links

* [\$wsAccount](/en/frontend/referenz/module/wsAccount)
* [\$wsShipTrack - Shipment tracking](/en/frontend/referenz/module/wsshiptrack): for a tracking number from `deliveryStatus`, loads the tracking information from the shipping provider and checks the ZIP code confirmation.