Upgrade to Polaris

Version 2025-07 is the last API version to support React-based UI components. Later versions use Polaris web components, native UI elements with built-in accessibility, better performance, and consistent styling with Shopify's design system. Check out the upgrade guide to upgrade your extension and avoid being blocked from updating your extension after October 1st 2026.

Choose a version:

Analytics API

The API for interacting with web pixels.

Anchor to StandardApiStandardApi

The base API object provided to purchase extension targets.

Anchor to analytics analytics required: The methods for interacting with Web Pixels, such as emitting an event.

Analytics

publish
Publish method to emit analytics events to [Web Pixels](/docs/apps/marketing).
```
(name: string, data: Record<string, unknown>) => Promise<boolean>
```
visitor
A method for capturing details about a visitor on the online store.
```
(data: { email?: string; phone?: string; }) => Promise<VisitorResult>
```

VisitorResult

Represents a visitor result.

VisitorSuccess | VisitorError

VisitorSuccess

Represents a successful visitor result.

type
Indicates that the visitor information was validated and submitted.
```
'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.
```
string
```
type
Indicates that the visitor information is invalid and wasn't submitted. Examples are using the wrong data type or missing a required property.
```
'error'
```

Examples

import {useState, useEffect} from 'react';

import {

Banner,

reactExtension,

useApi,

} from '@shopify/ui-extensions-react/checkout';

export const purchaseCheckoutBlockRender =

reactExtension(

'purchase.checkout.block.render',

() => <Extension />,

);

function Extension() {

const {analytics} = useApi();

analytics

.publish('checkout-extension-loaded', {

extensionName: 'My Extension',

})

.then((result) => {

if (result) {

console.log(

'succesfully published event, web pixels can now recieve 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>;

}

Examples

Publish

Description

You can publish analytics events to the Shopify analytics frameworks and they will be propagated to all web pixels on the page.

React

import {useState, useEffect} from 'react';
import {
  Banner,
  reactExtension,
  useApi,
} from '@shopify/ui-extensions-react/checkout';

export const purchaseCheckoutBlockRender =
  reactExtension(
    'purchase.checkout.block.render',
    () => <Extension />,
  );

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

  analytics
    .publish('checkout-extension-loaded', {
      extensionName: 'My Extension',
    })
    .then((result) => {
      if (result) {
        console.log(
          'succesfully published event, web pixels can now recieve 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>;
}

JavaScript

import {extension} from '@shopify/ui-extensions-react/checkout';
import {useEffect} from 'react';

export default extension(
  'purchase.checkout.block.render',
  (root, {analytics}) => {
    useEffect(() => {
      analytics
        .publish('checkout-extension-loaded', {
          extensionName: 'My Extension',
        })
        .then((result) => {
          if (result) {
            console.log(
              'succesfully published event, web pixels can now recieve this event',
            );
          } else {
            console.log(
              'failed to publish event',
            );
          }
        })
        .catch((error) => {
          console.error(
            'failed to publish event',
          );
          console.error('error', error);
        });
    });
  },
);

Visitor

Description

You can submit visitor information to Shopify, these will be sent to the shop backend and not be propagated to web pixels on the page.

React

import {useState, useEffect} from 'react';
import {
  Banner,
  reactExtension,
  useApi,
} from '@shopify/ui-extensions-react/checkout';

export const purchaseCheckoutBlockRender =
  reactExtension(
    'purchase.checkout.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>;
}

JavaScript

import {extension} from '@shopify/ui-extensions-react/checkout';

export default extension(
  'purchase.checkout.block.render',
  (root, {analytics}) => {
    analytics
      .visitor({
        email: 'someEmail@example.com',
        phone: '+1 555 555 5555',
      })
      .then((result) => {
        if (result.type === 'success') {
          console.log(
            `Success`,
            JSON.stringify(result),
          );
        } else {
          console.log(
            `Error`,
            JSON.stringify(result),
          );
        }
      });
  },
);

Anchor to RelatedRelated

ReferenceTargets

ReferenceComponents

ReferenceConfiguration

LearnTutorials

Was this page helpful?