--- title: Analytics API description: >- Publish custom events to registered web pixels, or submit visitor contact details directly to the shop backend. api_version: 2026-07-rc source_url: html: >- https://shopify.dev/docs/api/checkout-ui-extensions/2026-07-rc/target-apis/platform-apis/analytics-api md: >- https://shopify.dev/docs/api/checkout-ui-extensions/2026-07-rc/target-apis/platform-apis/analytics-api.md api_name: checkout-ui-extensions --- # Analytics API The Analytics API provides methods to interact with Shopify's analytics framework. Use this API to publish custom events that are forwarded to all registered [web pixels](https://shopify.dev/docs/apps/marketing), or to submit visitor contact details directly to the shop backend. Events published with `publish()` are forwarded only to web pixels. They aren't sent to the shop backend. Visitor data submitted with `visitor()` goes only to the shop backend. It isn't propagated to web pixels on the page. ### Use cases * **Publish custom analytics events**: Emit events from your extension that web pixels on the page can react to. * **Submit visitor information**: Send buyer contact details to the shop backend for attribution and analytics purposes. * **Track extension-specific interactions**: Publish events when buyers interact with your extension's UI to measure engagement. ### Support Targets (33) ### Supported targets * [purchase.​address-autocomplete.​format-suggestion](https://shopify.dev/docs/api/checkout-ui-extensions/2026-07-rc/targets/checkout/address#format-a-selected-suggestion-) * [purchase.​address-autocomplete.​suggest](https://shopify.dev/docs/api/checkout-ui-extensions/2026-07-rc/targets/checkout/address#suggest-address-completions-) * [purchase.​checkout.​actions.​render-before](https://shopify.dev/docs/api/checkout-ui-extensions/2026-07-rc/targets/checkout/navigation#navigation-target) * [purchase.​checkout.​block.​render](https://shopify.dev/docs/api/checkout-ui-extensions/2026-07-rc/targets/checkout/block#block-target) * [purchase.​checkout.​cart-line-item.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-07-rc/targets/checkout/order-summary#line-item-targets) * [purchase.​checkout.​cart-line-list.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-07-rc/targets/checkout/order-summary#checkout-cart-line-list-) * purchase.​checkout.​chat.​render * [purchase.​checkout.​contact.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-07-rc/targets/checkout/information#information-target) * [purchase.​checkout.​delivery-address.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-07-rc/targets/checkout/shipping#render-after-delivery-address-) * [purchase.​checkout.​delivery-address.​render-before](https://shopify.dev/docs/api/checkout-ui-extensions/2026-07-rc/targets/checkout/shipping#delivery-address-targets) * [purchase.​checkout.​footer.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-07-rc/targets/checkout/footer#footer-target) * [purchase.​checkout.​header.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-07-rc/targets/checkout/header#header-target) * [purchase.​checkout.​payment-method-list.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-07-rc/targets/checkout/payment#render-after-payment-methods-) * [purchase.​checkout.​payment-method-list.​render-before](https://shopify.dev/docs/api/checkout-ui-extensions/2026-07-rc/targets/checkout/payment#payment-targets) * [purchase.​checkout.​pickup-location-list.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-07-rc/targets/checkout/local-pickup#render-after-pickup-locations-) * [purchase.​checkout.​pickup-location-list.​render-before](https://shopify.dev/docs/api/checkout-ui-extensions/2026-07-rc/targets/checkout/local-pickup#location-list-targets) * [purchase.​checkout.​pickup-location-option-item.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-07-rc/targets/checkout/local-pickup#location-option-item-target) * [purchase.​checkout.​pickup-point-list.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-07-rc/targets/checkout/pickup-points#render-after-pickup-points-) * [purchase.​checkout.​pickup-point-list.​render-before](https://shopify.dev/docs/api/checkout-ui-extensions/2026-07-rc/targets/checkout/pickup-points#pickup-points-targets) * [purchase.​checkout.​reductions.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-07-rc/targets/checkout/order-summary#checkout-reductions-after-) * [purchase.​checkout.​reductions.​render-before](https://shopify.dev/docs/api/checkout-ui-extensions/2026-07-rc/targets/checkout/order-summary#reductions-targets) * [purchase.​checkout.​shipping-option-item.​details.​render](https://shopify.dev/docs/api/checkout-ui-extensions/2026-07-rc/targets/checkout/shipping#shipping-option-item-targets) * [purchase.​checkout.​shipping-option-item.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-07-rc/targets/checkout/shipping#render-after-shipping-option-) * [purchase.​checkout.​shipping-option-list.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-07-rc/targets/checkout/shipping#render-after-shipping-options-) * [purchase.​checkout.​shipping-option-list.​render-before](https://shopify.dev/docs/api/checkout-ui-extensions/2026-07-rc/targets/checkout/shipping#shipping-option-list-targets) * [purchase.​thank-you.​announcement.​render](https://shopify.dev/docs/api/checkout-ui-extensions/2026-07-rc/targets/thank-you/announcement#thank-you-announcement-) * [purchase.​thank-you.​block.​render](https://shopify.dev/docs/api/checkout-ui-extensions/2026-07-rc/targets/thank-you/block#block-target) * [purchase.​thank-you.​cart-line-item.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-07-rc/targets/thank-you/order-summary#line-item-targets) * [purchase.​thank-you.​cart-line-list.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-07-rc/targets/thank-you/order-summary#thank-you-cart-line-list-) * purchase.​thank-you.​chat.​render * [purchase.​thank-you.​customer-information.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-07-rc/targets/thank-you/information#information-target) * [purchase.​thank-you.​footer.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-07-rc/targets/thank-you/footer#footer-target) * [purchase.​thank-you.​header.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-07-rc/targets/thank-you/header#header-target) ### Properties and methods The [`shopify` global object](https://shopify.dev/docs/api/checkout-ui-extensions/2026-07-rc#target-apis-define-what-your-extension-does) provides analytics capabilities for the current checkout. Access the following properties and methods on `shopify` to publish custom events and submit visitor data. Available to `purchase` extension targets. * **analytics** **Analytics** **required** Tracks custom events and sends visitor information to [Web Pixels](https://shopify.dev/docs/apps/marketing). Use `publish()` to emit events and `visitor()` to submit buyer contact details. ### Analytics Tracks custom events and sends visitor information to \[Web Pixels]\(/docs/apps/marketing). Use \`publish()\` to emit events and \`visitor()\` to submit buyer contact details. * publish Publishes a custom event to \[Web Pixels]\(/docs/apps/marketing). Returns \`true\` when the event is successfully dispatched. The Promise resolves to \`true\` when the event was dispatched. The boolean indicates dispatch confirmation only. It doesn't indicate whether any specific web pixel processed the event. ```ts (name: string, data: Record) => Promise ``` * visitor Submits buyer contact details for attribution and analytics purposes. ```ts (data: { email?: string; phone?: string; }) => Promise ``` ### VisitorResult Represents a visitor result. ```ts VisitorSuccess | VisitorError ``` ### VisitorSuccess Represents a successful visitor result. * type Indicates that the visitor information was validated and submitted. ```ts 'success' ``` ### VisitorError Represents an unsuccessful visitor result. * message A message that explains the error. This message is useful for debugging. It isn't localized and shouldn't be displayed to the buyer. ```ts string ``` * type Indicates that the visitor information is invalid and wasn't submitted. Common causes include using the wrong data type or omitting a required property. ```ts 'error' ``` Examples ### Examples * #### ##### Description Send custom events to all web pixels registered on the page. This example calls \`shopify.analytics.publish()\` with an event name and payload that web pixels can react to. ##### jsx ```jsx import '@shopify/ui-extensions/preact'; import {render} from 'preact'; export default function extension() { render(, document.body); } function Extension() { shopify.analytics .publish('checkout-extension-loaded', { extensionName: 'My Extension', }) .then((result) => { if (result) { console.log( 'Successfully published event', ); } else { console.log('Failed to publish event'); } }) .catch((error) => { console.error('Publish error', error); }); return ( See console for result ); } ``` * #### ##### Description Submit buyer contact details to the shop backend. This example sends visitor data through \`shopify.analytics.visitor()\`. Unlike when using \`shopify.analytics.publish()\`, data isn't forwarded to web pixels on the page. ##### jsx ```jsx import '@shopify/ui-extensions/preact'; import {render} from 'preact'; export default function extension() { render(, document.body); } function Extension() { shopify.analytics .visitor({ email: 'someEmail@example.com', phone: '+1 555 555 5555', }) .then((result) => { if (result.type === 'success') { console.log('Success', result); } else { console.error('Error', result); } }); return ( See console for result ); } ``` *** ## Best practices * **Respect buyer privacy consent**: Before publishing analytics events, check whether analytics processing is allowed using the [Customer Privacy API](https://shopify.dev/docs/api/checkout-ui-extensions/2026-07-rc/target-apis/checkout-apis/customer-privacy-api). Read `shopify.customerPrivacy.value.allowedProcessing.analytics` and only publish events when it's `true`. * **Use descriptive event names**: When calling `publish()`, use specific event names that clearly describe the interaction (for example, `"loyalty_points_redeemed"` instead of `"click"`). This makes it easier for web pixel implementations to filter and process events. * **Separate analytics from visitor data**: Use `publish()` for events that web pixels should process and `visitor()` for contact details that should go to the shop backend. Don't use `publish()` to send visitor contact information. ***