$wsBasket - Basket - WEBSALE Dokumentation

The $wsBasket module lets you read the data of the current basket in the frontend. This includes the contained products (line items), their quantities and prices, as well as the calculated totals and tax information. This page is about reading the basket data. Everything that changes the basket (add product, change quantity, remove) is described under Actions → Basket, because the triggering actions and their parameters are documented there.

Basic concept

The basket stores the products selected by the customer and automatically calculates quantities, prices, and taxes. Through this module you can read these values and display them.

Structure

The basket data is nested in three levels:

Basket ($wsBasket) - the totals across all line items, e.g. total or totalQuantity.
Line items ($wsBasket.items) - a list of basket entries. Each entry represents a product in the basket and has its own values such as quantity and item total.
Product (item.product) - within each line item there is also the associated product with its master data (name, image, ID).

So you read totals from the basket, item-related values from the respective line item, and product details from the product of the line item.

Tax exemption

Several variables together represent the tax exemption and belong together in terms of content: isTaxExempt is the primary switch, totalTaxDeduction and totalPreDeduction provide the amounts for a “minus VAT” line, and usedExemptionRule together with billingCountry/shippingCountry shows which addresses are used for the check. For tax notices, always check isTaxExempt first.

Timing and last updated item

The template code runs when the page is built. Therefore, $wsBasket contains the basket state after the last executed action. lastBasketAction and lastUpdatedItem describe this last change. Useful, for example, to display feedback such as “Product X was added” directly after adding.

Module overview

Example / excerpt of $wsBasket

{{= $wsBasket | json }}

JSON output

{
  "billingCountry": "...",
  "isTaxExempt": true,
  "items": [
    {
      "discountPrice": 0.0,
      "freeFields": { },
      "id": "...",
      "oneTimeFee": 0.0,
      "orgPrice": 0.0,
      "price": 0.0,
      "product": { },
      "quantity": 0.0,
      "total": 0.0,
      "totalGross": 0.0,
      "totalNet": 0.0,
      "totalTax": 0.0,
      "voucherIds": [...]
    }
  ],
  "lastBasketAction": "...",
  "lastUpdatedItem": {
    "categories": [...],
    "freeFields": { },
    "id": "...",
    "parentCategories": [...],
    "price": 0.0,
    "productNumber": "...",
    "quantity": 0.0,
    "taxId": "...",
    "voucherIds": [...]
  },
  "shippingCountry": "...",
  "total": 0.0,
  "totalCommission": 0.0,
  "totalGross": 0.0,
  "totalNet": 0.0,
  "totalQuantity": 0.0,
  "totalTax": 0.0,
  "totalTaxDeduction": 0.0,
  "totalPreDeduction": 0.0,
  "totalWeight": 0.0,
  "usedExemptionRule": "..."
}

Basket variables (top level)

Variable	Return type	Description
`totalQuantity`	float	Total quantity of all products in the basket.
`total`	float	Total amount of the basket.
`totalNet`	float	Net amount of the basket.
`totalGross`	float	Gross amount of the basket.
`totalTax`	float	VAT of the basket.
`totalCommission`	float	Total commission.
`totalWeight`	float	Total weight of all products in the basket.
`lastBasketAction`	string	Last action on the basket (e.g. `"add"`, `"remove"`, `"update"`).
`lastUpdatedItem`	map	Most recently changed item (structure see below).
`items`	array	List of all basket entries (structure see below).
`isTaxExempt`	bool	Whether the current basket is tax-exempt.
`totalTaxDeduction`	float	Amount of deducted tax; only > 0 when a tax exemption is active.
`totalPreDeduction`	float	Total amount before the tax deduction.
`billingCountry`	string	Country code of the billing address (e.g. `"DE"`).
`shippingCountry`	string	Country code of the shipping address (e.g. `"DE"`).
`usedExemptionRule`	string	Active tax check rule (`"shippingOnly"` or `"shippingAndBilling"`).

Templates

