Checkout - WEBSALE Dokumentation

This section describes the available actions in the checkout. With these actions, billing and shipping addresses can be selected, cached, and applied, for example.

Actions overview

Action	Description
`CheckoutAccountTypeSelect`	Sets the account type for the current order process.
`CheckoutBillAddressSelect`	Sets a saved address as the active billing address.
`CheckoutShippingAddressSelect`	Sets a saved address as the active shipping address.
`CheckoutSetDraftAddress`	Saves an address temporarily as a draft (without validation).
`CheckoutCommitDraftAddress`	Applies an address draft as the binding checkout address (with validation).
`CheckoutUseSameShippingAddress`	Sets the shipping address to be the same as the billing address.
`CheckoutUseDifferentShippingAddress`	Activates a different shipping address.
`CheckoutSetGuestEmail`	Sets the email address for a guest order.
`CheckoutPaymentUpdate`	Sets the payment method for the current order process.
`CheckoutShippingMethodUpdate`	Sets the shipping method for the current order process.
`CheckoutConfirm`	Submits the order in a binding manner.
`CheckoutSetFreeFields`	Sets the free checkout fields, e.g., terms and conditions consent.
`CheckoutSetCustomerData`	Sets customer data in the checkout.
`CheckoutPseudoCCSelect`	Selects a saved pseudo credit card.
`CheckoutNewsletterSubscribe`	Subscribes the customer to the newsletter during the checkout.
`CheckoutSetVerificationStatus`	Sets the verification status of the order. (Documentation to follow)
`CheckoutStoreIdSelect`	Sets a store as the pickup location for the current order process.

Actions

CheckoutBillAddressSelect

With this action, the customer selects one of their already saved addresses as the billing address for the current order process. The selection is applied immediately; no further confirmation is needed. Usage example
Useful for displaying a dropdown of their saved addresses to logged-in customers in the checkout, so they can select a billing address with a single click without re-entering data. Parameters

Name	Description
`addressId`	The ID of the address to be set as the billing address.

Error codes

Error code	Description
`missingAddressId`	Parameter `addressId` is missing.
`invalidAddressId`	The specified address does not exist or does not belong to this customer account.

Related modules, variables & methods

Example showing how logged-in customers are presented with a dropdown of their saved addresses, through which they can select a billing address.

{{ var $myCheckoutBillAddressSelect = $wsActions.create("CheckoutBillAddressSelect") }}
<form method="post" action="{{= $wsViews.current.url() }}" data-auto-submit-change>
    <input type="hidden" name="wsact" value="{{= $myCheckoutBillAddressSelect.id }}">
    <input type="hidden" name="wscsrf" value="{{= $myCheckoutBillAddressSelect.csrf }}">
    <select name="addressId">
        {{ foreach $myAddressOption in $wsAccount.addresses }}
            <option value="{{= $myAddressOption.id }}"{{ if $myAddressOption.id == $wsCheckout.selectedBillAddress }} selected{{ /if }}>
                {{= $myAddressOption.firstName }} {{= $myAddressOption.lastName }}, {{= $myAddressOption.street }}
            </option>
        {{ /foreach }}
    </select>
</form>

CheckoutShippingAddressSelect

With this action, the customer selects one of their already saved addresses as the shipping address for the current order process. The action is only relevant if the customer wants to specify a different shipping address. Usage example
Useful when a customer wants to ship an order to a different address. Parameters

Name	Description
`addressId`	The ID of the address to be set as the shipping address.

Error codes

Error code	Description
`missingAddressId`	Parameter `addressId` is missing.
`invalidAddressId`	The specified address does not exist or does not belong to this customer account.

Related modules, variables & methods

Example showing how logged-in customers are presented with a dropdown of their saved addresses, through which they can select a shipping address.

{{ var $myCheckoutShippingAddressSelect = $wsActions.create("CheckoutShippingAddressSelect") }}
<form method="post" action="{{= $wsViews.current.url() }}" data-auto-submit-change>
    <input type="hidden" name="wsact" value="{{= $myCheckoutShippingAddressSelect.id }}">
    <input type="hidden" name="wscsrf" value="{{= $myCheckoutShippingAddressSelect.csrf }}">
    <select name="addressId">
        {{ foreach $myAddressOption in $wsAccount.addresses }}
            <option value="{{= $myAddressOption.id }}"{{ if $myAddressOption.id == $wsCheckout.selectedShippingAddress }} selected{{ /if }}>
                {{= $myAddressOption.firstName }} {{= $myAddressOption.lastName }}
            </option>
        {{ /foreach }}
    </select>
