Theme App Extensions and Web Pixels

Script tags are being removed in two separate steps, one for each place they ran. The dates below come from the script tag deprecation pages and the developer changelog entry of 2026-08-24.

Two details of the schema are worth knowing. The ScriptTagDisplayScope enum has three values in the 2026-10 schema: ONLINE_STORE, and the deprecated ALL and ORDER_STATUS (the latter "unavailable as a mutation input"). And the scriptTagCreate mutation is still present in the schema and not marked deprecated there, so a document that creates a script tag still validates against the schema; it is the runtime that refuses it. The deprecation page also records that an earlier plan to show a warning banner to merchants who install an app that uses script tags was dropped, so nothing in the admin will tell the merchant that an app is about to stop working.

Source: Storefront script tags, Order status script tags and Script tags are deprecated and will stop running on March 1, 2027

The deprecation page gives a two-row rule that is easy to remember: a script that loads JavaScript on storefront pages becomes an app embed block, and a script that tracks analytics, conversions or customer behaviour becomes a web pixel. The longer comparison below adds the app block and the other surfaces.

A rule of thumb for the Pocket Coffee app: the roast date badge is an app block, because the merchant wants it next to the product price and the block must follow the product being displayed; the Coffee Club widget is an app embed block, because it floats over every page and has no place in the section layout; the add-to-cart reporting is a web pixel, because it only collects data.

The generated extension and a populated one look like this. The folder names are fixed; Shopify reads nothing else.

Source: Configure theme app extensions: file structure

The configuration file of a theme app extension is deliberately minimal, because the extension’s behaviour comes from the schemas of its blocks.

Source: Configure theme app extensions: configuration file

When the build ran offline, the CLI derived the handle pocket-coffee-storefront from the name and used it as the log prefix (the log line reads pocket-coffee-storefront | Running theme check on your Theme app extension...).

An app block shows inline content that the merchant can place. You create one by setting "target": "content" in the schema. The older value section still works and behaves identically, but new blocks should use content. By default a theme has no app blocks after an app is installed: the merchant adds them from the Apps section of the theme editor, either inside a section that accepts app blocks or as a wrapped block of its own at section level.

Use app blocks for apps whose content should follow dynamic sources (reviews and star ratings), for content that merchants may want to reposition, and for content that should span the full page width. They are the right choice for the Pocket Coffee roast date badge:

Source: Configure theme app extensions: app blocks for themes

The block does five things that are typical of app blocks. It reads the product through an autofill resource setting, so that on a product page it points at the product being shown without the merchant choosing it. It reads an app-owned metafield through the reserved prefix $app:roast (see App-owned data: metafields and metaobjects). It prints block.shopify_attributes so that the theme editor can select the block when it is clicked in the preview. It shows an explanatory placeholder only when request.design_mode is true, that is, inside the theme editor, so the merchant can see and position the block even before any product has a roast date. And it declares one stylesheet that Shopify loads once per page however many badges the page contains.

An app embed block holds code that has no UI slot of its own, or that floats or overlays the page: chat bubbles, product image badges, cookie banners, SEO meta tags, analytics and tracking snippets. Shopify renders it and injects it before the closing </head> or </body> tag, depending on the target:

App embed blocks are off after installation. A merchant activates them in the theme editor under Theme settings and then App embeds, and an app cannot activate them on the merchant’s behalf; what the app can do is send the merchant to the theme editor with the embed already switched on (see Deep links). They work in vintage themes and in Online Store 2.0 themes alike, because they do not depend on sections or JSON templates, which is why one embed can replace a script tag for every merchant without maintaining a second installation path. The price of that independence is scope: an app embed block can only see the Global Liquid scope of the page it is rendered on, so it cannot use autofill or read a section’s settings. An embed can also limit itself to chosen templates with enabled_on, which a script tag could never do; loading a script only on the pages that need it is one of the performance arguments for the migration.

The Coffee Club widget is the Pocket Coffee example. It replaces a script tag that used to inject a floating "free shipping above 40 EUR for club members" message on every page.