The basket data can be displayed on every page of the shop. Common presentations are:

Offcanvas basket: in a sidebar, as a flyout, or as an off-canvas element, for a quick overview.
Basket page: a detailed overview with adjustment options.
Checkout and order confirmation: display during the purchase process and in confirmation emails.

Variables

$wsBasket.totalQuantity

Returns the total quantity of all products in the basket.

Items in the basket: {{= $wsBasket.totalQuantity }}

$wsBasket.total

Returns the total amount of the basket. Use it for the final total in basket and checkout.

Total amount: {{= $wsBasket.total | currency }}

$wsBasket.totalNet

Returns the net amount of the basket.

Net amount: {{= $wsBasket.totalNet | currency }}

$wsBasket.totalGross

Returns the gross amount of the basket.

Gross amount: {{= $wsBasket.totalGross | currency }}

$wsBasket.totalTax

Returns the VAT of the basket. Use it for a separate tax line in the totals overview.

VAT: {{= $wsBasket.totalTax | currency }}

$wsBasket.totalCommission

Returns the total commission of the basket.

Commission: {{= $wsBasket.totalCommission | currency }}

$wsBasket.totalWeight

Returns the total weight of all products in the basket. Useful, for example, to display a shipping cost or weight notice.

Total weight: {{= $wsBasket.totalWeight }}

$wsBasket.lastBasketAction

Returns the action most recently performed on the basket (e.g. "add", "remove", "update"). Evaluate it to display appropriate feedback after a change.

Last action: {{= $wsBasket.lastBasketAction }}

$wsBasket.lastUpdatedItem

Returns the most recently added or changed item. Use it together with lastBasketAction to display, for example, “Product X was added” directly after adding, without having to search through the entire basket.

Most recently changed: {{= $wsBasket.lastUpdatedItem.id }}
Quantity: {{= int($wsBasket.lastUpdatedItem.quantity) }}

Properties of `$wsBasket.lastUpdatedItem`

Property	Return type	Description
`id`	string	Product ID of the item.
`productNumber`	string	Item number of the item.
`price`	float	Price of the item.
`quantity`	float	Quantity of the item.
`taxId`	string	Tax rate ID of the item.
`categories`	array	Category IDs in which the item is located.
`parentCategories`	array	Parent category IDs of the item.
`freeFields`	map	Free fields of the item.
`voucherIds`	array	Applied voucher IDs for the item.

$wsBasket.items

Returns the list of all basket entries (line items). Iterate over this list to display each line item individually.

{{ foreach $item in $wsBasket.items }}
  Item: {{= $item.product.name }} – Quantity: {{= int($item.quantity) }}
{{ /foreach }}

Properties of an entry in `$wsBasket.items`

Property	Return type	Description
`id`	string	Basket ID of the entry.
`product`	map	The associated product of the entry (master data such as name, image, ID).
`quantity`	float	Quantity of the entry.
`price`	float	Unit price of the entry.
`orgPrice`	float	Original price before discounts.
`discountPrice`	float	Discounted price (if a discount is active).
`oneTimeFee`	float	One-time fee (e.g. setup costs).
`total`	float	Total amount of the entry (item total).
`totalNet`	float	Net amount of the entry.
`totalGross`	float	Gross amount of the entry.
`totalTax`	float	VAT of the entry.
`freeFields`	map	Free fields (e.g. labels, comments).
`voucherIds`	array	Applied voucher IDs for this entry.

$wsBasket.isTaxExempt

Returns whether the current basket is tax-exempt. This is the primary indicator for a tax exemption – use it, for example, to show a notice “Tax-exempt delivery”.

{{ if $wsBasket.isTaxExempt }}
  This basket is tax-exempt.
{{ /if }}

$wsBasket.totalTaxDeduction

Returns the amount of deducted tax. The value is only greater than 0 when a tax exemption is active. In gross shops, you can use it, for example, to display a line “minus VAT”.