</form>

CheckoutSetDraftAddress

With this action, an address entered by the customer is temporarily saved without the entries being immediately checked for completeness or correctness. The draft address already affects the available shipping and payment methods, which are adjusted based on the entries (relevant for the OnePage checkout). The address is initially considered a draft and is applied as the binding checkout address only by CheckoutCommitDraftAddress. The address type is specified directly in the action name (bill or shipping). Usage example
Useful in the OnePage checkout to continuously cache the entered address without immediately confronting the customer with validation errors. The actual check of the address only takes place when “Buy now” is clicked, via CheckoutCommitDraftAddress. Parameters

Name	Description
`address.(fieldname)`	The individual fields of the address, e.g., `address.firstName`, `address.street`, etc.

Related modules, variables & methods

Example showing how a billing address is cached as a draft without being validated immediately.

{{ var $myActionSetDraftBillAddress = $wsActions.create("CheckoutSetDraftAddress:bill") }}
<form method="post" action="{{= $wsViews.current.url() }}" data-ws-ajax-form>
    <input type="hidden" name="wsact" value="{{= $myActionSetDraftBillAddress.id }}">
    <input type="hidden" name="wscsrf" value="{{= $myActionSetDraftBillAddress.csrf }}">
    <input type="text" name="address.firstName">
    <input type="text" name="address.lastName">
    <input type="text" name="address.street">
    <input type="text" name="address.zip">
    <input type="text" name="address.city">
    <button type="submit">Save address</button>
</form>

CheckoutCommitDraftAddress

With this action, an address draft previously saved via CheckoutSetDraftAddress is validated and applied as the checkout address. The behavior differs depending on the order type:

Guest order - the entered address is checked and, if valid, applied directly for the checkout.
Order with customer account - the entered address is checked and, if valid, created as a new address in the customer account and selected for the current checkout at the same time.

If the data is incorrect or incomplete, validation fails and the draft is retained so the customer can correct their entries. The address type is specified directly in the action name (bill or shipping). Together with CheckoutSetDraftAddress, this action forms the typical address workflow in the OnePage checkout:
CheckoutSetDraftAddress continuously caches the entries (without validation); CheckoutCommitDraftAddress completes the process. Usage example
Useful as the final step in the OnePage checkout. The customer has already entered their address, and only when “Buy now” is clicked is it checked whether all information is correct and complete. Parameters

Name	Description
`address.(fieldname)`	The individual fields of the address, e.g., `address.firstName`, `address.street`, etc.

Error codes

Error code	Description
`addressCheckFailed`	Error in the address data. Specified via sub-codes: - `minlen` = too few characters - `maxlen` = too many characters - `numeric` = invalid characters - `country` = country not configured - `zip` = postal code incorrect

Related modules, variables & methods

Example showing how a billing address draft is validated and applied as the binding checkout address. In case of incorrect entries, the draft is retained and errors are output.

{{ var $myActionCommitDraftBillAddress = $wsActions.create("CheckoutCommitDraftAddress:bill") }}
{{ include "components/errorAlert.htm" with $myAction = $myActionCommitDraftBillAddress }}
<form method="post" action="{{= $wsViews.current.url() }}">
    <input type="hidden" name="wsact" value="{{= $myActionCommitDraftBillAddress.id }}">
    <input type="hidden" name="wscsrf" value="{{= $myActionCommitDraftBillAddress.csrf }}">
    <input type="text" name="address.firstName">
    <input type="text" name="address.lastName">
    <input type="text" name="address.street">
    <input type="text" name="address.zip">
    <input type="text" name="address.city">
    <button type="submit">Apply as address.</button>
</form>

CheckoutUseSameShippingAddress

With this action, it is specified that delivery should be made to the same address as the billing address. A previously entered or selected different shipping address is not deleted but is no longer taken into account for the checkout. Usage example
Useful for giving the customer the option, e.g., via a checkbox, to equate billing and shipping addresses with a single click without re-entering data. Related modules, variables & methods

