Create custom B2B checkout experiences

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

• Use the usePurchasingCompany hook to identify business customers.

• Use the useCheckoutSettings hook to identify draft order checkouts.

• Get familiar with using Company and CompanyLocation metafields.

• Deploy your extension code to Shopify.

• You've created a Partner account.

• You've created a new development store with the following:

  • Generated test data
  • Checkout and Customer Accounts Extensibility developer preview enabled

• You've created an app that uses Shopify CLI 3.0 or higher.

• You've requested access to protected customer data.

The sample code imports API hooks that provide b2b context to customize the checkout.

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 the following command 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 purchase.checkout.block.render target enables merchants to control where the extension is rendered in checkout. In the following example, the ORDER_SUMMARY4 placement is used so that the extension appears after the order summary:

Now that you've set up extension points, you can make metafields available by configuring shopify.extension.toml to access the customer, company, companyLocation metafields in the extension.

In the following example, the extension reads the merchant configured company metafield from appMetafields to determine whether the company has spent a certain amount of money (high_value).

You can use the usePurchasingCompany hook to identify whether a checkout is a B2B checkout. The usePurchasingCompany hook enables you to display tailored messages to B2B customers or hide information from D2C customers.

You can use the useCheckoutSettings hook to identify whether a checkout is a draft order checkout. Draft orders require merchant review, so you can inform the B2B buyers with a customized message about the type of checkout they're on.

When you're ready to release your changes to users, you can create and release an app version. An app version is a snapshot of your app configuration and all extensions.

You can have up to 50 checkout UI extensions in an app version.

1. Navigate to your app directory.

2. Run the following command.

   Optionally, you can provide a name or message for the version using the --version and --message flags.

Releasing an app version replaces the current active version that's served to stores that have your app installed. It might take several minutes for app users to be upgraded to the new version.

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 Shopify 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. The tunnel_url parameter allows your app to be accessed using a unique HTTPS URL.

   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 targets and their respective types.