Getting started with custom fields

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.

• Render an optional input field for customers to add a note.

• Save the note to a metafield.

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

• You're familiar with how custom fields work.

The sample code imports several checkout components, including BlockStack, Checkbox, and TextField to compose the user interface that renders at the Checkout::ShippingMethods::RenderAfter extension point. The code uses the applyMetafieldChange extension point API to update a metafield with a customer value.

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. You'll also need to update your extension's configuration file with the information in the code 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::ShippingMethods::RenderAfter extension point renders the extension after the shipping methods section on the shipping step of the checkout.

Now that you've set up the extension point, you'll save custom fields using public metafields. Public metafields are available to any app or extension.

1. Access the metafield and set that as your initial value, and use applyMetafieldsChange() to update and persist that value.

In this step, you'll render a checkbox that toggles an input where customers can add a note, which is then saved to a metafield. The Checkbox and TextField components display the offer to the customer.

To set the note value, you'll make a request to the applyMetafieldChange extension point API with the key and namespace values for the metafield.

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

Add a metafield definition for Orders. Use the same namespace and key as defined in the extension config file.

Your extension in the Shopify admin should now look similar to the following image:

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 custom fields 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.