Skip to content

Basket and Checkout Pages

The basket is a single card of lines beside a sticky order summary. It is built to be read in one pass: what you are buying, what it costs, and one obvious next step.

What the shopper sees

Part Behaviour
Heading The page title, the item count (3 items, counting units, not lines; a donation amount counts as one) and a Continue shopping link. Every theme's basket heading, mini basket and header badge read the same count, DOrder.itemCount, so a £25 donation is one item everywhere, not 25.
Line Picture, name (links back to the product), chosen options, the line total at the top right, then the quantity stepper with Remove item and Save for later (when enabled) on one row. When the quantity is more than one, the unit price shows beneath the name.
Clear basket A quiet Clear basket link under the lines. Opening it asks "Remove everything from your basket?" in place (a <details>, no script), with Yes, clear basket to confirm and Keep my items to back out; it posts to POST /basket/clear (BasketController, through OrderService.clearLineItems). Not offered on a table's tab (any line fired to a table, canClearBasket false), while a payment is in progress, or on an empty basket. Brock's mini basket drawer has the same toggle.
Stock Silent when everything is available. A line shows Out of stock (with a Remove button) only when there is a problem. The + button stops at the stock level.
Stock notices Adding or raising a line past the stock adds as many as there are and leaves a one-off message on that line (you asked for 10 but only 8 are available…). Returning to an old basket whose stock has dropped cuts the line back to what is available, with a message saying so. A typed quantity above the product's (or the shop's) maximum, or below its minimum, is set to that limit with a message too. Messages live on the line item (StockNotice), are shown once, and are cleared by the next basket change.
Typing a quantity The number between the stepper's − and + can be typed into, here and in the mini basket. It looks like the plain number until hovered or tapped (a number pad comes up on phones), and saves on Enter or when you move on. A number past what the product, the shop or the stock allows is set to the nearest allowed, with a note on the line. See Basket quantity field.
Quantity types Selectable products get the stepper, fixed-quantity products show Qty 1 (adding one again makes a second line rather than raising the first, so each donation keeps its own donor, message and Gift Aid declaration), and price-as-quantity products (donation or gift card amounts) get an amount field with an Update button.
Collect or deliver With collect some, deliver the rest on (Enterprise), each item that would be sent has a Delivery / Collect · Free choice against the shopper's store, a store bar (Collect from Leeds · Change) and a store chooser above the items, and a summary of what goes which way. A choice updates the items and the order summary without a page load (see Changes without a page load). Otherwise the basket is unchanged.
Order summary Subtotal, service fee and delivery where they apply, then the total. Until a delivery method is chosen it says Calculated at checkout (on the checkout, Choose a delivery option), so the total never looks final when it is not; a chosen method shows its price, or Free! when it costs nothing, never both. A method dropped because the address changed goes back to the unchosen state. Sticky beside the lines from 900px.
Checkout One primary button, a Secure checkout line and a quiet Continue shopping link.
Phones Below 900px the summary sits under the lines, so a bar pinned to the bottom of the screen carries the total and Checkout until the summary's own button comes into view. The bar's total follows the summary while prices reprice.
Empty A short message and a Continue shopping button, at full width.