{{ if $wsBasket.totalTaxDeduction > 0 }}
  Tax deduction: {{= $wsBasket.totalTaxDeduction | currency }}
{{ /if }}

$wsBasket.totalPreDeduction

Returns the total amount before the tax deduction. Together with totalTaxDeduction, you can show the amount before and after the deduction.

Amount before tax deduction: {{= $wsBasket.totalPreDeduction | currency }}

$wsBasket.billingCountry

Returns the country code of the billing address (e.g. "DE" for Germany).

Billing country: {{= $wsBasket.billingCountry }}

$wsBasket.shippingCountry

Returns the country code of the shipping address (e.g. "DE" for Germany).

Shipping country: {{= $wsBasket.shippingCountry }}

$wsBasket.usedExemptionRule

Returns the active tax check rule. Possible values: "shippingOnly" (only the shipping address is checked) or "shippingAndBilling" (shipping and billing addresses are checked). This shows you which addresses determine the tax exemption.

{{ if $wsBasket.usedExemptionRule }}
  Active check rule: {{= $wsBasket.usedExemptionRule }}
{{ /if }}

Methods

No methods are available for $wsBasket.

Actions

Actions that change the basket (add product, change quantity, remove) are documented separately: Actions → Basket.

Examples for data access

Check whether products are in the basket

First check whether any line items exist at all before displaying the basket, otherwise you would show an empty list.

{{ if $wsBasket.items }}
  <p>The basket contains {{= $wsBasket.items | len }} line items.</p>
{{ else }}
  <p>You have no products in the basket yet.</p>
{{ /if }}

Result
If the basket is filled, the number of line items appears, otherwise a notice about the empty basket.

Display products in the basket

If line items are present, iterate over items and show product name, quantity, and prices for each line item. The totals are placed outside the loop because they would otherwise be output again for each line item.

{{ if $wsBasket.items }}
  {{ foreach $item in $wsBasket.items }}
    <a href="{{= $wsViews.url('Product', {productId: $item.product.id}) }}">
      <img src="{{= $item.product.custom.image.normal }}" alt="{{= $item.product.name }}">
    </a>
    <p>Product name: {{= $item.product.name }}</p>
    <p>Quantity: {{= int($item.quantity) }}</p>
    <p>Unit price: {{= $item.price | currency }}</p>
    <p>Item total: {{= $item.total | currency }}</p>
  {{ /foreach }}

  <p>Shipping costs: {{= $wsCheckout.sum.shippingCost | currency }}</p>
  <p>Grand total: {{= $wsBasket.total | currency }}</p>
{{ else }}
  <p>You have no products in the basket!</p>
{{ /if }}

Result
Each line item is listed with image, name, quantity, and prices. Below, the shipping costs and grand total appear once.

Link to the basket page

Creates a link to the basket page, which is implemented via the view template basket.htm.

<a href="{{= $wsViews.viewUrl('basket.htm') }}">View basket</a>

Result
The link leads to the basket page of the shop.

Further links

Actions → Basket – change the basket (add, modify, remove), because $wsBasket itself only reads.
$wsCheckout – provides supplementary values such as the shipping costs (sum.shippingCost) for the totals display.
$wsViews – generates the product and view URLs used in the examples.
Practical examples basket – end-to-end practical examples for basket functions.

Basic concept

The basket stores the products selected by the customer and automatically calculates quantities, prices, and taxes. Through this module you can read these values and display them.

Structure

The basket data is nested in three levels:

Basket ($wsBasket) - the totals across all line items, e.g. total or totalQuantity.
Line items ($wsBasket.items) - a list of basket entries. Each entry represents a product in the basket and has its own values such as quantity and item total.
Product (item.product) - within each line item there is also the associated product with its master data (name, image, ID).

So you read totals from the basket, item-related values from the respective line item, and product details from the product of the line item.

Tax exemption

Timing and last updated item

