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 }}
Items can be moved from the basket to the wishlist through a text link to {{ item.remove_url }}&add_to_wishlist=1
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.
User files
Where a visitor uploads file(s) to a product when added to the basket, the user files are linked to the basket item through a session cookie. The association is therefore lost if the user quits the browser and the uploaded files will not be present on any order.
A variable basket.user_files_lost will return true if the platform detects that the association has been lost and can be used to show a warning to the visitor to re-add the products to their basket.