Migrate to Polaris

Version 2025-07 is the last API version to support React-based UI components. Later versions use web components, native UI elements with built-in accessibility, better performance, and consistent styling with Shopify's design system. Check out the migration guide to upgrade your extension.

Choose a version:

Customer Privacy API

Requires access to protected customer data. The region property requires level 1 access. The applyTrackingConsentChange property requires the collect_buyer_consent capability.

The Customer Privacy API provides the buyer's current privacy consent settings, including consent flags, allowed processing activities, and region information. Use it to check consent status or determine whether to display a consent banner on the Order status page.

Anchor to Use casesUse cases

Display a consent banner: Determine whether to show a cookie consent banner when the page loads.
Read current consent state: Check the buyer's current preferences for analytics, marketing, and data sharing.
Apply consent changes: Save the buyer's updated consent preferences after they interact with your consent UI.
Handle regional requirements: Detect if the buyer is in a jurisdiction requiring specific opt-out controls, such as CCPA in California.

Support

Targets (25)

Supported targets

Anchor to PropertiesProperties

The Customer Privacy API object provides the buyer's privacy consent settings. Access the following properties on the API object to read privacy data.

Anchor to applyTrackingConsentChange applyTrackingConsentChange required: Applies changes to the buyer's tracking consent preferences and consent metafields.

Note
Requires the collect_buyer_consent capability to be set to true.
Note: Requires the <a href="/docs/apps/build/customer-accounts/capabilities#collect-buyer-consent"><code><span class="PreventFireFoxApplyingGapToWBR">collect<wbr/>_buyer<wbr/>_consent</span></code> capability</a> to be set to <code>true</code>.
Requires access to protected customer data.
Anchor to customerPrivacy customerPrivacy StatefulRemoteSubscribable<> required: The buyer's current privacy consent settings, including consent flags, allowed processing activities, and region information.

ApplyTrackingConsentChangeType

visitorConsent
```
VisitorConsentChange
```

returns

Promise<TrackingConsentChangeResult>

VisitorConsentChange

analytics
Whether the visitor consents to analytics tracking that measures how they interact with the site.
```
boolean
```
marketing
Whether the visitor consents to ads and marketing communications based on their interests.
```
boolean
```
metafields
Tracking consent metafield data to be saved. If the value is `null`, the metafield will be deleted.
```
TrackingConsentMetafieldChange[]
```
preferences
Whether the visitor consents to storing preferences, such as country or language, to personalize their experience.
```
boolean
```
saleOfData
Whether the visitor opts out of data sharing or sale of their personal data.
```
boolean
```
type
The type of consent change. Always `'changeVisitorConsent'`.
```
'changeVisitorConsent'
```

TrackingConsentMetafieldChange

key
The name of the metafield. It must be between 3 and 30 characters in length (inclusive).
```
string
```
value
The information to be stored as metadata. If the value is `null`, the metafield will be deleted.
```
string | null
```

TrackingConsentChangeResult

TrackingConsentChangeResultSuccess | TrackingConsentChangeResultError

TrackingConsentChangeResultSuccess

The result returned when a tracking consent preference update succeeds.

type
Always `'success'`, indicating the consent change was applied.
```
'success'
```

TrackingConsentChangeResultError

The result returned when a tracking consent preference update fails, including an error message.

message
A message that explains the error. This message is useful for debugging. It isn’t localized, and therefore shouldn’t be presented directly to the buyer.
```
string
```
type
Always `'error'`, indicating the consent change failed.
```
'error'
```

CustomerPrivacy

