---
title: Analytics API
description: >-
  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, or to submit visitor contact details directly to the
  shop backend.
api_version: 2026-04
api_name: checkout-ui-extensions
source_url:
  html: >-
    https://shopify.dev/docs/api/checkout-ui-extensions/latest/target-apis/platform-apis/analytics-api
  md: >-
    https://shopify.dev/docs/api/checkout-ui-extensions/latest/target-apis/platform-apis/analytics-api.md
---

# 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-04/targets/checkout/address#format-a-selected-suggestion-)
* [purchase.​address-autocomplete.​suggest](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/address#suggest-address-completions-)
* [purchase.​checkout.​actions.​render-before](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/navigation#navigation-target)
* [purchase.​checkout.​block.​render](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/block#block-target)
* [purchase.​checkout.​cart-line-item.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/order-summary#line-item-targets)
* [purchase.​checkout.​cart-line-list.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/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-04/targets/checkout/information#information-target)
* [purchase.​checkout.​delivery-address.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/shipping#render-after-delivery-address-)
* [purchase.​checkout.​delivery-address.​render-before](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/shipping#delivery-address-targets)
* [purchase.​checkout.​footer.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/footer#footer-target)
* [purchase.​checkout.​header.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/header#header-target)
* [purchase.​checkout.​payment-method-list.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/payment#render-after-payment-methods-)
* [purchase.​checkout.​payment-method-list.​render-before](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/payment#payment-targets)
* [purchase.​checkout.​pickup-location-list.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/local-pickup#render-after-pickup-locations-)
* [purchase.​checkout.​pickup-location-list.​render-before](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/local-pickup#location-list-targets)
* [purchase.​checkout.​pickup-location-option-item.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/local-pickup#location-option-item-target)
* [purchase.​checkout.​pickup-point-list.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/pickup-points#render-after-pickup-points-)
* [purchase.​checkout.​pickup-point-list.​render-before](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/pickup-points#pickup-points-targets)
* [purchase.​checkout.​reductions.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/order-summary#checkout-reductions-after-)
* [purchase.​checkout.​reductions.​render-before](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/order-summary#reductions-targets)
* [purchase.​checkout.​shipping-option-item.​details.​render](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/shipping#shipping-option-item-targets)
* [purchase.​checkout.​shipping-option-item.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/shipping#render-after-shipping-option-)
* [purchase.​checkout.​shipping-option-list.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/shipping#render-after-shipping-options-)
* [purchase.​checkout.​shipping-option-list.​render-before](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/shipping#shipping-option-list-targets)
* [purchase.​thank-you.​announcement.​render](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/thank-you/announcement#thank-you-announcement-)
* [purchase.​thank-you.​block.​render](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/thank-you/block#block-target)
* [purchase.​thank-you.​cart-line-item.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/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-04/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-04/targets/thank-you/information#information-target)
* [purchase.​thank-you.​footer.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/thank-you/footer#footer-target)
* [purchase.​thank-you.​header.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/thank-you/header#header-target)

### Properties and methods

The [`shopify` global object](https://shopify.dev/docs/api/checkout-ui-extensions/latest#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<string, unknown>) => Promise<boolean>
  ```

* visitor

  Submits buyer contact details for attribution and analytics purposes.

  ```ts
  (data: { email?: string; phone?: string; }) => Promise<VisitorResult>
  ```

### 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(<Extension />, 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 (
      <s-banner>See console for result</s-banner>
    );
  }
  ```

* ####

  ##### 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(<Extension />, 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 (
      <s-banner>See console for result</s-banner>
    );
  }
  ```

***

## 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/latest/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.

***