Post-purchase extensions API reference

This API reference describes the technical details of how to build your Post Purchase UI Extensions. It covers the available extension points, including their input and output types and their structure.

For more information, refer to the post-purchase extension overview and Building a post-purchase checkout extension.

An App Bridge Checkout extension will register for one or more extension points using shopify.extend(). An extension point in an App Bridge Checkout extension is a plain JavaScript function. This function receives some API for interacting with the application, and is expected to return a value in a specific shape. The input arguments and the output type are different for each extension point.

The current extension points are available for post-purchase:

• Checkout::PostPurchase::ShouldRender and Checkout::PostPurchase::Render, used to build post-purchase interstitials for cross sell applications.

Post-purchase extensions have a configuration file named extension.config.yml in their root folder. This file is used for setting up dependencies that your extension needs to run.

When an extension is published to Shopify, the contents of this file are pushed alongside it. Currently, the configuration file only supports specifying the metafields that your extension needs to read. If your app needs to read metafields for various resources (Shop, Product, and ProductVariant), then you can specify these metafields using key value pairs in the config file. Any public metafield can be read. You can specify up to five key/namespace pairs in the config file. While executing the extensions, Shopify looks for the metafields in each resource and returns their contents.

Example:

The configuration file alone will not work in development as Shopify needs to know the file's contents before running the extension. In development, you must pass the configuration as the config query parameter.

The command shopify serve outputs the complete string that you must add to a checkout URL, including the contents of the config file. If you use the browser extension, then it automatically appends the config query string to the checkout URL. For example, https://your-test-store.myshopify.com/46071709864/checkouts/a7706e44c6c6b99b9899e1a87d5ec07b/post_purchase?script_url=http://localhost:39351/assets/extension.js&config={"metafields":[{"namespace":"my-namespace","key":"my-key"},{"namespace":"my-namespace","key":"my-key-2"}]}&api_key=myapikey.

The following example includes the URL-encoded version: https://your-test-store.myshopify.com/46071709864/checkouts/a7706e44c6c6b99b9899e1a87d5ec07b/post_purchase?script_url=http%3A%2F%2Flocalhost%3A39351%2Fassets%2Fextension.js&config=%7B%22metafields%22%3A%5B%7B%22namespace%22%3A%22my-namespace%22%2C%22key%22%3A%22my-key%22%7D%2C%7B%22namespace%22%3A%22my-namespace%22%2C%22key%22%3A%22my-key-2%22%7D%5D%7D&api_key=myapikey

When updating the configuration file, it's important to note that you need to restart your local server for the changes to take effect. Similarly, the browser extension might take up to 60 seconds before appending the updated values. If you don't want to wait, then disabling and then re-enabling the extension forces a refresh.

The most important API to an App Bridge Checkout extension is shopify, an object that is globally available. This object has a single method, extend that takes two arguments. One is the name of an available extension point, and the other is a function to call when Shopify is ready to run the extension point. The function you pass is called with at least one input argument, depending on the extension point. Refer to the documentation for the extension point you are targeting to see what you have access to.

This library provides an alias for shopify.extend in the form of the extend() export. This function is also strongly-typed. If you’re working in an editor that supports TypeScript’s language server (we recommend VSCode), then you get feedback about the input arguments to that extension point.

For extensions that render UI, like Checkout::PostPurchase::ShouldRender, the first argument is always a @remote-ui RemoteRoot object that allows you to render UI components into your extension point in checkout. You do not need to explicitly call mount() on this object; once the callback you registered for this extension point ends (or, if it returns a Promise, once that promise resolves), your initial UI will be rendered.

That’s really all the global API you need to know to start writing a UI extension. You’ll find the documentation for additional APIs that are provided when an extension point is run in the extension points documentation.

UI Extensions in Checkout post-purchase always run in a web worker. This environment has access to many of the same globals as you’d get with JavaScript running in a browser. However, we only guarantee the presence of the following globals:

• self, a reference back to the global object.
• console, which is the same console available in the browser and can be used for printing to the browser’s console (Note: your app should not log any content when running in production)
• setTimeout, clearTimeout, setInterval, and clearInterval, which behave the same as they do outside a web worker
• fetch and related globals (Headers, Request, and Response), which can be used to make HTTP requests to arbitrary endpoints (Note: any requests you make must explicitly support cross-origin resource sharing (CORS), just as they would if the request were coming from fetch() outside of a web worker)

You must not rely on any other globals being available. Many will be explicitly overwritten to be undefined in the sandbox, and non-language globals that aren’t hidden and aren’t in the list above may also be overwritten at any time.

Note: if you are using @shopify/checkout-ui-extensions-run to build and develop your script, all of the build configuration discussed in this section is handled for you — just try to be mindful if you are relying on very new language features that will require additional polyfills. @shopify/checkout-ui-extensions-run is the default build and dev tool you get when generating your extension with the Shopify App CLI, so if you’re not sure if you’re using it, you probably are.

The sandbox that loads your extension guarantees all of the globals available in ECMAScript 2015 (ES2015). This includes Set, Map, Promise, Symbol, and more. You should rely on these globals directly when you need them, and you should not use your own polyfill for any of these features. If you use globals added after ES2015, or new static methods on globals added after ES2015 (like Object.entries), you must polyfill your usage of these features.

Your UI extension should not ship any ES2015 (or newer) syntax, like class, const/let, or for..of loops. This syntax is not understood by some of the browsers that checkout supports. If you use these features in your source code, make sure they are compiled to ES5 syntax in your final JavaScript file.

The UI sandbox makes a regeneratorRuntime instance available globally. This object is provided by regenerator-runtime, and is used by many compilers to provide an ES5-compatible compilation target for generator functions and async/ await. If you use generators or async/ await, make sure you compile it down to code that uses regenerator-runtime, and make sure you do not import your own version of that polyfill.