$wsCheckout - Checkout - WEBSALE Dokumentation

With the $wsCheckout module, you can read all data of the order process in the frontend. This includes the selected payment and shipping method, billing and delivery address, the order totals, as well as the validation and error status. This page covers reading the checkout data. Everything that changes the checkout (selecting an address, setting the payment method, triggering the order) is documented under Actions → Checkout.

Basic concept

The checkout collects the customer’s selection (payment, shipping, addresses, free fields) and continuously checks whether the order can be executed. Through $wsCheckout, you read this selection and the validation status to design the order flow and provide targeted feedback to the customer.

Validation

There are three levels of validation feedback that differ in granularity. Choose the level based on what you want to display:

Overall status - isValid indicates whether the order as a whole can be executed. Use it, for example, to enable or disable the “Buy” button.
Field state - fieldStates provides a state per field (untouched, empty, invalid, incompatible, valid). Use it, for example, to visually mark a field.
Specific errors - problems provides a list of errors per field with code and text. Use it, for example, to tell the customer exactly how to resolve the error.

Immediate errors and errors after an action

The checkout has two sources of error feedback:

$wsCheckout.problems.* - shown as soon as a field has been selected or left, provided that show*BeforeSubmit is set to true in the configuration. It therefore takes effect even before the customer clicks “Buy”.
actionResponse errors - originate from the server response after an action. For most sections, they are output unfiltered. Exception: for customer data fields and the draft address, there is no problems.*; in those cases, actionResponse errors are filtered via show*BeforeSubmit.

Selection IDs and draft addresses

The selected* variables contain the ID of the respective selected option (e.g. the address ID that you pass to $wsAccount.loadAddress()). If the customer creates a new address during the order flow that is not yet saved in the account, its temporary ID is stored in draftBillAddressId or draftShippingAddressId.

Module overview

Example / excerpt of $wsCheckout

{{= $wsCheckout | json }}

JSON output (abbreviated)

{
  "accountType": "...",
  "customerData": { },
  "freeFields": [...],
  "guestMail": "...",
  "isExpressCheckoutLocked": false,
  "isPPCExpressCheckout": false,
  "isValid": false,
  "problems": {
    "billAddress": [...],
    "clearing": [...],
    "freeFields": [...],
    "general": [...],
    "payment": [...],
    "shippingAddress": [...],
    "shippingMethod": [...]
  },
  "selectedBillAddress": "...",
  "selectedPayment": "...",
  "selectedShippingAddress": "...",
  "selectedShippingMethod": "...",
  "selectedStoreId": 0,
  "sum": { },
  "useAlternativeShippingAddress": false,
  "verificationStatus": 0,
  "verificationStatusOptions": [...],
  "voucherAppliesPerItem": false,
  "fieldStates": { },
  "getAmountInSmallestUnit": "ƒ()",
  "getShippingMethodDisabledErrors": "ƒ()",
  "isFinished": "ƒ()",
  "isPending": "ƒ()",
  "isValidBillAddress": "ƒ()",
  "isValidPayment": "ƒ()",
  "isValidShippingAddress": "ƒ()",
  "isValidShippingMethod": "ƒ()",
  "itemVoucherDiscount": "ƒ()"
}

Note: "ƒ()" denotes a function. Variables overview