Source: Configure theme app extensions: app embed blocks

The markup is only a placeholder div that carries data attributes. The behaviour is in club-widget.js, which the schema loads, and the consent logic of that script is explained in Gating an app embed on consent. The data attributes use only objects that exist in the Global Liquid scope: request.locale, cart.currency and the block’s own settings. The same block could not read product on a product page unless the theme’s Global Liquid scope provides it there, and that is not guaranteed, which is the practical reason to prefer an app block whenever content must follow a resource.

A second embed uses the compliance_head target to set safe defaults before any other script runs:

Source: Configure theme app extensions: schema

The script that a block loads through the javascript attribute is added to the page head as <script async>, so its position relative to other scripts is not guaranteed; an inline script in a compliance_head block is the way to run something before them. If several blocks on the page reference the same JavaScript or stylesheet file, the file is included once.

The schema of an app block or app embed block resembles a theme section schema, with a few attributes of its own.

Source: Configure theme app extensions: schema

Three notes on the table. First, the documentation asks for schemas to avoid cluttering the theme editor: all app embed blocks of all apps live in one panel, so limit settings to visual ones. Second, app blocks have no presets; they appear in the picker because their target is content. Third, theme app extensions do not support comments or trailing commas in JSON, unlike theme files. A trailing comma in a schema is a parse error here.

autofill is a setting on resource settings (product, collection, article and similar) of app blocks. When the merchant adds the block to a section, Shopify fills the setting with a dynamic source: the parent section’s resource setting of the same type, or the template’s global resource. A featured product section has a product setting that selects the featured product, and an app block with an autofill product setting automatically uses it; on a product template it uses the product being displayed. That is why a reviews or ratings block never needs an extra step to find the product. The setting does not exist for app embed blocks, because they only have the Global Liquid scope.

App blocks and embeds are rendered in a restricted Liquid environment. The restrictions are not obvious from the theme side and cause most "it works in my theme but not in the extension" problems.

An extension often needs data that the app manages, such as the roast date. App-owned metafields and metaobjects use the reserved prefix $app, and the extension can reference them without hardcoding an app ID:

Source: Configure theme app extensions: reserved prefixes for metafields and metaobjects

Using the prefix means the same Liquid works in a development app and in the production app, which have different IDs. For the badge, the app creates the definition once and then sets a value per product. Both mutations were validated against the downloaded 2026-10 schema:

Source: metafieldDefinitionCreate and metafieldsSet

Metafield definitions and ownership rules are the subject of the page on metafields and metaobjects; whether a storefront can read the value (the access.storefront field above) is part of the definition. The Liquid reads the value the merchant-facing way, so the badge never needs an API call at render time.

Everything under assets/ is served from the Shopify CDN, so the extension never needs its own static hosting. The extension is validated when it is deployed; if it exceeds an enforced limit, validation fails and the extension does not update.

Source: Configure theme app extensions: file and content size limits

The block limit was 25 until 2026-02-03, when Shopify raised it to 30 app blocks per extension. Because app embed blocks can restrict themselves to the templates that need them, the documentation recommends that they load scripts only on specific pages, which keeps the performance cost of the app proportionate to its use; a script tag always loaded on every page.

The Pocket Coffee extension (three blocks, three assets, two locale files and a schema locale file) was assembled in a scratch app with a placeholder client ID of 32 zeros and example.invalid URLs, and built with the CLI. The command needs neither a login nor a store:

Source: shopify app build

The output (trimmed) shows that the build runs Theme Check on the extension and then bundles it:

Theme Check can also be run directly in the extension folder, which is what a CI job should do (the next section explains why). With the three blocks above it printed 6 files inspected with no offenses found.