{
  "billingCountry": "...",
  "isTaxExempt": true,
  "items": [
    {
      "discountPrice": 0.0,
      "freeFields": { },
      "id": "...",
      "oneTimeFee": 0.0,
      "orgPrice": 0.0,
      "price": 0.0,
      "product": { },
      "quantity": 0.0,
      "total": 0.0,
      "totalGross": 0.0,
      "totalNet": 0.0,
      "totalTax": 0.0,
      "voucherIds": [...]
    }
  ],
  "lastBasketAction": "...",
  "lastUpdatedItem": {
    "categories": [...],
    "freeFields": { },
    "id": "...",
    "parentCategories": [...],
    "price": 0.0,
    "productNumber": "...",
    "quantity": 0.0,
    "taxId": "...",
    "voucherIds": [...]
  },
  "shippingCountry": "...",
  "total": 0.0,
  "totalCommission": 0.0,
  "totalGross": 0.0,
  "totalNet": 0.0,
  "totalQuantity": 0.0,
  "totalTax": 0.0,
  "totalTaxDeduction": 0.0,
  "totalPreDeduction": 0.0,
  "totalWeight": 0.0,
  "usedExemptionRule": "..."
}

Basket variables (top level)

Variable	Return type	Description
`totalQuantity`	float	Total quantity of all products in the basket.
`total`	float	Total amount of the basket.
`totalNet`	float	Net amount of the basket.
`totalGross`	float	Gross amount of the basket.
`totalTax`	float	VAT of the basket.
`totalCommission`	float	Total commission.
`totalWeight`	float	Total weight of all products in the basket.
`lastBasketAction`	string	Last action on the basket (e.g. `"add"`, `"remove"`, `"update"`).
`lastUpdatedItem`	map	Most recently changed item (structure see below).
`items`	array	List of all basket entries (structure see below).
`isTaxExempt`	bool	Whether the current basket is tax-exempt.
`totalTaxDeduction`	float	Amount of deducted tax; only > 0 when a tax exemption is active.
`totalPreDeduction`	float	Total amount before the tax deduction.
`billingCountry`	string	Country code of the billing address (e.g. `"DE"`).
`shippingCountry`	string	Country code of the shipping address (e.g. `"DE"`).
`usedExemptionRule`	string	Active tax check rule (`"shippingOnly"` or `"shippingAndBilling"`).

The basket data can be displayed on every page of the shop. Common presentations are:

Offcanvas basket: in a sidebar, as a flyout, or as an off-canvas element, for a quick overview.
Basket page: a detailed overview with adjustment options.
Checkout and order confirmation: display during the purchase process and in confirmation emails.

$wsBasket.total

Returns the total amount of the basket. Use it for the final total in basket and checkout.

Total amount: {{= $wsBasket.total | currency }}

$wsBasket.totalNet

Returns the net amount of the basket.

Net amount: {{= $wsBasket.totalNet | currency }}

$wsBasket.totalGross

Returns the gross amount of the basket.

Gross amount: {{= $wsBasket.totalGross | currency }}

Returns the VAT of the basket. Use it for a separate tax line in the totals overview.

VAT: {{= $wsBasket.totalTax | currency }}

$wsBasket.totalCommission

Returns the total commission of the basket.

Commission: {{= $wsBasket.totalCommission | currency }}

$wsBasket.totalWeight

Returns the total weight of all products in the basket. Useful, for example, to display a shipping cost or weight notice.

Total weight: {{= $wsBasket.totalWeight }}

$wsBasket.lastBasketAction

Returns the action most recently performed on the basket (e.g. "add", "remove", "update"). Evaluate it to display appropriate feedback after a change.

Last action: {{= $wsBasket.lastBasketAction }}

$wsBasket.lastUpdatedItem

Most recently changed: {{= $wsBasket.lastUpdatedItem.id }}
Quantity: {{= int($wsBasket.lastUpdatedItem.quantity) }}

Properties of `$wsBasket.lastUpdatedItem`