Example showing how the action is triggered via a hidden form that can be coupled to a checkbox via JavaScript.

{{ var $myActionCheckoutUseSameShippingAddress = $wsActions.create("CheckoutUseSameShippingAddress") }}
<form method="post" action="{{= $wsViews.current.url() }}">
    <input type="hidden" name="wsact" value="{{= $myActionCheckoutUseSameShippingAddress.id }}">
    <input type="hidden" name="wscsrf" value="{{= $myActionCheckoutUseSameShippingAddress.csrf }}">
    <button type="submit">Confirm action.</button>
</form>

CheckoutUseDifferentShippingAddress

With this action, a different shipping address is activated for the checkout. As soon as it has been triggered, the area for selecting or entering a separate shipping address becomes relevant. The action reverses the effect of CheckoutUseSameShippingAddress. Usage example
Useful when the customer wants an order to be delivered to a different address, e.g., directly to a branch. Related modules, variables & methods

Example showing how the action is triggered via a hidden form that can be coupled to a checkbox via JavaScript.

{{ var $myActionCheckoutUseDifferentShippingAddress = $wsActions.create("CheckoutUseDifferentShippingAddress") }}
<form method="post" action="{{= $wsViews.current.url() }}">
    <input type="hidden" name="wsact" value="{{= $myActionCheckoutUseDifferentShippingAddress.id }}">
    <input type="hidden" name="wscsrf" value="{{= $myActionCheckoutUseDifferentShippingAddress.csrf }}">
    <button type="submit">Confirm action.</button>
</form>

CheckoutAccountTypeSelect

With this action, the account type for the current order process is set. The selected type determines which steps are displayed in the checkout process. Usage example
Useful on the login page in the checkout context to give the customer the option of ordering as a guest without having to create an account. Parameters

Name	Description
`accountType`	The desired account type. Possible values: - `guest` - Guest account - `new` - New customer account - `registered` - Registered customer

Error codes

Error code	Description
`invalidAccountType`	The specified account type is invalid.

Related modules, variables & methods

Example showing how the account type is set to “guest” to enable a guest order.

{{ var $myActionCheckoutAccountTypeSelect = $wsActions.create("CheckoutAccountTypeSelect") }}
<form method="post" action="{{= $wsViews.current.url() }}">
    <input type="hidden" name="wsact" value="{{= $myActionCheckoutAccountTypeSelect.id }}">
    <input type="hidden" name="wscsrf" value="{{= $myActionCheckoutAccountTypeSelect.csrf }}">
    <input type="hidden" name="accountType" value="guest">
    <button type="submit">Order as guest.</button>
</form>

CheckoutSetGuestEmail

With this action, the email address for a guest order is set. It is only relevant if the account type has been set to “guest”. Usage example
Useful in the checkout when a customer wants to order as a guest and needs to provide their email address for this. Parameters

Name	Description
`guestEmail`	The email address of the guest customer.

Error codes

Code	Description
`missingEmail`	Parameter `guestEmail` is missing.
`emailCheckFailed`	Parameter `guestEmail` does not contain a valid email address.

Related modules, variables & methods

Example showing how a guest customer enters their email address in the checkout, including error output on invalid input.

{{ var $myActionCheckoutSetGuestEmail = $wsActions.create("CheckoutSetGuestEmail") }}
<form method="post" action="{{= $wsViews.current.url() }}">
    <input type="hidden" name="wsact" value="{{= $myActionCheckoutSetGuestEmail.id }}">
    <input type="hidden" name="wscsrf" value="{{= $myActionCheckoutSetGuestEmail.csrf }}">
    <input type="text" name="guestEmail" value="{{= $wsCheckout.guestMail | ifNull('') }}">
    <button type="submit">Order as guest.</button>
</form>

CheckoutShippingMethodUpdate

With this action, the shipping method for the current order process is set. Usage example
Useful in the checkout to display a list of available shipping methods to the customer, from which they can select one. Parameters

Name	Description
`shippingMethodId`	The ID of the shipping method to be selected.

Error codes

Error code	Description
`missingShippingMethodId`	Parameter `shippingMethodId` is missing.
`invalidShippingMethodId`	The specified shipping method is not available.