allowedProcessing
Flags indicating which data processing activities are allowed, based on the visitor's consent, merchant configuration, and the visitor's location.
```
AllowedProcessing
```
metafields
Custom key-value pairs that store additional tracking consent preferences, such as granular opt-in choices for analytics or marketing categories. The array is empty when no consent metafields have been set.
```
TrackingConsentMetafield[]
```
region
The visitor's geolocation data, used to determine whether region-specific consent controls should be displayed.
```
CustomerPrivacyRegion
```
saleOfDataRegion
Whether the visitor is in a region that requires explicit opt-out controls for the sale of personal data.
```
boolean
```
shouldShowBanner
Whether a consent banner should display when the page loads. Determined by the visitor's current consent, the shop's [region visibility configuration](https://help.shopify.com/en/manual/privacy-and-security/privacy/customer-privacy-settings/privacy-settings#add-a-cookie-banner), and the visitor's location.
```
boolean
```
visitorConsent
The visitor's explicit consent choices for analytics, marketing, preferences, and sale of data. Each flag is `true` (granted), `false` (denied), or `undefined` (no decision yet).
```
VisitorConsent
```

AllowedProcessing

analytics
Whether the app can collect analytics about how the buyer interacted with the shop.
```
boolean
```
marketing
Whether the app can use the buyer's data for marketing, attribution, and targeted advertising.
```
boolean
```
preferences
Whether the app can store the buyer's preferences, such as language, currency, and size.
```
boolean
```
saleOfData
Whether the buyer has opted out of data sharing with third parties for behavioral advertising.
```
boolean
```

TrackingConsentMetafield

key
The name of the metafield. It must be between 3 and 30 characters in length (inclusive).
```
string
```
value
The stored consent preference value, such as a consent level or a stringified JSON object with granular settings.
```
string
```

CustomerPrivacyRegion

countryCode
The [ISO 3166 Alpha-2 format](https://www.iso.org/iso-3166-country-codes.html) for the buyer's country. {% include /apps/checkout/privacy-icon.md %} Requires level 1 access to [protected customer data](/docs/apps/store/data-protection/protected-customer-data).
```
CountryCode
```
provinceCode
The buyer's province code, such as state, province, prefecture, or region. Province codes can be found by clicking on the `Subdivisions assigned codes` column for countries listed [here](https://en.wikipedia.org/wiki/ISO_3166-2). {% include /apps/checkout/privacy-icon.md %} Requires level 1 access to [protected customer data](/docs/apps/store/data-protection/protected-customer-data).
```
string
```

CountryCode

'AC' | 'AD' | 'AE' | 'AF' | 'AG' | 'AI' | 'AL' | 'AM' | 'AN' | 'AO' | 'AR' | 'AT' | 'AU' | 'AW' | 'AX' | 'AZ' | 'BA' | 'BB' | 'BD' | 'BE' | 'BF' | 'BG' | 'BH' | 'BI' | 'BJ' | 'BL' | 'BM' | 'BN' | 'BO' | 'BQ' | 'BR' | 'BS' | 'BT' | 'BV' | 'BW' | 'BY' | 'BZ' | 'CA' | 'CC' | 'CD' | 'CF' | 'CG' | 'CH' | 'CI' | 'CK' | 'CL' | 'CM' | 'CN' | 'CO' | 'CR' | 'CU' | 'CV' | 'CW' | 'CX' | 'CY' | 'CZ' | 'DE' | 'DJ' | 'DK' | 'DM' | 'DO' | 'DZ' | 'EC' | 'EE' | 'EG' | 'EH' | 'ER' | 'ES' | 'ET' | 'FI' | 'FJ' | 'FK' | 'FO' | 'FR' | 'GA' | 'GB' | 'GD' | 'GE' | 'GF' | 'GG' | 'GH' | 'GI' | 'GL' | 'GM' | 'GN' | 'GP' | 'GQ' | 'GR' | 'GS' | 'GT' | 'GW' | 'GY' | 'HK' | 'HM' | 'HN' | 'HR' | 'HT' | 'HU' | 'ID' | 'IE' | 'IL' | 'IM' | 'IN' | 'IO' | 'IQ' | 'IR' | 'IS' | 'IT' | 'JE' | 'JM' | 'JO' | 'JP' | 'KE' | 'KG' | 'KH' | 'KI' | 'KM' | 'KN' | 'KP' | 'KR' | 'KW' | 'KY' | 'KZ' | 'LA' | 'LB' | 'LC' | 'LI' | 'LK' | 'LR' | 'LS' | 'LT' | 'LU' | 'LV' | 'LY' | 'MA' | 'MC' | 'MD' | 'ME' | 'MF' | 'MG' | 'MK' | 'ML' | 'MM' | 'MN' | 'MO' | 'MQ' | 'MR' | 'MS' | 'MT' | 'MU' | 'MV' | 'MW' | 'MX' | 'MY' | 'MZ' | 'NA' | 'NC' | 'NE' | 'NF' | 'NG' | 'NI' | 'NL' | 'NO' | 'NP' | 'NR' | 'NU' | 'NZ' | 'OM' | 'PA' | 'PE' | 'PF' | 'PG' | 'PH' | 'PK' | 'PL' | 'PM' | 'PN' | 'PS' | 'PT' | 'PY' | 'QA' | 'RE' | 'RO' | 'RS' | 'RU' | 'RW' | 'SA' | 'SB' | 'SC' | 'SD' | 'SE' | 'SG' | 'SH' | 'SI' | 'SJ' | 'SK' | 'SL' | 'SM' | 'SN' | 'SO' | 'SR' | 'SS' | 'ST' | 'SV' | 'SX' | 'SY' | 'SZ' | 'TA' | 'TC' | 'TD' | 'TF' | 'TG' | 'TH' | 'TJ' | 'TK' | 'TL' | 'TM' | 'TN' | 'TO' | 'TR' | 'TT' | 'TV' | 'TW' | 'TZ' | 'UA' | 'UG' | 'UM' | 'US' | 'UY' | 'UZ' | 'VA' | 'VC' | 'VE' | 'VG' | 'VN' | 'VU' | 'WF' | 'WS' | 'XK' | 'YE' | 'YT' | 'ZA' | 'ZM' | 'ZW' | 'ZZ'

VisitorConsent

analytics
Whether the visitor consents to analytics tracking that measures how they interact with the site.
```
boolean
```
marketing
Whether the visitor consents to ads and marketing communications based on their interests.
```
boolean
```
preferences
Whether the visitor consents to storing preferences, such as country or language, to personalize their experience.
```
boolean
```
saleOfData
Whether the visitor opts out of data sharing or sale of their personal data.
```
boolean
```

Examples

import {

reactExtension,

useCustomerPrivacy,

} from '@shopify/ui-extensions-react/customer-account';

import {BlockStack, Text} from '@shopify/ui-extensions/customer-account';

export default reactExtension(

'customer-account.order-status.block.render',

() => <Extension />,

);

function consentLabel(value?: boolean) {

if (value === true) return 'Allowed';

if (value === false) return 'Not allowed';

return 'No decision';

}

function Extension() {

const privacy = useCustomerPrivacy();

return (

<Text emphasis="bold">Privacy settings</Text>

<Text>Analytics: {consentLabel(privacy.visitorConsent.analytics)}</Text>

<Text>Marketing: {consentLabel(privacy.visitorConsent.marketing)}</Text>

</BlockStack>

);

}

Examples

Description

Read the buyer's consent settings and display the current status for each category. This example uses `useCustomerPrivacy` to access the `visitorConsent` flags for analytics, marketing, and preferences.

React

import {
  reactExtension,
  useCustomerPrivacy,
} from '@shopify/ui-extensions-react/customer-account';
import {BlockStack, Text} from '@shopify/ui-extensions/customer-account';

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

function consentLabel(value?: boolean) {
  if (value === true) return 'Allowed';
  if (value === false) return 'Not allowed';
  return 'No decision';
}

function Extension() {
  const privacy = useCustomerPrivacy();
  return (
    <BlockStack>
      <Text emphasis="bold">Privacy settings</Text>
      <Text>Analytics: {consentLabel(privacy.visitorConsent.analytics)}</Text>
      <Text>Marketing: {consentLabel(privacy.visitorConsent.marketing)}</Text>
    </BlockStack>
  );
}

TS

import {extension, BlockStack, Text} from '@shopify/ui-extensions/customer-account';

function consentLabel(value?: boolean) {
  if (value === true) return 'Allowed';
  if (value === false) return 'Not allowed';
  return 'No decision';
}

export default extension(
  'customer-account.order-status.block.render',
  (root, api) => {
    const privacy = api.customerPrivacy.current;
    const stack = root.createComponent(BlockStack, {});
    stack.appendChild(root.createComponent(Text, {emphasis: 'bold'}, 'Privacy settings'));
    stack.appendChild(root.createComponent(Text, {}, `Analytics: ${consentLabel(privacy.visitorConsent.analytics)}`));
    stack.appendChild(root.createComponent(Text, {}, `Marketing: ${consentLabel(privacy.visitorConsent.marketing)}`));
    root.appendChild(stack);
  },
);

Description

Check whether a consent banner should display based on the buyer's privacy settings. This example uses `useCustomerPrivacy` to read the `shouldShowBanner` flag and conditionally renders the banner.

React

import {
  reactExtension,
  useCustomerPrivacy,
} from '@shopify/ui-extensions-react/customer-account';
import {Banner, Text} from '@shopify/ui-extensions/customer-account';

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

function Extension() {
  const privacy = useCustomerPrivacy();
  if (!privacy.shouldShowBanner) return null;
  return (
    <Banner status="info" title="Cookie preferences">
      <Text>Please review your cookie preferences to personalize your experience.</Text>
    </Banner>
  );
}

TS

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

export default extension(
  'customer-account.order-status.block.render',
  (root, api) => {
    const privacy = api.customerPrivacy.current;
    if (!privacy.shouldShowBanner) return;
    const banner = root.createComponent(Banner, {status: 'info', title: 'Cookie preferences'});
    banner.appendChild(root.createComponent(Text, {}, 'Please review your cookie preferences to personalize your experience.'));
    root.appendChild(banner);
  },
);

Description

Read the buyer's region information and display the detected country and province. This example uses `useCustomerPrivacy` to access the `region` property and handles cases where geolocation data is unavailable.

React

import {
  reactExtension,
  useCustomerPrivacy,
} from '@shopify/ui-extensions-react/customer-account';
import {BlockStack, Text} from '@shopify/ui-extensions/customer-account';

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

function Extension() {
  const privacy = useCustomerPrivacy();
  return (
    <BlockStack>
      {privacy.region && (
        <Text>
          Region: {privacy.region.countryCode}
          {privacy.region.provinceCode && `, ${privacy.region.provinceCode}`}
        </Text>
      )}
      {privacy.saleOfDataRegion && (
        <Text appearance="subdued">Data sale opt-out controls are available in your region.</Text>
      )}
    </BlockStack>
  );
}

TS

import {extension, BlockStack, Text} from '@shopify/ui-extensions/customer-account';

export default extension(
  'customer-account.order-status.block.render',
  (root, api) => {
    const privacy = api.customerPrivacy.current;
    const stack = root.createComponent(BlockStack, {});
    if (privacy.region) {
      let regionText = `Region: ${privacy.region.countryCode}`;
      if (privacy.region.provinceCode) regionText += `, ${privacy.region.provinceCode}`;
      stack.appendChild(root.createComponent(Text, {}, regionText));
    }
    if (privacy.saleOfDataRegion) {
      stack.appendChild(root.createComponent(Text, {appearance: 'subdued'}, 'Data sale opt-out controls are available in your region.'));
    }
    root.appendChild(stack);
  },
);

Anchor to Best practicesBest practices

Check shouldShowBanner before displaying a consent banner: The shouldShowBanner flag accounts for the buyer's current consent, the shop's region configuration, and the buyer's location.
Use allowedProcessing for data decisions: Check the allowedProcessing flags before collecting analytics, marketing, or preference data.

Anchor to LimitationsLimitations

Applying tracking consent changes requires the collect_buyer_consent capability to be enabled in your extension's configuration.
The region property requires level 1 access to protected customer data. Without this access, the visitor's location is unavailable.

Was this page helpful?