Post-purchase extensions API reference

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 shopify.extension.toml in the root folder. This file is used for setting up dependencies that your extension needs to run.

For more information about the configuration file, refer to Post-purchase extensions configuration.

The configuration file alone won't 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 app 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.

The following example shows a config query string that's appended to the checkout URL:

The following example includes the URL-encoded version:

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. Your app shouldn't 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. 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.

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.