The sequence that needs a store is the one in the official tutorial: shopify app dev starts a local development server with hot reloading and uploads a host theme to the development store (Shopify’s example theme Dawn unless you choose one with --theme <ID or name>), and the CLI output tells you to open the host theme in the theme editor, add your app block, save and open the printed preview URL. The preview is available only in Google Chrome, and the local server port can be set with --theme-app-extension-port. The tutorial lists Ruby and Bundler among the project dependencies. Test with both an app block and an app embed, and check the things the tutorial names: floating components do not cover page content, merchants can switch embeds on and off and edit their settings, and blocks can be added, removed and moved.

Releasing works like any other extension. shopify app deploy creates an app version (a snapshot of the app configuration and all extensions) and releases it, replacing the active version served to installed stores; it can take several minutes for stores to be upgraded. --no-release creates the version without releasing it, and --version and --message name it. The page on billing, App Store requirements and deployment covers CI for shopify app deploy.

Source: Build theme app extensions: deploy and release

Neither command was executed for this page; both need an authenticated CLI and an app registered in the Dev Dashboard.

Because blocks are inactive until a merchant acts, the app must lead the merchant to the right place and must know whether the merchant got there. Both are part of the migration from script tags: deleting the script tag before the replacement is active leaves a gap in which neither works.

Shopify’s UX guidance for theme app extensions is short, and following it is a condition for a good review.

Source: UX for theme app extensions

Once the pixel has been created for a shop, it is loaded on that shop’s online store. As a customer browses, they trigger customer events, which Shopify publishes to a data layer, or event bus. A pixel subscribes to the events it cares about, transforms the payloads into the format of its endpoint, and sends them. The surfaces are not limited to the storefront: since 2025-07-21 web pixels also load automatically on customer account pages and on the Order status page, where the page_viewed event and the Advanced DOM API are supported and custom events can be published from a UI extension. Shops must use a custom domain for customer accounts (for example accounts.your-store.com) for the customer account pages to log events.

Source: About web pixels and Web Pixels API

Shopify says it strongly recommends that developers build apps and encourage merchants to install them instead of creating custom pixels, for greater integration. A custom pixel in the lax sandbox cannot reach the top frame, so some properties return different values: for example window.href returns the sandbox URL rather than the top frame’s URL. The rest of this section is about app pixels. The existence and signatures of the four server pixel mutations were confirmed in the downloaded 2026-10 schema; their behaviour was not exercised.

A web pixel extension is generated with the CLI template web_pixel and offers JavaScript and TypeScript flavours:

Source: Build web pixels: create a web pixel extension

The command needs a login and was not run. The template it copies is public: a shopify.extension.toml, a package.json that depends on @shopify/web-pixels-extension (the template pins ^2.10.0; npm resolved 2.18.0 on 2026-10-27) and src/index.js that registers a callback and subscribes to page_viewed. The Pocket Coffee extension keeps that shape:

Source: Build web pixels: define your web pixel settings

To run a pixel without consent (strictly necessary), set analytics, marketing and preferences to false. Whether a pixel is genuinely essential is a legal question for the merchant, not a configuration choice.

App pixels run in a strict sandbox: a web worker. It offers many of the globals of a browser worker, but only the following are guaranteed:

Other globals may be set to undefined or removed at any time, so a pixel must not rely on them. There is no document or window: anything that scrapes the DOM or writes to it is impossible, which is the point. The sandbox replaces the useful parts of those APIs with explicit, asynchronous ones:

Source: About web pixels: sandbox environments, browser and init

The callback passed to register receives one object, the Standard API, which can be destructured. Its properties for app pixels are:

Source: Standard API

Every event delivered to a pixel has the same envelope: id (event id), name, type (standard, custom, dom or advanced-dom), seq (sequence number), timestamp (ISO 8601), clientId (Shopify’s client-side id of the visitor), context (the browser snapshot) and data (the payload, specific to the event). The standard events are these:

Source: Standard Events

Besides standard events, the DOM Events API provides a subset of interaction events (clicked, form_submitted, input_blurred, input_changed, input_focused) across storefront, checkout and thank you pages (not on customer account pages or the Order status page), and an Advanced DOM Events API exists for finer interaction tracking.

