checkout_basket

The checkout_basket.twig view hosts the shopping basket page of your website.

On the shopping basket page, the customer views the contents of their shopping basket, enters any voucher code they have, redeems any discounts, selects a delivery rate and proceeds through to checkout.


Requirements

Unless selecting a delivery rate is not required for the basket (or disabled on the account) the user must select a delivery rate before the basket form is submitted. Not selecting a delivery rate on form submission will return a platform error.

The checkout_basket view must include the basket form.


Items in the basket

The items in the shopping basket can be returned using the basket items object.

If you want to allow users to update the quantity of an item in the basket then surround the basket in a form, i.e.

<form action="{{ global.current_url }}" method="post">

Include a quantity field for each item in the basket when the name of the field is quantity[X] where X is the unique platform ID for the item.

This can be outputted using a standard HTML macro, i.e.

{{ html.input('quantity[' ~ item.id ~ ']', item.quantity) }}

{{ item.quantity }} is the variable to display the current number of items in the basket.

Include a <button> tag for the user to click to select to update the item's quantity, i.e.

<button>update</button>

Each item in the basket can be removed by displaying a removal URL outputted with {{ item.remove_url }}


Empty basket

When designing the page, consideration should be given to the display of the page if there are no items in the shopping basket. This can be detected if the basket.items array returns false, e.g.

{% for item in basket.items %}
    ...
{% else %}
    Your shopping basket is empty
{% endfor %}

Errors

Including the code {{ theme.errors(errors) }} will output any errors that the platform responds with when any of the basket forms are submitted.


Voucher code entry

Include a voucher code form on the page to allow the visitor to enter any voucher/discount codes that they have.

<form action="{{ global.current_url }}" method="post">
    <input type="text" name="voucher_code">
    <button>Apply</button>
</form>

Reward points

If the reward points APP is enabled on the account several features can be included on the shopping basket view to display information about reward points.

1. Information about how many reward points the customer currently has in their account, e.g.

{% if basket.reward_points > 0 %}
    You have {{ basket.reward_points }} reward points.
{% endif %}

2. If the customer is eligible to redeem their reward points (because the level of points they have is greater than any minimum that can be redeemed), e.g.

{% if basket.can_redeem_points %}
    <a href="/checkout/basket/convert-reward-points" class="button">Redeem Your Points</a>
{% endif %}

3. If the customer has redeemed their points, what the currency discount obtained was, e.g.

{% if basket.has_redeemed_points %}
    Your points have been redeemed for a discount of {{ currency_value(basket.reward_points_discount) }}
{% endif %}

The logic used should not show any of these 3 messages at the same time.

Reward points can be deconverted by visiting the URL /checkout/basket/unconvert-reward-points


Delivery rates

Unless the basket does not require a delivery zone and rate to be selected, the customer should be able to choose a delivery rate at checkout.

Firstly, the customer will need to select a delivery zone. The delivery zone will usually be selected with a <select> list.

<select name="countryId">
    <option value="">Please select...</option>
        {% if basket.shipping_countries|first is iterable %}
            {% for name, states in basket.shipping_countries %}
                <optgroup label="{{ name|default('Other Countries') }}">
                    {% for state in states %}
                        <option value="{{ state.id }}"{% if state.current %} selected="selected"{% endif %}>
                            {{ state.name }}
                        </option>
                    {% endfor %}
                </optgroup>
            {% endfor %}
        {% else %}
        {% for country in basket.shipping_countries %}
            <option value="{{ country.id }}"{% if country.current %} selected="selected"{% endif %}>
                {{ country.name }}
            </option>
        {% endfor %}
    {% endif %}
</select>

Another select list should allow the customer to select their delivery rate, according to the delivery zone selected.

<select name="rateId">
    {% for rate in basket.shipping_rates %}
        <option value="{{ rate.id }}" {{ rate.id == global.basket.shipping_rate_id ? 'selected="selected"' : '' }}>
            {{ rate.name }} {{ currency_value(rate.price) }}
        </option>
    {% endfor %}
</select>

The delivery zone will display any country with a state selection as an <optgroup> with an individual state being able to be selected from the <select> list, as shown in the example below.


Checkout totals

The basket object can be used to return the totals (e.g. delivery cost, grand total).


PayPal Express

If PayPal Express is enabled then the PayPal Express checkout button should be displayed on the checkout page.

{% if basket.paypal_express_enabled %}
    <button name="paypal_express" value="1">
        ...
    </button>
{% endif %}


How you heard about us question

If you are using the customer sources APP you can include a 'tell us how you heard about us' question in the form.

<select name="customer_source">
    {% for source in basket.customer_sources %}
        <option value="{{ source }}">{{ source }}</option>
    {% endfor %}
</select>

The variable basket.customer_source will return a customer's existing selection for this (for customer's logged into an account).


Endpoints

Two endpoints exist for voucher codes and gift vouchers to be applied to a basket (through AJAX) and for any voucher code or gift voucher already applied to be removed.

The paths are

/checkout/basket/set-voucher
/checkout/basket/clear-vouchers

The set-voucher endpoint accepts a code POST parameter (either a gift voucher or a voucher code).

The clear-vouchers endpoint will clear all vouchers (both gift vouchers and voucher codes).

Both endpoints accept an ajax POST parameter, which enables AJAX mode (the response will contain two properties: success and error).

If AJAX mode is not enabled two more POST parameters are available: redirect_path which can be used to redirect the user to a new URL and redirect_message which will keep the user on the current URL with a platform success message.

A third endpoint exists to clear the contents of the basket. The path is

/checkout/basket/clear

An AJAX, redirect_path and redirect_message parameters are also available.