Getting started with order status page extensions

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

• Create a checkout UI extension that renders a post-checkout survey on the order status page.
• Run the extension locally and test it on a development store.
• Display different versions of the post-checkout survey depending on the order state.
• Set up the UI components for the post-checkout survey.
• Deploy your extension code to Shopify.

• You're familiar with order status page extensions.

• 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 following sample code creates a post-order checkout survey and displays it on the order status page. When the customer first completes the checkout, the survey asks the customer how they heard about the store. After the order has been submitted, the survey content changes to ask the customer if they are enjoying their purchase.

You can copy and paste the following code into your index file and add 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 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:

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 is a dynamic extension point that renders at a supported location set by the merchant. This is where the post-checkout survey will appear.

In your project, navigate to the src/index.tsx file, and set up the following extension point:

The following code sample returns a different version of the post-checkout survey depending on whether the customer has completed a checkout and an order has been submitted.

The customer needs to complete a checkout for the survey to appear:

• If the order has been submitted, then the survey asks the customer to review the product (the "Product review" survey).
• If no order exists, then the customer is viewing the order status page for the first time after the checkout is complete, and the survey asks customer how they heard about the store (the "Attribution" survey).

The following code sample sets up the other state of the post-checkout survey. This state appears on the order status page after the customer completes checkout. The survey asks the customer where they heard about the store.

The following code sample sets up one state of the post-checkout survey. This state appears on the order status page after the order has been submitted. The survey asks the customer if they like the product that they received.

The following code sample sets up the UI components that both states of the survey share, including the button to submit feedback and the message that appears after the feedback has been submitted:

You can preview your post-checkout survey to test it.

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

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

   The order status page is displayed after the payment step and any post-purchase extension. Refresh the page to see the order status page as it appears when a customer revisits it after checkout. If you want to revisit the page as it first appears during the checkout process, then add the param ?prevent_order_redirect=true to the URL.

   To preview the dynamic extension in a different supported location, add the param ?placement-reference=ORDER_SUMMARY1 to the URL.

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 order status page extensions.
• 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.