The pixel reports two events to the app’s own collector: every add-to-cart, and the completed purchase. The endpoint is a setting, so each shop can point to a different collector, and the Spanish and English storefronts are told apart by the /en path prefix.

Source: analytics and product_added_to_cart

The tutorial’s own sample sends a variable called payload that it never defines; the version above builds the payload from the event. The collector at https://collector.example.test/events is a reserved test domain, so no request would ever leave a developer’s machine with this example; the endpoint must also answer CORS preflight requests, because the sandbox is a worker.

To check the logic without a store, the bundle produced by shopify app build was executed in a Node vm context with a fake shopify.extend, a fake analytics.subscribe that records the callbacks, and a fake fetch. The harness registers the pixel, then fires one add-to-cart for two 250 g Ethiopia bags (SKU PC-ETH-WHL-250), one add-to-cart with cartLine set to null, and one purchase of a 1 kg Colombia filter bag plus the starter kit. It printed:

Source: Web Pixels API

The null cart line produced no request, as intended. The harness does not reproduce the real sandbox: it proves that the logic reads the documented event fields correctly, not that Shopify delivers those events or that the endpoint accepts them.

Deploying the extension does not start the pixel. The app also needs two access scopes, write_pixels (to write the pixel’s merchant settings) and read_customer_events (to get access to customer events), and it must create a web pixel record on every shop where it is installed. In shopify.app.toml:

Source: Build web pixels: update your app access scopes

When shopify app dev connects the extension to a development store, the app’s name appears under Settings then Customer events in the App pixels list with the status Disconnected. Creating the record flips it to Connected. The mutation validates the settings against the definition in shopify.extension.toml; if they do not match, it fails.

Source: webPixelCreate, webPixelUpdate and webPixelDelete

All four documents validated against the 2026-10 schema. The input type WebPixelInput has a single field, settings (JSON), so the variables for the Pocket Coffee shop are:

Source: Build web pixels: activate a web pixel extension

Note that settings is a JSON value that carries an encoded JSON string, as in the official tutorial. A deliberately wrong document, with a field runtimeContext on WebPixelInput and a misspelt settngs on WebPixel, was rejected by validation (Field "runtimeContext" is not defined by type "WebPixelInput" and Did you mean "settings"?). The userErrors of the pixel mutations use code values from the ErrorsWebPixelUserErrorCode enum:

A reasonable pattern is to query webPixel first and call webPixelUpdate when a record exists and webPixelCreate otherwise, and to run the same step from the app’s installation hook and from the "Enable tracking" button in the app.

Since 2025-12-10 Shopify enforces its protected customer data policy for all web pixel extensions on every surface (storefront, checkout and customer accounts). Personally identifiable fields (name, email, phone and address) are present in the payload only if the app has been approved for the corresponding protected scope; otherwise the field is null and the structure of the event does not change. The scopes are read_customer_name, read_customer_email, read_customer_phone, read_customer_address and read_customer_personal_data. Custom pixels are out of scope of this change. For the Pocket Coffee pixel, which sends SKUs, quantities and amounts, no PII is read, so no approval is needed; an app that forwards checkout.email must handle null without breaking its pipeline, and should request only the scopes it uses.

Source: Protected customer data scopes required for web pixel PII access starting on December 10th

With a development store the loop is the one in the tutorial: run shopify app dev, create the web pixel record, open the store, open the browser’s developer tools and read the console, where the tutorial logs the accountID setting. Use the store’s Customer events page to confirm the status of the pixel. Remove console.log calls before release, because Shopify asks that production pixels do not log. Without a store, keep the logic of the pixel in plain functions and test them as the harness above does; the bundle is a plain script, so a fake shopify.extend is enough to drive it.

Shopify distinguishes four processing purposes:

Source: Customer Privacy API: call the API

Whether a purpose is allowed for a given visitor combines three things: the merchant’s current privacy settings (is consent required in this region?), the visitor’s location, and what the visitor has consented to. For regions that are configured to require consent, non-essential purposes are not allowed until the visitor consents. For other regions the default is to allow everything. The merchant configures regions and the cookie banner in the admin’s privacy settings; data sale opt-out regions, usually US states, are configured separately, and in them the Global Privacy Control signal is honoured automatically and sets sale_of_data to false.

For app pixels consent is enforced for you. The pixel declares its purposes in [customer_privacy], and Shopify’s pixel manager loads the pixel only if the visitor’s permission covers all the purposes the pixel declares as required. The behaviour at the callback level depends on the region:

A pixel cannot call the Customer Privacy API itself. If it needs to adapt to consent changes (for example to include the consent state in payloads), it reads init.customerPrivacy for the state at page load and subscribes to customerPrivacy.subscribe('visitorConsentCollected', ...) for later changes. The event payload carries the four flags analyticsProcessingAllowed, marketingAllowed, preferencesProcessingAllowed and saleOfDataAllowed.

Source: Pixel Privacy: Customer Privacy API

Custom pixels have the same API through api.customerPrivacy and init.customerPrivacy, and set their privacy requirements in the pixel’s settings in the admin instead of a toml file. The visitorConsentCollected event of the pixel sandbox and the document event of the storefront share a name but not an identical payload: the storefront documentation shows analyticsAllowed and preferencesAllowed in the detail, while the pixel API shows the ...ProcessingAllowed names. Read the exact keys from the documentation of the surface you are on, and log one event in a development store before relying on a key.

Theme app extension code that reads or changes consent loads the API first. The feature name and version are exact:

Source: Customer Privacy API: loading the API

After the callback runs without an error, the API is on window.Shopify.customerPrivacy. The methods are:

Source: Customer Privacy API

The document event visitorConsentCollected is published when consent changes, with the new state in event.detail; updates are published only when consent changes, not when the listener is added. An app that renders its own banner calls setTrackingConsent with the visitor’s choice:

Source: Customer Privacy API: collect and register consent

Four rules apply. Never read or modify Shopify cookies directly; the API is the only supported interface, and cookie names and formats change. Shopify stopped setting the _tracking_consent, _landing_page and _orig_referrer cookies on storefronts on 2025-09-15; the replacement for _tracking_consent is this API, and for the other two the browser’s window.location.href and document.referrer, or the Web Pixels API, or the customerJourneySummary of an order. Record a data sale opt-out only through a flow the visitor starts (a link or preference page), because the flag is true to allow and false to block and must not be applied on page load. And when the Shopify cookie banner is enabled it shows in the configured regions and passes consent to the API automatically; if the merchant uses an app for the banner, ask that app’s developer where the banner is rendered. The cookie banner has a small runtime API of its own: privacyBanner.showPreferences() opens the preferences modal.

Source: _tracking_consent, _landing_page, _orig_referrer cookies will no longer be set

An app embed that loads for everyone must itself decide what it may do before consent. The Coffee Club widget does the following, and club-widget.js is the file the schema loads:

Source: Customer Privacy API: use an event listener

The script follows the documented pattern: load the feature, test the purpose with the ...Allowed method that combines merchant settings, location and consent, subscribe to visitorConsentCollected for a later decision, and do nothing that needs consent until it is true. The merchant chooses the required purpose in the block settings; none is for a widget that is strictly necessary, and the default is analytics. The started flag matters: without it the script would render again and publish the custom event again every time a consent event arrived, including in the none mode.

The script was executed in a Node vm context with a stubbed window.Shopify (a loadFeatures that calls back at once, a customerPrivacy whose analyticsProcessingAllowed is switched by the test, an analytics.publish that records its calls) and a stubbed document. It printed:

Source: Customer Privacy API

The widget stays hidden while analytics are not allowed and appears once consent arrives; in none mode it appears at once and publishes once. This is a logic test with stubs: it does not exercise Shopify’s real banner, region detection or the real Shopify global. If the widget is shown to every visitor regardless of consent, as many sites do for strictly necessary messages, the none setting makes that explicit and visible to the merchant.

Three further pieces complete the picture.

Source: dataSaleOptOut