Post-purchase extensions API reference
About Post Purchase UI ExtensionsAnchor link to section titled "About Post Purchase UI Extensions"
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.
Extension pointsAnchor link to section titled "Extension points"
An App Bridge Checkout extension will register for one or more extension points using
The current extension points are available for post-purchase:
Checkout::PostPurchase::Render, used to build post-purchase interstitials for cross sell applications.
Configuration fileAnchor link to section titled "Configuration file"
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.
DevelopmentAnchor link to section titled "Development"
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.
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,
The following example includes the URL-encoded version:
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.
Shopify-specific globalsAnchor link to section titled "Shopify-specific globals"
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
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.
Web platform globalsAnchor link to section titled "Web platform globals"
self, a reference back to the global object.
console, which is the same
consoleavailable 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)
clearInterval, which behave the same as they do outside a web worker
fetchand related globals (
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-runto 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-runis 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
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
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.