Getting started with custom banners

In this tutorial, you'll learn how to do the following tasks:

• Create a checkout UI extension that renders some text in the checkout flow.

• Run the extension locally and test it on a development store.

• Set up a banner to display to customers.

• Configure settings that enable merchants to control the banner content.

• Support multiple extension points that enable merchants to choose where to render the banner.

• Deploy your extension code to Shopify.

• You've created a Partner account.

• You've created a new development store, where you've enabled the checkout extensibility developer preview.

• You've populated your store with test products.

• You've created an app that uses Shopify CLI 3.0 or higher, or you've migrated your existing app so that it's compatible with Shopify CLI 3.0 or higher.

• You're familiar with how custom banners work.

The sample code imports the Banner component to build the UI. The code uses settings to provide the content that's rendered in the Banner component. The code supports multiple extension points, including Checkout::Dynamic::Render and Checkout::DeliveryAddress::RenderBefore.

You can copy and paste the following code into your index file and add a few example values to get the extension to render in the browser. The rest of the tutorial walks through this sample code step-by-step.

To create a checkout UI extension, you can use Shopify CLI, which generates starter code for building your extension and automates common development tasks.

1. Navigate to your app directory:

2. Run one of the following commands to create a new checkout UI extension:

3. Select a language for your extension. You can choose from TypeScript, JavaScript, TypeScript React, or JavaScript React.

   You should now have a new extension directory in your app's directory. The extension directory includes the extension script at src/index.{file-extension}. The following is an example directory structure:

4. Start your development server to build and preview your app:

   To learn about the processes that are executed when you run dev, refer to the Shopify CLI command reference.

5. Press p to open the developer console. In the developer console page, click on the preview link for your extension.

Setting up the extension points enables merchants to select which extension point they want to use and where it renders in checkout. You can place dynamic and static extension points in any location that's supported for the extension point type.

1. Set up the following extension points:

   • Checkout::Dynamic::Render: A dynamic extension point that merchants can place in any supported location.
   • Checkout::DeliveryAddress::RenderBefore: A static extension point that, in this example, renders above the shipping address form.

2. Set the extension points in shopify.ui.extension.toml.

Now that you've set up extension points, you can make settings available through the shopify.ui.extension.toml so that merchants can configure the banner. Settings display in the checkout editor.

The following example shows a settings configuration that defines the settings title, description, status and collapsible within the checkout editor:

For this example, the merchant configures the banner's title and description fields using the checkout editor with the following values:

• title = "All items final sale"
• description = "They're not eligible for returns, refunds, or exchanges."
• status = "warning"
• collapsible = true

In this example, you'll set the following fields using the useSettings() hook:

• title: The title of the banner.

• description: The text in the body of the banner.

• status: The status of the banner, which sets the banner's color and icon. You can set status to one of info, success, warning, or critical.

• collapsible: Whether the banner should display controls to expand or collapse the description. You can set collapsible to one of true, or false.

In this step, you'll use the Banner component to render the banner with the content from the settings that you configured.

When you're ready, you can deploy your extension code to Shopify.

1. Navigate to your app directory.

2. Run one of the following commands:

   
   

   To learn about the processes that are executed when you run deploy, refer to the Shopify CLI command reference.

This section describes how to solve some potential errors when you run dev for an app that contains a checkout UI extension.

If you receive the error ShopifyCLI:AdminAPI requires the property token to be set, then you'll need to use the --checkout-cart-url flag to direct the CLI to open a checkout session for you.

If you don't receive the test checkout URL when you run dev, then verify the following:

• You have a development store populated with products.

• You're logged in to the correct Partners organization and development store. To verify, check your app info using the following command:

Otherwise, you can manually create a checkout with the following steps:

1. From your development store's storefront, add some products to your cart.

2. From the cart, click Checkout.

3. From directory of the app that contains your extension, run dev to preview your app:

4. On the checkout page for your store, change the URL by appending the ?dev=https://{tunnel_url}/extensions query string and reload the page.

   You should now see a rendered order note that corresponds to the code in your project template.

• Learn about the components that are available in checkout UI extensions.

• Consult the API reference for checkout UI extension points and their respective types.

• Learn how to release and publish a version of your checkout UI extension.