Variable	Return type	Description
`accountType`	string	Account type: `"guest"`, `"new"`, or `"registered"`.
`customerData`	map	Customer data fields, including `fieldGroups`.
`freeFields`	array	Free checkout fields (structure see below).
`guestMail`	string	Email of a guest account.
`selectedPayment`	string	ID of the selected payment method.
`selectedShippingMethod`	string	ID of the selected shipping method.
`selectedBillAddress`	string	ID of the selected billing address.
`selectedShippingAddress`	string	ID of the selected delivery address.
`draftBillAddressId`	string	ID of a temporary, not yet saved billing address.
`draftShippingAddressId`	string	ID of a temporary, not yet saved delivery address.
`selectedPseudoCC`	string	Pseudo credit card token.
`selectedStoreId`	int	ID of the selected store (e.g. Click & Collect).
`useAlternativeShippingAddress`	bool	Whether a different delivery address is active.
`isValid`	bool	Whether the order as a whole can be executed.
`isExpressCheckoutLocked`	bool	Whether the express checkout is locked (e.g. after a PayPal payment).
`isPPCExpressCheckout`	bool	Whether the PayPal Commerce Platform Express Checkout is active.
`isPPCApplePayExpressCheckout`	bool	Whether the Apple Pay Express Checkout is active.
`isPPCGooglePayExpressCheckout`	bool	Whether the Google Pay Express Checkout is active.
`problems`	map	Specific errors per area (structure see below).
`fieldStates`	map	State per checkout field (values see below).
`sum`	map	Price information for the checkout (structure see below).
`verificationStatus`	int	Verification status of the order.
`verificationStatusOptions`	array	Available verification status options.
`voucherAppliesPerItem`	bool	Whether vouchers are applied per item.
`restUntilFreeDelivery`	float	Remaining amount until the free shipping threshold (`0` if reached).
`isOrderBlockedByIneffectiveVoucher`	bool	Whether the order is blocked by an ineffective voucher.
`paymentBlocked`	bool	Whether the payment is blocked.
`paymentCaptchaRequired`	bool	Whether a captcha is required for the payment.
`draftBillAddress`	map	Data of the temporary (not yet saved) billing address.

Methods overview

Method	Return type	Description
`isValidPayment()`	bool	Checks whether a payment method is available.
`isValidShippingMethod()`	bool	Checks whether a shipping method is available.
`isValidBillAddress()`	bool	Checks whether an address is valid as a billing address.
`isValidShippingAddress()`	bool	Checks whether an address is valid as a delivery address.
`isPending()`	bool	Checks whether a payment process is pending.
`isFinished()`	bool	Checks whether an order has been completed.
`getAmountInSmallestUnit()`	int	Converts an amount into the smallest currency unit (e.g. cents).
`getShippingMethodDisabledErrors()`	array	Returns why a shipping method is disabled.
`getShippingCost()`	float	Shipping costs of a shipping method, relative to the current basket.
`itemVoucherDiscount()`	float	Calculates the voucher discount for an item.

Templates

The checkout is freely designable and can span one or more shop pages. The order of the elements is arbitrary.

Variables

$wsCheckout.accountType

Returns the account type: "guest" (guest), "new" (new account), or "registered" (logged in). Evaluate it, for example, to offer a guest the option to create an account.

{{ if $wsCheckout.accountType == "guest" }}
  <!-- Guest order -->
{{ /if }}

$wsCheckout.guestMail

Returns the email address of a guest account. Only populated for a guest order.

Email: {{= $wsCheckout.guestMail }}

$wsCheckout.selectedPayment / selectedShippingMethod

Return the ID of the selected payment method or shipping method. Evaluate them to display or check the selection that was made.

{{ if $wsCheckout.selectedPayment == "stripe" }}
  <!-- Stripe is selected -->
{{ /if }}

$wsCheckout.selectedBillAddress / selectedShippingAddress

Return the ID of the selected billing or delivery address. You pass this ID, for example, to $wsAccount.loadAddress() to load the full address.

{{ var $billAddress = $wsAccount.loadAddress($wsCheckout.selectedBillAddress) }}
{{= $billAddress.firstName }} {{= $billAddress.lastName }}

$wsCheckout.draftBillAddressId / draftShippingAddressId

Return the ID of a temporary address that the customer created during the order flow and that is not yet saved in the customer account. It only exists in the current session.

Temporary billing address: {{= $wsCheckout.draftBillAddressId }}

$wsCheckout.useAlternativeShippingAddress

Returns whether a delivery address different from the billing address is used.

{{ if $wsCheckout.useAlternativeShippingAddress }}
  <!-- Different delivery address -->
{{ /if }}

$wsCheckout.selectedStoreId

Returns the ID of the selected store (e.g. for Click & Collect). 0 if no store is selected.

{{ if $wsCheckout.selectedStoreId > 0 }}
  <!-- Store selected -->
{{ /if }}

$wsCheckout.selectedPseudoCC

Returns the pseudo credit card token of the selected payment.

Token: {{= $wsCheckout.selectedPseudoCC }}

$wsCheckout.customerData

Returns the customer data fields as an object structured by groups. Output the actual structure of your shop first, since it depends on the configured fields:

{{= $wsCheckout.customerData | json }}

$wsCheckout.freeFields

Returns the free checkout fields (e.g. T&C checkbox, comment field). Iterate over the fields and evaluate them via their id.

{{ foreach $field in $wsCheckout.freeFields }}
  {{= $field.name }} ({{= $field.type }}, required: {{= $field.required }})
{{ /foreach }}

Properties of a free field

Property	Return type	Description
`id`	string	ID of the field (e.g. `"agb"`, `"comment"`).
`name`	string	Display name of the field (e.g. `"T&C"`).
`type`	string	Field type (`"checkbox"`, `"text"`).
`required`	bool	Whether the field is a required field.
`default`	bool/string	Default value (`false` for checkbox, `""` for text field).
`checked`	bool	Whether the checkbox is checked (only for `type == "checkbox"`).

$wsCheckout.isValid

Returns whether the order as a whole can be executed. This is the overall status across all fields – use it to enable or disable the “Buy” button.

{{ if $wsCheckout.isValid }}
  <!-- Order can be executed -->
{{ /if }}

$wsCheckout.isExpressCheckoutLocked

Returns whether the express checkout is locked – e.g. after the customer has paid via PayPal and is redirected back to the shop for confirmation. Evaluate it to prevent editing of the basket in this state.

{{ if $wsCheckout.isExpressCheckoutLocked }}
  Editing your basket is currently not possible.
{{ /if }}

$wsCheckout.isPPCExpressCheckout / isPPCApplePayExpressCheckout / isPPCGooglePayExpressCheckout

Return whether the respective PayPal Commerce Platform express checkout is active. Use them to display the appropriate express checkout flow.

{{ if $wsCheckout.isPPCExpressCheckout }}
  <!-- PayPal Express Checkout active -->
{{ /if }}

$wsCheckout.verificationStatus / verificationStatusOptions

verificationStatus returns the verification status of the order as a number. verificationStatusOptions lists the possible statuses.

{{ foreach $option in $wsCheckout.verificationStatusOptions }}
  {{= $option.id }}: {{= $option.name }}
{{ /foreach }}

$wsCheckout.voucherAppliesPerItem

Returns whether a voucher is applied per item (instead of on the total amount).

{{ if $wsCheckout.voucherAppliesPerItem }}
  <!-- Voucher is calculated per item -->
{{ /if }}

$wsCheckout.restUntilFreeDelivery

🔧 Shop-checked 12.06.2026: Exists (float, observed 0.0).

Returns the remaining amount until the free shipping threshold (0 if the threshold has been reached). Use it for a “Only X left until free shipping” notice.

{{ if $wsCheckout.restUntilFreeDelivery > 0 }}
  Only {{= $wsCheckout.restUntilFreeDelivery | currency }} left until free shipping!
{{ /if }}

$wsCheckout.fieldStates

Returns a map with the state of each checkout field (payment, shippingMethod, billAddress, shippingAddress). Use it to mark individual fields specifically – e.g. an unfilled field neutrally, a faulty one in red.

Value	Description
`"untouched"`	The field has not yet been edited or selected.
`"empty"`	The field was filled, but the value was removed again.
`"invalid"`	A value is present but failed validation.
`"incompatible"`	The value is valid but not allowed in the current context.
`"valid"`	The field is filled in correctly and has passed all checks.

The states build on each other. The system checks in sequence: selected (untouched) → value present (empty) → valid (invalid) → allowed in context (incompatible). Only when all checks have passed does the field count as valid. The first applicable state is returned.

