---
title: Analytics API
description: >-
  The Analytics API lets you publish custom events and visitor information to
  web pixels configured on the store. Use this API to track customer behavior in
  your extension and send conversion data to third-party analytics services.
api_version: 2025-07
api_name: customer-account-ui-extensions
source_url:
  html: >-
    https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/target-apis/platform-apis/analytics-api
  md: >-
    https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/target-apis/platform-apis/analytics-api.md
---

Migrate to Polaris

Version 2025-07 is the last API version to support React-based UI components. Later versions use [web components](https://shopify.dev/docs/api/customer-account-ui-extensions/latest/polaris-web-components), native UI elements with built-in accessibility, better performance, and consistent styling with [Shopify's design system](https://shopify.dev/docs/apps/design). Check out the [migration guide](https://shopify.dev/docs/apps/build/customer-accounts/migrate-to-web-components) to upgrade your extension.

# Analytics API

The Analytics API lets you publish custom events and visitor information to [web pixels](https://shopify.dev/docs/api/web-pixels-api) configured on the store. Use this API to track customer behavior in your extension and send conversion data to third-party analytics services.

### Use cases

* **Track extension interactions**: Publish custom events when customers interact with your extension, such as viewing a product recommendation or clicking a promotion banner.
* **Measure conversions**: Send conversion events from customer account pages to analytics platforms for attribution and reporting.
* **Identify returning visitors**: Submit visitor contact information so downstream analytics tools can associate sessions with known customers.

### Support Targets (25)

### Supported targets

* Customer​Account::Kitchen​Sink
* [customer-account.​footer.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/footer#footer-render-after-)
* [customer-account.​order-index.​announcement.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/order-index#order-index-targets)
* [customer-account.​order-index.​block.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/order-index#order-index-block-)
* [customer-account.​order-status.​announcement.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/order-status#order-status-announcement-)
* [customer-account.​order-status.​block.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/order-status#order-status-block-)
* [customer-account.​order-status.​cart-line-item.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/order-status#cart-line-item-render-after-)
* [customer-account.​order-status.​cart-line-list.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/order-status#cart-line-list-render-after-)
* [customer-account.​order-status.​customer-information.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/order-status#customer-information-render-after-)
* [customer-account.​order-status.​fulfillment-details.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/fulfillment-status#fulfillment-status-targets)
* [customer-account.​order-status.​payment-details.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/payments-and-returns#payments-and-returns-targets)
* [customer-account.​order-status.​return-details.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/payments-and-returns#return-details-render-after-)
* [customer-account.​order-status.​unfulfilled-items.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/fulfillment-status#unfulfilled-items-render-after-)
* [customer-account.​order.​action.​menu-item.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/order-actions#order-action-menu-item-)
* [customer-account.​order.​action.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/order-actions#order-action-)
* [customer-account.​order.​page.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/full-page#order-specific-full-page-)
* [customer-account.​page.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/full-page#customer-account-full-page-)
* [customer-account.​profile.​addresses.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/profile-page-default#profile-page-default-targets-)
* [customer-account.​profile.​announcement.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/profile-page-default#announcement-)
* [customer-account.​profile.​block.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/profile-page-default#profile-block-)
* [customer-account.​profile.​company-details.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/profile-page-b2b#profile-page-b2b-targets-)
* [customer-account.​profile.​company-location-addresses.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/profile-page-b2b#company-location-addresses-render-after-)
* [customer-account.​profile.​company-location-payment.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/profile-page-b2b#company-location-payment-render-after-)
* [customer-account.​profile.​company-location-staff.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/profile-page-b2b#company-location-staff-render-after-)
* customer-account.​profile.​payment.​render-after

### Properties

The Analytics API object provides the analytics interface for customer account extensions. Access the following properties on the API object to publish custom events and send visitor data to web pixels.

* **analytics**

  **Analytics**

  **required**

  Methods for interacting with [web pixels](https://shopify.dev/docs/apps/build/marketing-analytics/pixels), such as publishing analytics events.

  **Note:** Requires a \<a href="https://help.shopify.com/en/manual/domains/add-a-domain/connecting-domains/connect-domain-customer-account">connected third-party domain\</a> for your customer account pages.

### Analytics

Methods for interacting with \[web pixels]\(/docs/apps/build/marketing-analytics/pixels), including publishing analytics events and capturing visitor identity data.

* publish

  Publishes analytics events to \[web pixels]\(/docs/apps/build/marketing-analytics/pixels). Events are forwarded to all subscribed pixels.

  ```ts
  (name: string, data: Record<string, unknown>) => Promise<boolean>
  ```

* visitor

  Captures visitor identity data (email or phone) for analytics and marketing attribution.

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

### VisitorResult

Represents a visitor result.

```ts
VisitorSuccess | VisitorError
```

### VisitorSuccess

Represents a successful visitor result.

* type

  Indicates the visitor information was successfully 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's \*\*not\*\* localized, and therefore should not be presented directly to the buyer.

  ```ts
  string
  ```

* type

  Indicates the visitor information was invalid and wasn't submitted, such as using an incorrect data type or missing a required property.

  ```ts
  'error'
  ```

Examples

### Examples

* #### Publish a custom analytics event

  ##### Description

  Publish a custom event to all web pixels configured on the store. This example fires a \`customer-account-extension-loaded\` event when the extension mounts and logs whether the publish succeeded.

  ##### React

  ```tsx
  import {
    Banner,
    reactExtension,
    useApi,
  } from '@shopify/ui-extensions-react/customer-account';

  export default reactExtension(
    'customer-account.order-status.block.render',
    () => <Extension />,
  );

  function Extension() {
    const {analytics} = useApi();

    analytics
      .publish(
        'customer-account-extension-loaded',
        {
          extensionName: 'My Extension',
        },
      )
      .then((result) => {
        if (result) {
          console.log(
            'successfully published event, web pixels can now receive this event',
          );
        } else {
          console.log('failed to publish event');
        }
      })
      .catch((error) => {
        console.log('failed to publish event');
        console.log('error', error);
      });

    return <Banner>See console for result</Banner>;
  }
  ```

  ##### TS

  ```js
  import {
    extension,
    Banner,
  } from '@shopify/ui-extensions/customer-account';

  export default extension(
    'customer-account.order-status.block.render',
    (root, {analytics}) => {
      analytics
        .publish(
          'customer-account-extension-loaded',
          {
            extensionName: 'My Extension',
          },
        )
        .then((result) => {
          if (result) {
            console.log(
              'successfully published event, web pixels can now receive this event',
            );
          } else {
            console.log('failed to publish event');
          }
        })
        .catch((error) => {
          console.error('failed to publish event');
          console.error('error', error);
        });

      root.appendChild(
        root.createComponent(
          Banner,
          {},
          'See console for result',
        ),
      );
    },
  );
  ```

* #### Submit visitor information

  ##### Description

  Send visitor contact details to the store backend for identity resolution. This example submits an email and phone number and handles the success or error response.

  ##### React

  ```tsx
  import {
    Banner,
    reactExtension,
    useApi,
  } from '@shopify/ui-extensions-react/customer-account';

  export default reactExtension(
    'customer-account.order-status.block.render',
    () => <Extension />,
  );

  function Extension() {
    const {analytics} = useApi();

    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 <Banner>See console for result</Banner>;
  }
  ```

  ##### TS

  ```js
  import {
    extension,
    Banner,
  } from '@shopify/ui-extensions/customer-account';

  export default extension(
    'customer-account.order-status.block.render',
    (root, {analytics}) => {
      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);
          }
        });

      root.appendChild(
        root.createComponent(
          Banner,
          {},
          'See console for result',
        ),
      );
    },
  );
  ```

***

## Best practices

* **Publish events inside `useEffect`**: Trigger analytics calls after the component mounts so you don't block the initial render.
* **Handle publish failures gracefully**: Always attach a `.catch()` handler to `shopify.analytics.publish()` so undelivered events don't cause uncaught promise rejections.
* **Use descriptive event names**: Choose event names that clearly identify the interaction, such as `loyalty-points-redeemed` or `subscription-upgraded`, so pixel consumers can filter and act on them.
* **Avoid sending sensitive data in event payloads**: Don't include passwords, full payment details, or other personally identifiable information beyond what's needed for analytics.

***

## Limitations

* Custom events published through this API are only delivered to web pixels that are configured on the store. If no pixels are active, the publish call resolves but has no downstream effect.
* The `shopify.analytics.visitor()` method sends data to the store backend only. Visitor information isn't propagated to web pixels on the page.
* Event payloads must be JSON-serializable. Functions, DOM nodes, and circular references can't be included.

***