Build a date picker for a specific shipping rate

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

• 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.
• Query the Storefront API from the extension code to get shipping rate data.
• Use the checkout UI component library to add new user interface to the checkout.
• Use the checkout UI extension API to read and write order information.
• Save the date to a metafield and display the value in the Shopify admin.

• 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 reviewed the UX guidelines for customizing delivery methods.

If you want to quickly get started, then you can copy and paste the following sample code into your src/Checkout.jsx and shopify.extension.toml files. This tutorial describes the sample code step by step.

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

1. Navigate to your app directory.

2. Run the following command to create a new extension:

3. Select checkout UI as the extension type, and then provide a name for your extension.

4. Select a language for your extension. The example code in this tutorial uses JavaScript React.

   You now have a new directory for your app under <app-name> > extensions. The extension directory includes the extension script at src > Checkout.jsx.

In src/Checkout.jsx, import the components from the checkout UI extensions API that you need to build the extension:

Targets control where your extension renders in the checkout flow. The purchase.checkout.shipping-option-list.render-after extension target renders the extension after the shipping methods section on the shipping step of the checkout.

When you generate an app extension, a TOML configuration file named shopify.extension.toml is automatically generated in your app's extension directory. The TOML file is located in the extensions/ directory of your app project. It contains basic information and settings.

For information about the properties that you can configure in the TOML file, refer to Configuring app extensions.

In src/Checkout.jsx, add a reactExtension() function to render your extension using the purchase.checkout.shipping-option-list.render-after extension target.

In your checkout UI extension configuration file, create an [[extensions.targeting]] section with the following information:

• target - An identifier that specifies where you're injecting code into Shopify. This needs to match the target that you exported from your Checkout.jsx file.
• module - The path to the file that contains the extension code.
• export - The name of the exported function that contains the extension code.

Now that you've set up the extension target, you'll save custom field values in a metafield. Regular metafields are available to any app or extension.

In this step, you'll set a namespace and key for the metafield where you want to store the custom field value. Later, you'll expose values stored in this metafield to merchants in the Shopify admin.

A metafield is a custom field that you can use to store additional information about a Shopify resource. You can use metafields to store information specific to your app without setting up your own storage.

You can use the useApplyMetafieldsChange hook to store the value that the customer enters in the metafields property of the checkout. This metafield value is later associated with the order.

useApplyMetafieldsChange is a React hook that lets you write metafield values. To learn more about the hooks available for checkout UI extensions, refer to the checkout UI extension reference.

In this step, you'll render a calendar where customers can select a delivery date, which is then saved to a metafield. The DatePicker component will display the available dates.

If there are only certain dates that delivery can happen, then you can customize how the DatePicker component can be used by buyers by passing through disabled dates in the disabled property.

After you've saved the date picker metafield to the order, display it on the order details page in the Shopify admin so that merchants can view it.

In the Shopify admin, add a metafield definition for orders. Use the same namespace and key as defined in your /src/Checkout.jsx file.

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

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

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

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 date picker should render in the Shipping step of the checkout when Express Shipping is selected.

Test your extension to make sure that it works as expected by placing an order with delivery instructions in checkout.

1. With your server running, open the storefront of your development store.

2. Add a product to the cart and then check out.

3. Fill out the contact and shipping address information, and then move to the Shipping step of the checkout.

4. Select Express Shipping. A date picker appears.

5. Select a date and then complete the checkout.

6. In the Shopify admin for the development store, open the order details page for the order that you just placed.

The delivery date that you entered is displayed in the Metafields section, with the delivery date field that you created.

To release your changes to users, 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.

Shopify CLI builds your app, bundles your app components, and deploys to Shopify. To learn more about the processes that are executed when you run deploy, refer to the Shopify CLI command reference.

An app version created using Shopify CLI contains the following:

• The app configuration from the local configuration file. If the include_config_on_deploy flag is omitted or false, the configuration from the active app version will be used instead.
• The local version of the app's CLI-managed extensions. If you have an extension in your deployed app, but the extension code doesn't exist locally, then the extension isn't included in your app version.
• The latest drafts of dashboard-managed extensions.

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

• Learn about the components that are available in checkout UI extensions.
• Consult the API reference for checkout UI targets and their respective types.