{{ if $wsCheckout.fieldStates.payment == "valid" }}
  <!-- Payment method correctly selected -->
{{ /if }}

$wsCheckout.problems

Returns a map with specific errors per area (payment, shippingMethod, billAddress, shippingAddress, freeFields, clearing, general). Each area is a list of errors; it is populated when a problem is present there.

Properties of an error

Property	Return type	Description
`code`	string	Error code: `"missing"`, `"checkFailed"`, or `"checkIncompatible"`.
`check`	string	Service name / reason of the check (e.g. `"productTypeDenied"`).
`text`	string	Descriptive error text from the configuration (only if configured).
`field`	string	Affected field (only for field-related errors such as `billAddress`).

Meaning of the error codes

Code	Meaning	Example
`"missing"`	No value selected or entered.	No payment method selected.
`"checkFailed"`	A value is present but failed validation.	Invalid zip code.
`"checkIncompatible"`	The value is valid but not allowed in the current context.	Payment method blocked for the delivery country.

Example that outputs the payment method errors in a customer-friendly way:

{{ foreach $prob in $wsCheckout.problems.payment }}
  {{ if $prob.code == "missing" }}
    Please select a payment method.
  {{ else }}
    {{= $prob.text }}
  {{ /if }}
{{ /foreach }}

clearing (payment processing) and general (general problems) do not contain a field entry. To access an individual error, use the index, e.g. $wsCheckout.problems.payment[0].text.

$wsCheckout.sum

Returns a map with the price information for the checkout. To display a value as a monetary amount, use the currency filter – it already includes the currency symbol.

Properties of `$wsCheckout.sum`

Property	Return type	Description
`total`	float	Total amount of the order (incl. shipping, discounts, taxes).
`totalNet`	float	Net amount.
`totalGross`	float	Gross amount.
`totalTax`	float	Total VAT.
`totalPreDeduction`	float	Total amount before tax deduction.
`totalVoucher`	float	Value of the redeemed vouchers.
`totalWeight`	float	Total weight of the order.
`shippingCost`	float	Shipping costs.
`paymentCost`	float	Costs of the payment method.
`surchargeCost`	float	Extra costs / surcharges.
`currency`	string	Currency code (e.g. `"EUR"`).
`totalTaxDeduction`	float	Amount of deducted tax (in case of tax exemption).
`isTaxExempt`	bool	Whether the order is tax-exempt.
`usedExemptionRule`	string	Active tax check rule (e.g. `"shippingOnly"`).
`billingCountry`	string	Country code of the billing address.
`shippingCountry`	string	Country code of the delivery address.

Total amount: {{= $wsCheckout.sum.total | currency }}
Shipping costs: {{= $wsCheckout.sum.shippingCost | currency }}

Methods

$wsCheckout.isValidPayment() / isValidShippingMethod()

Check whether the payment method or shipping method with the specified ID is available. Use them to offer only available options. Signature
$wsCheckout.isValidPayment(paymentId) · $wsCheckout.isValidShippingMethod(shippingMethodId) Return value
bool – available / not available.

{{ if $wsCheckout.isValidPayment("stripe") }}
  <!-- Stripe is available -->
{{ /if }}

$wsCheckout.isValidBillAddress() / isValidShippingAddress()

Check whether the address with the specified ID is valid as a billing or delivery address. Signature
$wsCheckout.isValidBillAddress(addressId) · $wsCheckout.isValidShippingAddress(addressId) Return value
bool – valid / not valid.

Name	Type	Required	Description
`addressId`	string	yes	ID of the address to be checked.

{{ if $wsCheckout.isValidBillAddress($wsCheckout.selectedBillAddress) }}
  <!-- Billing address is valid -->
{{ /if }}

$wsCheckout.isPending() / isFinished()

isPending() checks whether a payment process is still pending; isFinished() checks whether the order has been completed. Use them to detect the status of an ongoing or completed order. Signature
$wsCheckout.isPending() · $wsCheckout.isFinished() Return value
bool.

{{ if $wsCheckout.isPending() }}
  <!-- Payment process still ongoing -->
{{ /if }}

$wsCheckout.getAmountInSmallestUnit()

Returns an amount in the smallest currency unit (e.g. cents instead of euros). Useful for payment APIs that expect amounts in cents. Signature
$wsCheckout.getAmountInSmallestUnit(amount) Return value
int – amount in the smallest unit.

Name	Type	Required	Description
`amount`	float	yes	Amount in the main currency.

{{ var $cents = $wsCheckout.getAmountInSmallestUnit($wsCheckout.sum.total) }}

$wsCheckout.getShippingMethodDisabledErrors()

Returns why a shipping method is disabled. Use it to explain to the customer why a shipping method cannot be selected. Signature
$wsCheckout.getShippingMethodDisabledErrors(shippingMethodId) Return value
array – list of error messages.

Name	Type	Required	Description
`shippingMethodId`	string	yes	ID of the shipping method to be checked.

{{ foreach $error in $wsCheckout.getShippingMethodDisabledErrors("express") }}
  {{= $error }}
{{ /foreach }}

$wsCheckout.itemVoucherDiscount()

Calculates the voucher discount for a single basket item. Pass the ID of a basket entry. Signature
$wsCheckout.itemVoucherDiscount(itemId) Return value
float – discount amount for the item.

Name	Type	Required	Description
`itemId`	string	yes	ID of the basket entry.

Discount: {{= $wsCheckout.itemVoucherDiscount($item.id) | currency }}

$wsCheckout.getShippingCost()

Returns the shipping costs of a specific shipping method, even if it is not selected. The value is based on the current basket. Use it, for example, to display the shipping costs of various options in advance. Signature
$wsCheckout.getShippingCost(shippingMethodId) Return value
float – shipping costs of the specified shipping method.

Name	Type	Required	Description
`shippingMethodId`	string	yes	ID of the shipping method whose costs are to be determined.

Shipping costs: {{= $wsCheckout.getShippingCost("dhl_standard") | currency }}

Actions

Actions that change the checkout (selecting an address, setting the payment method, triggering the order) are documented separately: Actions → Checkout.

Examples

Check whether the order can be placed and display errors

This example combines the validation levels:
If the order is valid, the “Buy” area is shown; otherwise the specific problems are listed.

{{ if $wsCheckout.isValid }}
  <!-- Show buy button -->
{{ else }}
  {{ foreach $prob in $wsCheckout.problems.payment }}
    {{= $prob.text }}
  {{ /foreach }}
  {{ foreach $prob in $wsCheckout.problems.shippingMethod }}
    {{= $prob.text }}
  {{ /foreach }}
  {{ foreach $prob in $wsCheckout.problems.billAddress }}
    {{= $prob.field }}: {{= $prob.text }}
  {{ /foreach }}
{{ /if }}

Result
For a valid order, the buy area appears; otherwise the open items per area are shown.

Totals overview

A complete totals display. The currency filter already includes the currency symbol.

Subtotal: {{= $wsCheckout.sum.totalNet | currency }}
Shipping costs: {{= $wsCheckout.sum.shippingCost | currency }}
VAT: {{= $wsCheckout.sum.totalTax | currency }}
{{ if $wsCheckout.sum.totalVoucher > 0 }}
  Voucher: {{= $wsCheckout.sum.totalVoucher | currency }}
{{ /if }}
Total amount: {{= $wsCheckout.sum.total | currency }}

Result
A breakdown of totals with correctly formatted monetary amounts.

Check T&C acceptance

Checks whether the free field agb is checked before the order is allowed.

{{ foreach $field in $wsCheckout.freeFields }}
  {{ if $field.id == "agb" and not $field.checked }}
    Please accept the terms and conditions.
  {{ /if }}
{{ /foreach }}

Result
If the T&C checkbox is not checked, the notice appears.

Check the selected payment method

{{ if $wsCheckout.isValidPayment($wsCheckout.selectedPayment) }}
  Selected payment method: {{= $wsCheckout.selectedPayment }}
{{ /if }}

