Checkout UI extensions

Anchor to Getting startedGetting started

To get started customizing your store's checkout, scaffold an app extension using Shopify CLI.

Scaffolding the extension creates a file framework that includes your extension's TOML configuration file and a templated Checkout.jsx file where you add your extension's code.

Anchor to Building your extensionBuilding your extension

Checkout UI extensions are made up of three interconnected parts: targets that determine where your custom UI appears in the checkout interface, target APIs that provide access to checkout data and functionality, and web components that render UI elements like buttons and menus.

Anchor to Targets: Choose where your custom UI appearsTargets: Choose where your custom UI appears

Targets define where your custom UI appears within Shopify's checkout interface. There are three types of targets:

Anchor to Target APIs: Define what your extension doesTarget APIs: Define what your extension does

Target APIs provide access to data and functionality within the checkout flow. Use them to add custom logic to your extension.

When your extension runs, Shopify provides a shopify global object that you use to access data and features. Most target APIs are properties on this object. For example, shopify.buyerIdentity gives you information about the buyer who's interacting with the checkout, and shopify.cost provides the cost breakdown for the current checkout.

If your app uses ESLint, update your configuration to include the global shopify object to prevent linting errors.

Anchor to Web components: Design your interfaceWeb components: Design your interface

Web components are the UI building blocks that you use to display data and trigger API functions. These components are native UI elements that follow Shopify's design system and are built with remote-dom, Shopify's library for building cross-platform user interfaces.

The component library includes options like form inputs, buttons, overlays, and feedback indicators. You can use these components individually for simple displays, or combine them with layout primitives like stack, grid, and section to build more complex interfaces.

Anchor to Apply changes: Update the cart and checkoutApply changes: Update the cart and checkout

Some target APIs include methods that update the cart and checkout. For example:

• applyAttributeChange sets a cart attribute.
• applyMetafieldChange writes a cart metafield.

Each method returns a promise that resolves after Shopify applies the change and the corresponding API property updates with the new state.

Anchor to ConfigurationConfiguration

You define your extension's configuration in a shopify.extension.toml file. This file contains the extension's name, targeting definitions, API version, and other settings. We recommend that you always set the latest supported api_version in your configuration file.

When you scaffold your extension using Shopify CLI, a shopify.extension.toml file with a default configuration is created for you. As you build your extension, you define the targets you want to use and their corresponding code modules in this file.

Anchor to PropertiesProperties

Checkout UI extensions use the following configuration properties:

Anchor to Testing and deploymentTesting and deployment

Shopify CLI provides a set of tools to help you test and deploy your extension.

Anchor to Local testingLocal testing

To run your extension locally during development, start a dev server using Shopify CLI. The dev command creates a preview of your extension on your chosen dev store. If your extension is built on an app with a backend, then this command also serves your backend locally using a Cloudflare tunnel.

The dev server automatically reloads your extension when you make changes to your code, so you can test updates in real-time.

Anchor to DeploymentDeployment

When you're ready to go live, deploy your extension to production using Shopify CLI.

The Shopify CLI deploy command builds your extension bundle and uploads everything to Shopify. If your extension is built on an app with a backend, then you need to deploy your app to a hosting service first. Shopify hosts only your extension's code.

Anchor to VersioningVersioning

Polaris reference docs follow Shopify's API versioning policy. Each stable version is supported for a minimum of 12 months. Older versions continue to work, they just won't have dedicated docs on Shopify.dev. Shopify CLI already prevents deploys targeting API versions older than 12 months, so we recommend keeping your extensions on a supported version.

Anchor to Error handlingError handling

To handle errors in your extension, add an unhandledrejection listener for promise rejections or an error listener for other exceptions like Javascript runtime errors or failures to load a resource.

You can also use third party error-reporting libraries. However, these libraries might require extra configuration because UI extensions run inside of a Web Worker which doesn't have access to window or the DOM. You'll typically need to disable default integrations and manually attach error listeners to self.

The third-party tool example shown uses Sentry. To install and initialize this tool, follow their Browser JavaScript guide. We recommend disabling the default integrations to be sure the tool will run within a Web Worker. You'll need to add event listeners manually.