Checkout customization
The checkout page is the last step of the buying flow: the buyer fills in contact details and a shipping address, picks a delivery method, and pays. Checkout customization is how an app changes that page. Your app adds content of its own at the slots the platform reserves, reads and writes the data of that order, and hides the built-in modules it replaces — all without taking over the page. The extension that does this is a checkout extension.
Supported features
Checkout customization is made up of three parts:
- Extension points — the slots the platform reserves on the checkout page.
extend()renders your HTML at the extension point you name, so the extension point decides where on the page your content appears. - Hiding native modules —
deleteTargetinextension.jsonswitches off a built-in module by name, so your content replaces it instead of sitting beside it. CheckoutAPI— the global object the platform mounts onwindow.CheckoutAPIonce the page has loaded. You use it to read and write the data of that order. It is grouped into namespaces; the table below is the overview, and the full method signatures and types are in the reference.
| Namespace | What it covers | What you can do |
|---|---|---|
order | What the buyer picks on the way to placing an order, and the price refresh that follows every change. | Add or remove line items; store your own key-value fields on the order; change the delivery method and the shipping line; block submission or validate before it. |
store | The order data itself: the order, its prices, its business type, and the checkout layout. | Read the order and its totals; listen for every recalculation; tell which checkout layout is in use. |
summary | The order summary column: the line items, the price breakdown, and the shipping cost text. | Read the line items and the price breakdown; watch either one change; rewrite the list the summary renders. |
address | The shipping and billing forms, the schema they render from, and the addresses the buyer has saved. | Read and write either address; reorder, relabel, hide, or lock fields; add validation rules on top of the built-in ones; read the country list and the address templates. |
coupon | The savings a buyer can apply: coupons they hold, discount codes they type in, and gift cards. | Read what is currently applied; apply or remove a discount code or a gift card; rewrite how the code tags render. |
user | Who the buyer is and how to reach them. | Read the sign-in state and the account details; read the email and phone entered at checkout; read the marketing subscription. |
payment | The payment methods on offer. | Read the payment methods and the selected one; submit the payment; run a callback when a payment is attempted, fails, or completes. |
base | The plumbing of the checkout page: loading state, formatting, localized messages, and native module visibility. | Register your own translations and read them back in the buyer's language; format a price or a phone number; check whether a native module is on screen. |
utils | The checkout page's own dialog and drawer, plus three lodash functions passed straight through. | Open a modal dialog; open a drawer; use the lodash helpers the platform passes through. |
step | The steps of a checkout and the navigation between them. | Read the step the buyer is on; move to another step; read the step breadcrumb; send the buyer to another page of the store. |
config | Read-only store and page configuration: theme, market, feature flags, and which of the two pages is open. | Tell the checkout page from the thank-you page; read the theme, market, and store configuration; check whether the mobile layout is in use. |
exception | Business errors raised during checkout. | Check a response for an error code; read or clear the stored error; watch for submit failures. |
pickup | In-store pickup. | Read the pickup locations; read the one the buyer selected; read the pickup information form and its validation result. |
extension | Extensions themselves. | Read what is registered at an extension point; wait until extensions have finished loading; check which native modules are hidden; build the real name of a dynamic extension point. |
track | Analytics reporting. | Report an event of your own; report a checkout milestone; read the order payload used for reporting; attach extra fields to an event. |
utils.eventBus | An in-page event bus between extensions on the same checkout page. | Emit an event; listen for one, once or every time; stop listening. |
A method whose name starts with register is not a listener. It hands the checkout page a callback whose return value the platform consumes, so what you return becomes what the page renders or how it behaves. Return the wrong shape — undefined from a callback that must return a list, for instance — and the page reads a property off it and crashes to an error screen. The buyer cannot finish the order.
Only on* and add*Cb methods are safe in this respect: they receive a value, and the platform does not consume what they return. To watch something without changing it, use the on* method, never the register* one.
Reads carry no such risk. The get*, is*, and has* methods answer from data the page already holds, return synchronously, and send no request, so you can call them as often as you need to.
Examples
Both recipes below are built the same way. The first one walks through the shared skeleton step by step, then gives the call for each kind of change. Start there if this is your first checkout extension. The second is a complete feature built on top of it.
Jump straight to any recipe: