Skip to main content

Display custom data at checkout

Checkout UI extensions can read and display custom data that's stored in metafields. For example, in this guide you'll learn how to read watering instructions for plants and display that data next to the plant in the order summary at checkout. Learn from an end-to-end example here, and you can use what you've learned to display other types of metafield data at other checkout UI extension targets.

Follow along with this tutorial to build a sample app, or clone the completed sample app.

Shopify Plus

Checkout UI extensions are available only to Shopify Plus merchants.

Products in the order summary displaying their watering instructions

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

  • Add custom data to products using a metafield
  • Generate a checkout UI extension that appears in the checkout flow using Shopify CLI
  • Set up configurations for your checkout UI extension in the extension TOML file
  • Render metadata next to products at checkout
  • Deploy your extension code to Shopify

Requirements

Project

Anchor to Create a metafield for a productCreate a metafield for a product

In the Shopify admin, define a metafield and add data to it.

Anchor to Add a metafield definitionAdd a metafield definition

Add a metafield for the product. For this tutorial, set the Name and the Namespace and key with the following values:

  • Name: Watering instructions

  • Namespace and key: The namespace is instructions and the key is watering, entered as instructions.watering.

Set the Type as Single line text.

  1. Select a product.

  2. Under Product metafields, in the text field for the metafield definition that you added, enter the data that you want to display in the checkout UI extension. For example, "Average water needed".

  3. Click Save.

  4. Repeat these steps for another product, and add different data. For example, "Very little water needed".

Anchor to Create a checkout UI extensionCreate a checkout UI extension

To create a checkout UI extension, you'll use Shopify CLI, which generates starter code for building your extension.

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:

    Terminal

    cd <directory>
  2. Run the following command to create a new checkout UI extension:

    Terminal

    shopify app generate extension --template checkout_ui --name my-checkout-ui-extension
  3. Select a language for your extension. You can choose from TypeScript, JavaScript, TypeScript React, or JavaScript React.

    Tip

    TypeScript or JavaScript is suitable for smaller projects that require a more straightforward API. TypeScript React or JavaScript React is suitable when you want an easy model for mapping state updates to UI updates. With JavaScript or TypeScript, you need to map state updates yourself. This process is similar to writing an application targeting the DOM, versus using react-dom.

    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:

    Checkout UI extension file structure

    └── my-app
    └── extensions
    └── my-checkout-ui-extension
    ├── src
    │ └── Checkout.jsx OR Checkout.js // The index page of the checkout UI extension
    ├── locales
    │ ├── en.default.json // The default locale for the checkout UI extension
    │ └── fr.json // The locale file for non-regional French translations
    ├── shopify.extension.toml // The config file for the checkout UI extension
    └── package.json
  1. Start your development server to build and preview your app:

    Terminal

    shopify app dev

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

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

Anchor to Set up an extension targetSet up an extension target

Set up a target for your checkout UI extension. Targets control where your extension renders in the checkout flow.

Anchor to Export the target from your script fileExport the target from your script file

In your Checkout.jsx file, set the entrypoint for the checkout extension, and then export it so that it can be referenced in your configuration.

Create a reactExtension function that references your target, and export it using the default export.


This extension uses the purchase.checkout.cart-line-item.render-after target, to display the custom data after the product.

Anchor to Reference the extension targets in your configuration fileReference the extension targets in your configuration file

You can define more than one target so that app users can add the extension to multiple locations in the checkout.

In your checkout UI extension's configuration file, for each of your targets, create an [[extensions.targeting]] section with the following information:

  • module: The path to the file that contains the extension code.

  • target: An identifier that specifies where you're injecting code into Shopify. This needs to match the target that you exported from your file/s.


shopify.extension.toml is the configuration file for your extension. It contains basic information and settings.

Note

Whenever you edit your extension configuration file, you need to restart your server for the changes to take effect.

Terminal

shopify app dev

Anchor to Reference the metafield in the configuration fileReference the metafield in the configuration file

In your checkout UI extension's configuration file, reference the metafield definition so that the extension code in your Checkout.jsx file can read it.

Anchor to Add the metafield definition to the extension TOMLAdd the metafield definition to the extension TOML

Create an [[extensions.metafields]] section with the metafield namespace and key. This needs to match the metafield definition that you created in the Shopify admin.

Anchor to Render the extensionRender the extension

Import checkout UI extension resources to render the extension and the metadata in the checkout UI.

Anchor to Import the following checkout UI extension resources to render the extension:Import the following checkout UI extension resources to render the extension:

  • useCartLines: Return the current line item for the checkout.
  • Text: Provide semantic value to the text that you're rendering.
  • useAppMetafields: Return the metafield data for the product.

Anchor to Preview the extensionPreview the extension

Preview your extension to make sure that it works as expected.

Run the Shopify CLI dev command to build your app and preview it on your development store.

Make sure that you select a development store that has enabled the developer preview for Checkout and Customer Accounts Extensibility.

  1. In a terminal, navigate to your app directory.

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

    Terminal

    shopify app dev
  3. Press p to open the developer console.

  4. In the developer console page, click on the preview link for the custom field extension.

    The checkout opens.


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

Anchor to Property token errorProperty token error

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.

Terminal

shopify app dev --checkout-cart-url cart/{product_variant_id}:{quantity}

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:

    Terminal

    shopify app info

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:

    Terminal

    shopify app dev
  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.

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.

  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.

    Terminal

    shopify app deploy

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.

Tip

If you want to create a version, but avoid releasing it to users, then run the deploy command with a --no-release flag. You can release the unreleased app version using Shopify CLI's release command, or through the Partner Dashboard.

Was this page helpful?