Prices are repriced asynchronously by basket-v2.js; the hooks it writes to (.lineItemPrice, .lineItemNet, .orderPrice and friends, and link#order-data) are unchanged, and the pinned bar deliberately does not carry .orderPrice because the script only updates the first one on the page.

Changes without a page load

The lines card (#basket-items-card) and the order summary card (#basket-summary-card in Nova, the .brock-summary section in Brock) are also the basket-items-card and basket-summary-card fragments. A collect-or-deliver choice posts to the page as it does without JavaScript, and the page answers the script with those two cards instead of the redirect, so after the swap they show the basket as the reloaded page would: the lines and their stock notices, the collect-or-deliver choices and store bar with the notice of what changed, the totals (collection, delivery, fees, promotions and tax), the promotion code box and the checkout button. Each card is drawn from its own extension's model (the full basket's and the basket actions'), without rendering the rest of the page. When the change redirects back to the basket, only those two extensions run for the cards, unless another block on the page has to run too.

After a swap, basket-v2.js sets up the new lines' quantity steppers and, when the card's data-order-repricing says prices are still being worked out, polls for them. The phone checkout bar watches the new summary's total and button, and the service fee's explanation and the promotion code box keep working, as their listeners sit on the page rather than on the cards. Quantity, remove, save-for-later and clear still load the page.

Theming

Nova's basket (templates/nova/extensions/fullBasket/) is styled entirely from --nb-* tokens, so a theme re-skins it by setting tokens on :root in its own stylesheet. It does not need to out-specify the template's inline CSS. Every token falls back to a Nova token (--color-primary, --font-family-display, --radius-lg ...), so a theme that only re-points Nova's palette, fonts and radii already gets a basket in its own voice. The full list is in fragment/commerceTokens.html.

Token group Controls
--nb-card-bg, --nb-card-border, --nb-card-radius, --nb-card-shadow The lines card and the summary panel
--nb-summary-bg, --nb-summary-border The summary panel on its own (defaults to the card)
--nb-rule, --nb-control-border, --nb-control-radius Row dividers, stepper and amount field
--nb-title-*, --nb-item-title-*, --nb-total-* Page title, line titles and the order total (font, size, weight, letter-spacing, case)
--nb-label-case, --nb-label-ls, --nb-label-size Small labels: Remove item, the count, summary rows
--nb-num-font Prices and totals (Depot and Spec use their monospace face)
--nb-cta-* The checkout button: background, text, hover, border, radius, shadow, case, weight
--nb-sticky-top, --nb-bar-bg Where the summary sticks (to clear a sticky header) and the phone bar's background

Atelier, Pop, Depot, Spec and Diorama each set a block of these at the end of their own stylesheet. Brock has its own basket templates (templates/brock/extensions/fullBasket/) and styles them with its --b-* tokens; it has the same sticky summary and phone checkout bar. The collect-or-deliver choice (fullBasket/handover.html) is shared by Nova's and Brock's baskets and uses only these tokens (the store bar takes --nb-head-bg).

Checkout

The checkout steps use the same tokens, so the basket and checkout read as one flow in every theme. Each step (details, address, delivery, payment, and the order confirmation and order placed pages) renders through templates/nova/fragment/checkoutStyles.html, which gives it the same card and header band, headings, field labels and errors, delivery options and alerts, and makes its main button the same button as the basket's Checkout (--nb-cta-*). The checkout sidebar uses the basket's totals block.

Inputs and buttons are not styled by the checkout: they are .nova-input and .nova-btn, which every theme already restyles. Stripe's card field takes the input's look, and the unified checkout's Payment Element is given the theme's input colours (or its own panel colours, where a theme sets one, as Spec does) because Stripe draws into an iframe that cannot see the page's CSS.

Extra tokens for the checkout steps: --nb-head-bg (the header band), --nb-input-bg, --nb-card-title-size and --nb-legend-size. Brock's unified checkout has its own rules in brock.css; its other steps use the Nova templates through the token block at the end of its checkout rules.

Your details: the title field

The details step (the checkout-personalDetails extension) does not ask for a title (Mr, Ms, Dr…) unless the shop turns on its Show title setting. It used to ask every time, with no empty option, so the first title in the list ended up on almost every order: browser autofill fills the name, email and phone but not the title. When the field is shown it starts on Select, offers Mr, Mrs, Miss, Ms, Mx and Dr, and saves no title if none is picked. Adding title to the extension's Mandatory Fields shows it whatever the setting says. The title goes on to the order, the customer's saved details and Gift Aid declarations, all of which treat it as optional.

Messages

The page uses the basket.* Site Text keys (for example basket.yourBasket, basket.orderSummary, basket.itemCount, basket.deliveryLater, basket.secureCheckout) and, for the buttons, the existing button.removeItem, button.saveForLater, button.checkout and button.continueShopping. Brock uses the brock.basket.* keys.

While a payment is in progress

Once the shopper pays at checkout, the basket is locked (CheckoutPaymentLock) until the order is placed or the payment is refused or abandoned: from the moment they press Pay on the single-page checkout (or give a card in the Apple Pay or Google Pay sheet), while the card is being asked for (3D Secure, an off-site payment method), while checkout takes the stock and places an order whose card is held, and whenever a session finds the card held or charged. A locked basket is paid for exactly as it is, so nothing anywhere changes it:

Where What the shopper gets
Basket page The basket read-only: no quantity steppers, amounts, remove or save-for-later buttons, collect-or-deliver controls or promo box. A Payment in progress notice (basket.paymentInProgress.title, basket.msg.paymentInProgress) links to checkout (basket.paymentInProgress.checkout), where they finish or cancel the payment. Showing it saves nothing: no stock cut-back, no collect-or-deliver tidy, no repricing.
Add to basket, quantity, remove (/basket, /basket/update, /basket/remove, /basket/clear, the mini basket, bundles, saved items) Back to the basket page, which says why (from the mini basket, a 204 sending the script there; see Storefront Fragments).
Promo codes PAYMENT_IN_PROGRESS in the promo box: codes can't change right now.
Delivery (/rest/delivery/set), the step-checkout's delivery, address and personal details steps Refused (409, or the step shown unchanged).
Apple Pay / Google Pay quick pay Refused with paymentInProgress; the button sends them to the basket page.
REST basket API 409 with a BasketLockedError (PAYMENT_IN_PROGRESS) on add, line update or removal and personal details, as PATCH /v1/basket/{id}/handover already did.
Signing in When the account's basket is locked, what they had added as a guest becomes a fresh basket of their own and the locked one is left as it was (with nothing added as a guest, they carry on with the locked one).

Every change goes through CheckoutPaymentLock.requireUnlocked in the services (OrderService's line and delivery changes, HandoverService), which throws a BasketLockedException (a ShopperMessageException, key basket.msg.paymentInProgress). As a last check, confirm refuses a payment whose amount or currency no longer matches the basket (see Order lifecycle).

Not done yet

  • Free-delivery progress. The delivery threshold is not exposed to the basket model, so there is no You're £x away from free delivery meter.

Promo codes

When the shop has a promotion that needs a code (or the order already carries one), the basket sidebar and the checkout summary show Add a promo code: a native <details> link that opens a field and an Apply button. Applied codes appear as removable chips (the code, what it takes off, an x to remove it), the totals gain a Discount line, and a refused code shows its reason under the field (not recognised, expired, not active yet, conditions not met, too many attempts). On a shop with reCAPTCHA, too many attempts runs an invisible reCAPTCHA instead and tries the code again once it's passed (see marketing tools). A shop with no code promotions sees nothing.

Where How
Basket page, step-checkout sidebar The box is fragment/promoCode (one file in Nova's templates that every theme falls back to) with a look per theme family (fragment/promoCodeStyles: Nova's --nbc-* tokens, Brock's --b-*). It is included by the fullBasket extension's basketActions and basketSummary templates of Nova and Brock. The extension puts a PromoCodeView on the model as promo.
Basket without JavaScript The forms post to POST /basket/promo and /basket/promo/remove (PromoCodeController) and redirect back, with a refused code's status in ?promo=.
Basket with JavaScript The same endpoints answer JSON; on success the page reloads, as it does for quantity changes. A refusal shows inline with no reload.
Single-page checkout The box asks the page (a bdgr:promo event) and the checkout script (nova/js/modules/checkout/summary.js) sends it as {promoCode} / {removePromoCode} in the checkout session patch, so the totals, Pay button and Stripe amount follow. The session's promo carries the codes and the outcome.

The box is accessible: the field has a label, the message is a polite live region, and nothing depends on Bootstrap's JavaScript. The totals blocks of both templates always render the discount row (hidden when there is none) so checkout can reveal it as the order reprices. Text is in the basket.promo.* Site Text keys.

Single-page checkout

Sites use the step-by-step checkout page (checkout) unless Use single-page checkout (unified-checkout-enabled, Settings › Checkout and payments › Checkout) is on. Then every checkout renders the shared checkout-unified page instead: contact, address, delivery and payment on one page with Apple Pay and Google Pay at the top. It needs Stripe connected; without it the step-by-step page stays. Direct checkout links always use it (see Direct Checkout Links).

Both checkout pages open with the sign-in prompt (authenticationExtension, compact mode). A shopper the site recognises but who isn't signed in sees "Welcome back" with Sign in and Not you?. A guest sees a one-line "Returning customer? Sign in" that opens in place, or a button to Badger Auth on sites with central auth. Signed-in shoppers have their details filled in from their account (name, email, phone, title), or from their last order when the account lacks a name or email, and their addresses from their address book or last order. The system update 2026-10-23-add-checkout-sign-in-prompt adds the prompt to existing checkout-unified pages.

The shopper pays the total the page shows

The single-page checkout never charges a total the shopper wasn't shown. Until they pay, the basket follows the catalogue: each load of the page prices it afresh, and a change on the page (address, delivery option, promo code) can reprice it, with the page showing the new total. From Pay, nothing reprices it.

When What happens
Pay now, or a card from the Apple Pay / Google Pay sheet Before Stripe asks the card, the page sends the total it showed (or the sheet showed) to POST /api/checkout/session/start-payment. If the basket's total is different (it was priced again in another tab, say), Pay is refused: the page reloads the session and says Some prices in your basket have changed. Please check your order total before you pay. (checkout.msg.pricesChanged). If it matches, the PaymentIntent is brought to it (without repricing) and the basket is locked (CheckoutPaymentLock, status starting), so nothing reprices it (see While a payment is in progress).
The card is declined or the sheet closed POST /api/checkout/session/payment-not-taken unlocks the basket once Stripe shows nothing was taken. A page that went away mid-payment is caught by the next session load: a starting lock over a minute old with nothing taken is unlocked.

The step-by-step checkout and quick pay keep the same rule in their own way. Their PaymentIntent is created by the server when the shopper pays, so repricing can't move an amount already asked for:

Where What happens
Step-by-step checkout, each page load CheckoutController prices the basket and waits for it, so a reload shows today's prices.
Step-by-step checkout, Pay (card, gift card, test payment) payment.js sends the total the page shows (shown_total, from data-amount-to-pay) with the first /rest/extensions/v1/payment/confirm-payment. A different order total, or none, is refused before any payment (PaymentResponse.pricesChanged) and the page reloads with ?pricesChanged=1, showing the new total and checkout.paymentDetails.error.PRICES_CHANGED.
Step-by-step checkout, placing the order Refused with PRICES_CHANGED when the authorised amount isn't the order's total (the basket changed in another tab after the card was authorised). Paying again drops the old authorisation.
Quick pay (Apple Pay / Google Pay on the basket) quickPay.js sends the total the sheet last showed (shownTotal) to /checkout/quickPay/submit. A different order total, or none, is refused (pricesChanged): the shopper is told and the page reloads.

The single-page checkout can show the shop's terms of sale and a box for marketing email, and records what the shopper agreed to when the order is placed. How the records are kept, unsubscribing and the site upgrade are in Customer Messaging and Consent.

Terms of sale. When Terms of sale page (terms-of-sale-page, the page's seoName) names a page that exists, checkout links to it. How customers accept the terms (terms-acceptance-mode) chooses how:

Mode What the shopper sees
statement (default) By placing this order you agree to our terms of sale. under the Pay button and under the Apple Pay / Google Pay button.
checkbox I agree to the terms of sale, a box above both buttons (ticking one ticks the other). Until it is ticked the Pay button names what's missing and the wallet button is dimmed and won't open.

Each order records an acceptance of the version in Terms of sale version (terms-of-sale-version, any label such as 3 or 2026-10-23), with the order, the words shown and the shopper's language. The first acceptance of a version keeps a copy of the page's text. Change the version label whenever the terms change. With no page set, checkout shows and records nothing about terms.

Marketing email. Marketing opt-in at checkout (checkout-marketing-opt-in) adds a box under the email field:

Setting The box
off None.
opt-in Email me news and offers from {shop}, unticked. Ticking it subscribes the shopper to news and offers.
soft-opt-in (default) Don't email me news and offers from {shop}, unticked. The shopper is subscribed unless they tick it. This is the UK "soft opt-in" for existing customers: switch to opt-in or off if it doesn't apply to your shop. Someone who unsubscribed before gets the plain unticked Email me box instead.

The privacy notice is linked under the box: the Privacy notice page when one is set, else the Privacy notice URL. With a page set, the order also notes which version of the notice the shopper was shown and a fingerprint of its text, recorded once per customer per distinct text (see Legal documents and the privacy notice). A signed-in customer who already gets news and offers doesn't see the box. A checkout opt-in is not sent a confirmation email: the shopper has just ordered with that address. Not ticking an opt-in box records nothing.

The wording is Site Text (consent.marketing.checkout, consent.marketing.checkout.softOptOut, consent.marketing.privacy, consent.terms.statement, consent.terms.checkbox, consent.terms.linkText, checkout.msg.termsRequired), so it can be changed or translated; the words actually shown are what gets recorded.

How it is recorded. The shopper's choices are kept on the basket as they make them, with a note of what the page showed. When the order is placed, the recordCheckoutConsent step of the order pipeline records them against the shopper's contact, whether the shopper came back from paying or the order was placed later by Stripe's payment notification (an off-site payment the shopper never returned from). It never stops an order: if recording fails, the order goes through and the failure is logged with the order's reference. In checkbox mode, a payment that reaches checkout without the box ticked (an old page left open) is refused and the card hold released, as for other refused payments.