Property	Return type	Description
`id`	string	Product ID of the item.
`productNumber`	string	Item number of the item.
`price`	float	Price of the item.
`quantity`	float	Quantity of the item.
`taxId`	string	Tax rate ID of the item.
`categories`	array	Category IDs in which the item is located.
`parentCategories`	array	Parent category IDs of the item.
`freeFields`	map	Free fields of the item.
`voucherIds`	array	Applied voucher IDs for the item.

$wsBasket.items

Returns the list of all basket entries (line items). Iterate over this list to display each line item individually.

{{ foreach $item in $wsBasket.items }}
  Item: {{= $item.product.name }} – Quantity: {{= int($item.quantity) }}
{{ /foreach }}

Properties of an entry in `$wsBasket.items`

Property	Return type	Description
`id`	string	Basket ID of the entry.
`product`	map	The associated product of the entry (master data such as name, image, ID).
`quantity`	float	Quantity of the entry.
`price`	float	Unit price of the entry.
`orgPrice`	float	Original price before discounts.
`discountPrice`	float	Discounted price (if a discount is active).
`oneTimeFee`	float	One-time fee (e.g. setup costs).
`total`	float	Total amount of the entry (item total).
`totalNet`	float	Net amount of the entry.
`totalGross`	float	Gross amount of the entry.
`totalTax`	float	VAT of the entry.
`freeFields`	map	Free fields (e.g. labels, comments).
`voucherIds`	array	Applied voucher IDs for this entry.

$wsBasket.isTaxExempt

Returns whether the current basket is tax-exempt. This is the primary indicator for a tax exemption – use it, for example, to show a notice “Tax-exempt delivery”.

{{ if $wsBasket.isTaxExempt }}
  This basket is tax-exempt.
{{ /if }}

$wsBasket.totalTaxDeduction

Returns the amount of deducted tax. The value is only greater than 0 when a tax exemption is active. In gross shops, you can use it, for example, to display a line “minus VAT”.

{{ if $wsBasket.totalTaxDeduction > 0 }}
  Tax deduction: {{= $wsBasket.totalTaxDeduction | currency }}
{{ /if }}

$wsBasket.totalPreDeduction

Returns the total amount before the tax deduction. Together with totalTaxDeduction, you can show the amount before and after the deduction.

Amount before tax deduction: {{= $wsBasket.totalPreDeduction | currency }}

$wsBasket.billingCountry

Returns the country code of the billing address (e.g. "DE" for Germany).

Billing country: {{= $wsBasket.billingCountry }}

$wsBasket.shippingCountry

Returns the country code of the shipping address (e.g. "DE" for Germany).

Shipping country: {{= $wsBasket.shippingCountry }}

$wsBasket.usedExemptionRule

{{ if $wsBasket.usedExemptionRule }}
  Active check rule: {{= $wsBasket.usedExemptionRule }}
{{ /if }}

Actions that change the basket (add product, change quantity, remove) are documented separately: Actions → Basket. First check whether any line items exist at all before displaying the basket, otherwise you would show an empty list.

{{ if $wsBasket.items }}
  <p>The basket contains {{= $wsBasket.items | len }} line items.</p>
{{ else }}
  <p>You have no products in the basket yet.</p>
{{ /if }}

Result
If the basket is filled, the number of line items appears, otherwise a notice about the empty basket. If line items are present, iterate over items and show product name, quantity, and prices for each line item. The totals are placed outside the loop because they would otherwise be output again for each line item.

{{ if $wsBasket.items }}
  {{ foreach $item in $wsBasket.items }}
    <a href="{{= $wsViews.url('Product', {productId: $item.product.id}) }}">
      <img src="{{= $item.product.custom.image.normal }}" alt="{{= $item.product.name }}">
    </a>
    <p>Product name: {{= $item.product.name }}</p>
    <p>Quantity: {{= int($item.quantity) }}</p>
    <p>Unit price: {{= $item.price | currency }}</p>
    <p>Item total: {{= $item.total | currency }}</p>
  {{ /foreach }}

  <p>Shipping costs: {{= $wsCheckout.sum.shippingCost | currency }}</p>
  <p>Grand total: {{= $wsBasket.total | currency }}</p>
{{ else }}
  <p>You have no products in the basket!</p>
{{ /if }}

