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.
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
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.
DevelopmentAnchor link to section titled "Development"
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.
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:
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. Your app shouldn't 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. 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
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.