Related modules, variables & methods

Example showing how all available shipping methods are displayed as a selection list, with unavailable options being disabled.

{{ var $myActionCheckoutShippingMethodUpdate = $wsActions.create("CheckoutShippingMethodUpdate") }}
<form method="post" action="{{= $wsViews.current.url() }}" data-auto-submit-change>
    <input type="hidden" name="wsact" value="{{= $myActionCheckoutShippingMethodUpdate.id }}">
    <input type="hidden" name="wscsrf" value="{{= $myActionCheckoutShippingMethodUpdate.csrf }}">
    {{ foreach $myShipping in $wsConfig.shippingMethods }}
        <input type="radio" name="shippingMethodId" id="{{= $myShipping.id }}" value="{{= $myShipping.id }}"
            {{ if $wsCheckout.selectedShippingMethod == $myShipping.id }} checked{{ /if }}
            {{ if not $wsCheckout.isValidShippingMethod($myShipping.id) }} disabled{{ /if }}>
        <label for="{{= $myShipping.id }}">{{= $myShipping.name }}</label>
    {{ /foreach }}
</form>

CheckoutConfirm

With this action, the order is submitted in a binding manner. It is the final step in the checkout process and requires that all required information — address, payment method, and shipping method — is complete and valid. Usage example
Useful as the “Buy now” button on the order overview page, through which the customer places the order in a binding manner. Error codes

Error code	Description
`notLoggedIn`	The user is not logged in and no guest email is available.
`invalidCheckout`	The checkout is not complete or contains invalid information.

Related modules, variables & methods

Example showing how the order is submitted in a binding manner via a button, provided that the customer is logged in or identified as a guest.

{{ var $myActionCheckoutConfirm = $wsActions.create("CheckoutConfirm") }}
<form method="post" action="{{= $wsViews.current.url() }}">
    <input type="hidden" name="wsact" value="{{= $myActionCheckoutConfirm.id }}">
    <input type="hidden" name="wscsrf" value="{{= $myActionCheckoutConfirm.csrf }}">
    <input type="hidden" name="wstarget" value="{{= $wsViews.viewUrl('confirm.htm') }}">
    <button type="submit">Place order.</button>
</form>

CheckoutSetFreeFields

With this action, the free checkout fields are set, e.g., consent to the terms and conditions or a comment field. The action is typically used together with CheckoutConfirm on the order overview page. Usage example
Useful on the order overview page to display a checkbox to the customer for consent to the terms and conditions, which must be accepted before submitting the order. Parameters

Name	Description
`freeFields.(id).value`	The value of the free field, e.g., `freeFields.agb.value` for the terms checkbox.

Error codes

Error code	Description
`missingRequiredField`	A required field was not filled in.

Related modules, variables & methods

Example showing how a terms and conditions checkbox is embedded as a free checkout field.

{{ var $myActionSetFreeFields = $wsActions.create("CheckoutSetFreeFields") }}
<form method="post" action="{{= $wsViews.current.url() }}" data-auto-submit-change>
    <input type="hidden" name="wsact" value="{{= $myActionSetFreeFields.id }}">
    <input type="hidden" name="wscsrf" value="{{= $myActionSetFreeFields.csrf }}">
    {{ foreach $cField in $wsCheckout.freeFields }}
        {{ if $cField.id == "agb" }}
            <input type="{{= $myField.type }}" name="freeFields.{{= $myField.id }}.value"{{ if $myField.checked }} checked{{ /if }}>
            <label>Accept terms and conditions.</label>
        {{ /if }}
    {{ /foreach }}
</form>

CheckoutSetCustomerData

With this action, additional customer data is set in the checkout. The fields are loaded dynamically from the configuration and can be grouped or ungrouped. Usage example
Useful in the checkout to query configured customer data fields (e.g., company name, phone) that go beyond the standard address. Parameters

Name	Description
`(dynamic)`	The fields are loaded from $wsCheckout.customerData and vary depending on the shop configuration.

Related modules, variables & methods

Example showing how grouped customer data fields are rendered dynamically and errors are output field-specifically:

{{ var $setCustomerDataAction = $wsActions.create("CheckoutSetCustomerData") }}
<form method="post" action="{{= $wsViews.current.url() }}" data-ajax-form data-auto-submit-change>
    <input type="hidden" name="wsact" value="{{= $setCustomerDataAction.id }}">
    <input type="hidden" name="wscsrf" value="{{= $setCustomerDataAction.csrf }}">
    <input type="hidden" name="wstarget" value="{{= $wsViews.current.url() }}">
    {{ foreach $error in $setCustomerDataAction.errors }}
        <div class="alert alert-danger">{{= $error.text | ifNull($error.code) }}</div>
    {{ /foreach }}
    {{ foreach $group in $wsCheckout.customerData.groupedFields }}
        {{ if $group.hidden == false }}
            <label>{{= $group.label | ifNull($group.name) }}</label>
            {{ foreach $field in $group.fields }}
                {{include "components/src/customerDataField.htm" with $field=$field }}
                {{ if $setCustomerDataAction.errorsByField[$field.name] }}
                    {{ foreach $err in $setCustomerDataAction.errorsByField[$field.name] }}
                        <div class="alert alert-danger">{{= $error.code }}{{ if $error.subCode }} ({{= $error.subCode }}){{ /if }}</div>
                    {{ /foreach }}
                {{ /if }}
            {{ /foreach }}
        {{ /if }}
    {{ /foreach }}
</form>

CheckoutPseudoCCSelect

With this action, the customer selects one of their saved pseudo credit cards for the current order process. The action is exclusively relevant for the Computop credit card integration. Usage example
Useful in the checkout when the customer wants to use a previously stored credit card without re-entering the card data. The value 0 stands for “do not use a saved card”. Parameters

Name	Description
`pseudoCCId`	The ID of the saved pseudo credit card. The value `0` selects no card.

Related modules, variables & methods

Example showing how saved credit cards are displayed for selection, including the option to use no card.

{{ var $myAction = $wsActions.create("CheckoutPseudoCCSelect") }}
<form method="POST" action="{{= $wsViews.current.url() }}" data-ajax-form data-auto-submit-change>
    <input type="hidden" name="wsact" value="{{= $myAction.id }}">
    <input type="hidden" name="wscsrf" value="{{= $myAction.csrf }}">
    <input type="hidden" name="wstarget" value="{{= $wsViews.current.url() }}">
    {{ if $action.error }}
        {{ foreach $error in $action.errors }}
            <div class="alert alert-danger">{{= $error.text | ifNull($error.code) }}</div>
        {{ /foreach }}
    {{ /if }}
    {{ foreach $card in $wsAccount.pseudoCreditCards }}
        <label>
            <input type="radio" name="pseudoCCId" value="{{= $card.id }}"
                {{ if $wsCheckout.selectedPseudoCC == $card.id }} checked{{ /if }}>
            {{= $card.type }} – Card number: {{= $card.number }},
            Expiration date: {{= $card.expireMonth }}/{{= $card.expireYear }}
        </label>
    {{ /foreach }}
    <label>
        <input type="radio" name="pseudoCCId" value="0"
            {{ if $wsCheckout.selectedPseudoCC == '0' }} checked{{ /if }}>
        Do not select a card
    </label>
</form>

CheckoutNewsletterSubscribe

With this action, a customer is subscribed to the newsletter during the order process. It works analogously to the NewsletterSubscribe action — parameters, error codes, and field-passing behavior are identical. Usage example
Useful in the checkout to give customers the option of subscribing to the newsletter during the order process, for example via a checkbox on the order overview page. Parameters

Name	Description
`email`	The email address to be subscribed to the newsletter.
`targetGroupId.(id)`	Optional target group ID to which the customer should be subscribed.

Error codes

Error code	Description
`missingEmail`	Parameter `email` is missing.
`emailCheckFailed`	The specified email address is invalid.
`accountAlreadyExists`	The email address is already subscribed to the newsletter.

Related modules, variables & methods

Example showing how a customer in the checkout selects a target group and subscribes to the newsletter.