Result
Each line item is listed with image, name, quantity, and prices. Below, the shipping costs and grand total appear once. Creates a link to the basket page, which is implemented via the view template basket.htm.

<a href="{{= $wsViews.viewUrl('basket.htm') }}">View basket</a>

Result
The link leads to the basket page of the shop.

Further links

Actions → Basket – change the basket (add, modify, remove), because $wsBasket itself only reads.
$wsCheckout – provides supplementary values such as the shipping costs (sum.shippingCost) for the totals display.
$wsViews – generates the product and view URLs used in the examples.
Practical examples basket – end-to-end practical examples for basket functions.

​Basic concept

​Structure

​Tax exemption

​Timing and last updated item

​Module overview

​Templates

​Variables

​$wsBasket.totalQuantity

​$wsBasket.total

​$wsBasket.totalNet

​$wsBasket.totalGross

​$wsBasket.totalTax

​$wsBasket.totalCommission

​$wsBasket.totalWeight

​$wsBasket.lastBasketAction

​$wsBasket.lastUpdatedItem

​Properties of $wsBasket.lastUpdatedItem

​$wsBasket.items

​Properties of an entry in $wsBasket.items

​$wsBasket.isTaxExempt

​$wsBasket.totalTaxDeduction

​$wsBasket.totalPreDeduction

​$wsBasket.billingCountry

​$wsBasket.shippingCountry

​$wsBasket.usedExemptionRule

​Methods

​Actions

​Examples for data access

​Check whether products are in the basket

​Display products in the basket

​Link to the basket page

​Further links

​Basic concept

​Structure

​Tax exemption

​Timing and last updated item

​$wsBasket.total

​$wsBasket.totalNet

​$wsBasket.totalGross

​$wsBasket.totalCommission

​$wsBasket.totalWeight

​$wsBasket.lastBasketAction

​$wsBasket.lastUpdatedItem

​Properties of $wsBasket.lastUpdatedItem

​$wsBasket.items

​Properties of an entry in $wsBasket.items

​$wsBasket.isTaxExempt

​$wsBasket.totalTaxDeduction

​$wsBasket.totalPreDeduction

​$wsBasket.billingCountry

​$wsBasket.shippingCountry

​$wsBasket.usedExemptionRule

​Further links

Basic concept

Structure

Tax exemption

Timing and last updated item

Module overview

Templates

Variables

$wsBasket.totalQuantity

$wsBasket.total

$wsBasket.totalNet

$wsBasket.totalGross

$wsBasket.totalTax

$wsBasket.totalCommission

$wsBasket.totalWeight

$wsBasket.lastBasketAction

$wsBasket.lastUpdatedItem

Properties of `$wsBasket.lastUpdatedItem`

$wsBasket.items

Properties of an entry in `$wsBasket.items`

$wsBasket.isTaxExempt

$wsBasket.totalTaxDeduction

$wsBasket.totalPreDeduction

$wsBasket.billingCountry

$wsBasket.shippingCountry

$wsBasket.usedExemptionRule

Methods

Actions

Examples for data access

Check whether products are in the basket

Display products in the basket

Link to the basket page

Further links

Basic concept

Structure

Tax exemption

Timing and last updated item

$wsBasket.total

$wsBasket.totalNet

$wsBasket.totalGross

$wsBasket.totalCommission

$wsBasket.totalWeight

$wsBasket.lastBasketAction

$wsBasket.lastUpdatedItem

Properties of `$wsBasket.lastUpdatedItem`

$wsBasket.items

Properties of an entry in `$wsBasket.items`

$wsBasket.isTaxExempt

$wsBasket.totalTaxDeduction

$wsBasket.totalPreDeduction

$wsBasket.billingCountry

$wsBasket.shippingCountry

$wsBasket.usedExemptionRule

Further links