Getting started with custom banners

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

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

• You've created a Partner account.

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

• You've populated your store with test products.

• You've created an ngrok account and auth token. The ngrok token is used when previewing your app with Shopify CLI. To learn more about creating an auth token, refer to ngrok’s documentation.

• 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'll use Shopify CLI to generate a new extension.

1. Navigate to the directory of the app that you want to add your extension to.

2. Run the following command to start creating the checkout extension:

3. Select Checkout UI as the type of extension.

4. Provide a name for your extension using either dash case or snake case.

5. Select a template for your extension. You can choose from JavaScript, TypeScript, React, or React TypeScript.

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:

After your extension is created, you can work with it by building the app and starting a local development server.

Shopify CLI uses ngrok to create a tunnel that allows your app and extension to be accessed using a unique HTTPS URL.

1. Navigate to your app directory.

2. Either start or restart your server to build and preview your app:

   
   When you run the dev command, the CLI builds and serves your app. It also walks you through multiple configuration steps. If you've already run dev for this app, then some of these steps are skipped. In some cases, you might be required to manually kill an ngrok tunnel that's already running.

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

3. Click the URL that's printed at the bottom of the CLI output to view your extension.

After your extension is created, you can deploy your extension code to Shopify.

1. Navigate to your app directory.

2. Run one of the following commands:

   
   

   When you run the deploy command, the CLI deploys the extensions to Shopify as a draft. It also walks you through multiple configuration steps. If you've already run dev or deploy for this app, then some of these steps are skipped.

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

3. After you deploy the extension to Shopify, navigate to your app in the Partner Dashboard.

This section describes how to solve some potential errors when you run dev for an app that contains a checkout 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 how to add custom banners to checkout.