{{ var $myActionCheckoutNewsletterSubscribe = $wsActions.create("CheckoutNewsletterSubscribe") }}
<form method="post" action="{{= $wsViews.current.url() }}">
    <input type="hidden" name="wscsrf" value="{{= $myActionCheckoutNewsletterSubscribe.csrf }}">
    <input type="hidden" name="wsact" value="{{= $myActionCheckoutNewsletterSubscribe.id }}">
    {{ if $myActionCheckoutNewsletterSubscribe.success }}
        <div class="alert alert-success">Newsletter successfully subscribed.</div>
    {{ /if }}
    {{ foreach $myNewsletterList in $wsNewsletter.getTargetGroups() }}
        <input type="checkbox" value="{{= $myNewsletterList.id }}" name="targetGroupId.{{= $myNewsletterList.id }}">
        <label>{{= $myNewsletterList.name }}</label>
    {{ /foreach }}
    <input type="email" name="email">
    <button type="submit">Subscribe to newsletter</button>
</form>

CheckoutStoreIdSelect

With this action, the customer selects a store as the pickup location for the current order process. The action is only relevant if a shipping method of type pickup has been selected. During selection, it is checked whether all products are available in the selected store. If this is not the case, the action is not executed and an error is returned.
If no store has been selected, the store from the general session selection is used by default. Usage example
Useful when the customer wants to pick up an order directly in a store and should choose from the available Click & Collect stores in the checkout. Error codes

Error code	Description
`reservationFailed`	The items are not available in the selected store. Details on the affected product are returned via `error.details.productId`.

Related modules, variables & methods

Example that shows, for each shipping method of type pickup, a dropdown with all Click & Collect-capable stores. It sets the selected store as the pickup location via CheckoutStoreIdSelect, including error handling for items not available in the selected store.

{{ var $myActionCheckoutStoreIdSelect = $wsActions.create("CheckoutStoreIdSelect") }}
{{ foreach $myShipping in $wsConfig.shippingMethods }}
    {{ if $wsCheckout.selectedShippingMethod == $myShipping.id and $myShipping.type == "pickup" }}
        <form method="post" action="{{= $wsViews.current.url() }}" data-auto-submit-change>
            <input type="hidden" name="wsact" value="{{= $myActionCheckoutStoreIdSelect.id }}">
            <input type="hidden" name="wscsrf" value="{{= $myActionCheckoutStoreIdSelect.csrf }}">
            <select name="storeId">
                {{ foreach $myStore in $wsStores.loadAllStores() }}
                    {{ if $myStore.clickAndCollect }}
                        <option value="{{= $myStore.id }}"{{ if $wsCheckout.selectedStoreId == $myStore.id }} selected{{ /if }}>
                            {{= $myStore.name }}
                        </option>
                    {{ /if }}
                {{ /foreach }}
            </select>
        </form>
        {{ if $myActionCheckoutStoreIdSelect.error }}
            {{ foreach $myError in $myActionCheckoutStoreIdSelect.errors }}
                {{ if $myError.code == "reservationFailed" }}
                    <div class="alert alert-danger">Item not available in store: {{= $myError.details.productId }}</div>
                {{ /if }}
            {{ /foreach }}
        {{ /if }}
    {{ /if }}
{{ /foreach }}

​Actions overview

​Actions

​CheckoutBillAddressSelect

​CheckoutShippingAddressSelect

​CheckoutSetDraftAddress

​CheckoutCommitDraftAddress

​CheckoutUseSameShippingAddress

​CheckoutUseDifferentShippingAddress

​CheckoutAccountTypeSelect

​CheckoutSetGuestEmail

​CheckoutShippingMethodUpdate

​CheckoutConfirm

​CheckoutSetFreeFields

​CheckoutSetCustomerData

​CheckoutPseudoCCSelect

​CheckoutNewsletterSubscribe

​CheckoutStoreIdSelect

​Further links

Actions overview

Actions

CheckoutBillAddressSelect

CheckoutShippingAddressSelect

CheckoutSetDraftAddress

CheckoutCommitDraftAddress

CheckoutUseSameShippingAddress

CheckoutUseDifferentShippingAddress

CheckoutAccountTypeSelect

CheckoutSetGuestEmail

CheckoutShippingMethodUpdate

CheckoutConfirm

CheckoutSetFreeFields

CheckoutSetCustomerData

CheckoutPseudoCCSelect

CheckoutNewsletterSubscribe

CheckoutStoreIdSelect

Further links