Getting started with pre-purchase product offers

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.

• Show an initial loading state for the products to be offered.

• Fetch cart lines for the product offers from the Storefront API, to display to customers.

• Filter the cart lines to determine which to display for the product offer.

• Add a cart line to an order.

• Show an error banner if there's a problem adding a cart line to an order.

• 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.

The sample code imports some checkout components to build the UI. The code fetches products for the offer using query. The applyCartLinesChange API adds a cart line to the order when a customer clicks the button to add the product.

You can copy and paste the following code into your index file. You'll also need to update your extension's configuration file following the extension.config.toml example.

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.

In the index file, import the components from the Checkout UI extensions API that you need to build the extension:

The Checkout::Dynamic::Render extension point enables merchants to control what placement the extension is rendered in checkout. In this example, you'll use the ORDER_SUMMARY4 placement so that the extension appears after the order summary.

Now that you've set up the extension point, you'll fetch products so that you can display them to customers for the product offer.

1. Set up a function that handles retrieving your products. You'll query the Storefront API products resource. Shopify also provides a Storefront API Learning Kit that offers some useful examples for using the Storefront API.

   If you need to use fetch instead of query, then you can use the following examples. For more details on when to use fetch instead of query, refer to the checkout UI extension configuration documentation.

2. Show a loading state UI while fetching the products using the SkeletonText and SkeletonImage components.

In this step, you'll pick a product to offer, while making sure you aren’t offering a product that’s already in the cart.

If there is an error adding a product on offer, you'll want to update the UI to inform the user. To do this, you'll use the Banner component.

In this step, you'll render your product on offer and use the onPress property to apply the cart lines change if customers click on the product offer and handle any errors.

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.

• Get familiar with the UX guidelines for adding pre-purchase product offers to checkout.
• 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.