$wsOrderHistory - Order history - WEBSALE Dokumentation

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

{{= $wsOrderHistory | json }}

JSON output

{
  "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.

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

{{ var $order = $wsOrderHistory.load("12345") }}

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.

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:

{
  "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`)

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 configuration.
manual – A freely worded status text has been entered in the Admin Interface.

deliveryStatus is only provided by load(). The entries from loadList() do not contain the field – if needed, reload the order via its ID. Structure for a global status with tracking data:

{
  "deliveryStatus": {
    "type": "global",
    "statusType": "tracking",
    "data": {
      "trackingNumber": "5586666654788855",
      "trackingVendorId": "dhl"
    }
  }
}

Structure for a global manual status:

{
  "deliveryStatus": {
    "type": "global",
    "statusType": "manual",
    "data": {
      "status": "Being picked"
    }
  }
}

Structure for delivery in multiple packages (splitted):

{
  "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 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() 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.

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

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

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.

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.

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

$wsAccount
$wsShipTrack - Shipment tracking: for a tracking number from deliveryStatus, loads the tracking information from the shipping provider and checks the ZIP code confirmation.

Frontend

The basics

Getting started

Feature overview

Examples

Reference – Actions

Reference – Language

Reference – Modules

$wsOrderHistory - Order history

Module overview

Templates

Variables

Methods

$wsOrderHistory.loadList()

$wsOrderHistory.load()

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

Delivery status (`deliveryStatus`)

Example for displaying order history data

Display order data

General map - general info

Order map - info about the order

Customer map - customer info

Actions

​Module overview

​Templates

​Variables

​Methods

​$wsOrderHistory.loadList()

​$wsOrderHistory.load()

​Order data (return value of $wsOrderHistory.load())

​Delivery status (deliveryStatus)

​Example for displaying order history data

​Display order data

​General map - general info

​Order map - info about the order

​Customer map - customer info

​Actions

​Related links

Module overview

Templates

Variables

Methods

$wsOrderHistory.loadList()

$wsOrderHistory.load()

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

Delivery status (`deliveryStatus`)

Example for displaying order history data

Display order data

General map - general info

Order map - info about the order

Customer map - customer info

Actions

Related links