Result
The selected payment method is shown if it is valid.

Actions → Checkout – change the checkout (set selection, trigger order), since $wsCheckout itself is read-only.
$wsBasket – the basket on which the checkout is built; provides the items for itemVoucherDiscount().
$wsAccount – uses loadAddress() to load the full address for selectedBillAddress/selectedShippingAddress.
Checkout configuration – controls when errors are displayed via show*BeforeSubmit.

​Basic concept

​Validation

​Immediate errors and errors after an action

​Selection IDs and draft addresses

​Module overview

​Templates

​Variables

​$wsCheckout.accountType

​$wsCheckout.guestMail

​$wsCheckout.selectedPayment / selectedShippingMethod

​$wsCheckout.selectedBillAddress / selectedShippingAddress

​$wsCheckout.draftBillAddressId / draftShippingAddressId

​$wsCheckout.useAlternativeShippingAddress

​$wsCheckout.selectedStoreId

​$wsCheckout.selectedPseudoCC

​$wsCheckout.customerData

​$wsCheckout.freeFields

​Properties of a free field

​$wsCheckout.isValid

​$wsCheckout.isExpressCheckoutLocked

​$wsCheckout.isPPCExpressCheckout / isPPCApplePayExpressCheckout / isPPCGooglePayExpressCheckout

​$wsCheckout.verificationStatus / verificationStatusOptions

​$wsCheckout.voucherAppliesPerItem

​$wsCheckout.restUntilFreeDelivery

​$wsCheckout.fieldStates

​$wsCheckout.problems

​Properties of an error

​Meaning of the error codes

​$wsCheckout.sum

​Properties of $wsCheckout.sum

​Methods

​$wsCheckout.isValidPayment() / isValidShippingMethod()

​$wsCheckout.isValidBillAddress() / isValidShippingAddress()

​$wsCheckout.isPending() / isFinished()

​$wsCheckout.getAmountInSmallestUnit()

​$wsCheckout.getShippingMethodDisabledErrors()

​$wsCheckout.itemVoucherDiscount()

​$wsCheckout.getShippingCost()

​Actions

​Examples

​Check whether the order can be placed and display errors

​Totals overview

​Check T&C acceptance

​Check the selected payment method

​Related links

Basic concept

Validation

Immediate errors and errors after an action

Selection IDs and draft addresses

Module overview

Templates

Variables

$wsCheckout.accountType

$wsCheckout.guestMail

$wsCheckout.selectedPayment / selectedShippingMethod

$wsCheckout.selectedBillAddress / selectedShippingAddress

$wsCheckout.draftBillAddressId / draftShippingAddressId

$wsCheckout.useAlternativeShippingAddress

$wsCheckout.selectedStoreId

$wsCheckout.selectedPseudoCC

$wsCheckout.customerData

$wsCheckout.freeFields

Properties of a free field

$wsCheckout.isValid

$wsCheckout.isExpressCheckoutLocked

$wsCheckout.isPPCExpressCheckout / isPPCApplePayExpressCheckout / isPPCGooglePayExpressCheckout

$wsCheckout.verificationStatus / verificationStatusOptions

$wsCheckout.voucherAppliesPerItem

$wsCheckout.restUntilFreeDelivery

$wsCheckout.fieldStates

$wsCheckout.problems

Properties of an error

Meaning of the error codes

$wsCheckout.sum

Properties of `$wsCheckout.sum`

Methods

$wsCheckout.isValidPayment() / isValidShippingMethod()

$wsCheckout.isValidBillAddress() / isValidShippingAddress()

$wsCheckout.isPending() / isFinished()

$wsCheckout.getAmountInSmallestUnit()

$wsCheckout.getShippingMethodDisabledErrors()

$wsCheckout.itemVoucherDiscount()

$wsCheckout.getShippingCost()

Actions

Examples

Check whether the order can be placed and display errors

Totals overview

Check T&C acceptance

Check the selected payment method

Related links