Choose a version:

Customer Privacy API

Requires access to protected customer data for some properties.

The Customer Privacy API provides access to the buyer's privacy consent preferences during checkout. Use this API to check consent status for analytics and marketing, and display appropriate consent notices. It's similar to the Customer Privacy API in storefront.

Applying tracking consent changes requires the customer_privacy capability to be enabled in your extension configuration.

Anchor to Use casesUse cases

Check consent status: Determine whether the buyer has responded to analytics and marketing consent prompts.
Display a consent banner: Show a cookie preferences banner when consent hasn't been provided yet.
Respect privacy preferences: Conditionally render features based on the buyer's consent choices.

Support

Targets (31)

Supported targets

Anchor to Properties and methodsProperties and methods

The shopify global object provides customer privacy data and consent management. Access the following on shopify to read consent preferences and apply tracking consent changes. Available to purchase extension targets.

Anchor to applyTrackingConsentChange applyTrackingConsentChange required: Enables setting and updating customer privacy consent settings and tracking 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 <> required: Customer privacy consent settings and a flag denoting if consent has previously been collected.

ApplyTrackingConsentChangeType

visitorConsent
```
VisitorConsentChange
```

returns

Promise<TrackingConsentChangeResult>

VisitorConsentChange

analytics
The visitor's consent for analytics tracking. `true` means the visitor actively granted consent, `false` means actively denied, and `undefined` means no decision has been made yet.
```
boolean
```
marketing
The visitor's consent for marketing and targeted advertising. `true` means the visitor actively granted consent, `false` means actively denied, and `undefined` means no decision has been made yet.
```
boolean
```
metafields
Tracking consent metafield data to be saved. If the value is `null`, the metafield is deleted.
```
TrackingConsentMetafieldChange[]
```
preferences
The visitor's consent for storing preferences such as language and currency. `true` means the visitor actively granted consent, `false` means actively denied, and `undefined` means no decision has been made yet.
```
boolean
```
saleOfData
The visitor's consent for the sale or sharing of their personal data with third parties. `true` means the visitor actively granted consent, `false` means actively denied, and `undefined` means no decision has been made yet.
```
boolean
```
type
Identifies this as a visitor consent change. This is the only supported change type for `applyTrackingConsentChange()`.
```
'changeVisitorConsent'
```

TrackingConsentMetafieldChange

key
The identifier for the tracking consent metafield to update.
```
string
```
value
The new value to store in the metafield. Set to `null` to delete the metafield. Consent metafield values are strings, not booleans. Pass `null` to delete a tracking consent metafield.
```
string | null
```

TrackingConsentChangeResult

TrackingConsentChangeResultSuccess | TrackingConsentChangeResultError

TrackingConsentChangeResultSuccess

The returned result of a successful tracking consent preference update.

type
Indicates that the tracking consent update was applied successfully.
```
'success'
```

TrackingConsentChangeResultError

The returned result of an unsuccessful tracking consent preference update with a message detailing the type of error that occurred.

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.
```
string
```
type
Indicates that the tracking consent update couldn't be applied. Check the `message` property for details.
```
'error'
```

SubscribableSignalLike

Represents a reactive signal interface that provides both immediate value access and subscription-based updates. Enables real-time synchronization with changing data through the observer pattern. This interface extends `ReadonlySignalLike` with deprecated fields that are still supported for backwards compatibility.

current
The current value of the signal. Equivalent to `.value`, accessing this property subscribes to changes when used in a reactive context.
```
T
```
destroy
Cleans up the subscription and releases any resources held by this signal. After calling `destroy()`, the signal stops receiving updates from the main thread.
```
() => Promise<void>
```
subscribe
Subscribes to value changes and calls the provided function whenever the value updates. Returns an unsubscribe function to clean up the subscription. Use to automatically react to changes in the signal's value.
```
(fn: (value: T) => void) => () => void
```
value
The current value of the signal. This property provides immediate access to the current value without requiring subscription setup. Use for one-time value checks or initial setup.
```
T
```

CustomerPrivacy

allowedProcessing
Flags indicating whether each type of data processing is permitted, based on the visitor's consent, the merchant's privacy configuration, and the visitor's geographic location.
```
AllowedProcessing
```
metafields
The tracking consent metafields that have been stored for this visitor. These contain app-specific consent data beyond the standard categories.
```
TrackingConsentMetafield[]
```
region
The visitor's geographic location, used to determine whether more granular consent controls should be displayed based on regional privacy regulations.
```
CustomerPrivacyRegion
```
saleOfDataRegion
Whether the visitor is located in a region that requires an explicit opt-out option for the sale or sharing of personal data, such as California (CCPA) or other jurisdictions with similar regulations.
```
boolean
```
shouldShowBanner
Whether a consent banner should be displayed by default when the page loads. Use this as the initial open/expanded state of the consent banner. This is determined by the visitor's current privacy 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) settings, and the region in which the visitor is located.
```
boolean
```
visitorConsent
The visitor's current privacy consent settings. Each property represents a consent category and is `true` (actively granted), `false` (actively denied), or `undefined` (no decision made yet).
```
VisitorConsent
```

AllowedProcessing

analytics
Whether analytics data can be collected based on the visitor's consent, the merchant's privacy configuration, and the visitor's region. Analytics data includes how the shop was used and what interactions occurred. Whether analytics data can be collected right now. Combines the buyer's consent, the merchant's privacy configuration, and the buyer's region into a single boolean. Check this flag, not `visitorConsent.analytics`, before calling `shopify.analytics.publish()`.
```
boolean
```
marketing
Whether marketing data can be collected based on the visitor's consent, the merchant's privacy configuration, and the visitor's region. Marketing data includes attribution and targeted advertising preferences. Whether marketing data can be collected right now. Combines the buyer's consent, the merchant's privacy configuration, and the buyer's region into a single boolean. Check this flag, not `visitorConsent.marketing`, before performing marketing-related data collection.
```
boolean
```
preferences
Whether preference data can be collected based on the visitor's consent, the merchant's privacy configuration, and the visitor's region. Preference data includes language, currency, and sizing choices. Whether preference data can be collected right now. Combines the buyer's consent, the merchant's privacy configuration, and the buyer's region into a single boolean. Check this flag, not `visitorConsent.preferences`, before storing or reading buyer preference data.
```
boolean
```
saleOfData
Whether data can be shared with third parties based on the visitor's consent, the merchant's privacy configuration, and the visitor's region. This typically applies to behavioral advertising data. Whether buyer data can be shared with or sold to third parties right now. Combines the buyer's consent, the merchant's privacy configuration, and the buyer's region into a single boolean. Check this flag, not `visitorConsent.saleOfData`, before sharing or selling buyer data with third parties.
```
boolean
```

TrackingConsentMetafield

key
The identifier for the tracking consent metafield, such as `'analyticsType'` or `'marketingType'`.
```
string
```
value
The value stored in the tracking consent metafield, such as `'granular'` or a stringified JSON object.
```
string
```

CustomerPrivacyRegion

countryCode
The buyer's country code in [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) format. The value is `undefined` if geolocation failed. {% 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, state, or region code in [ISO 3166-2](https://en.wikipedia.org/wiki/ISO_3166-2) format. The value is `undefined` if geolocation failed or only the country was detected. {% 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
The visitor's consent for analytics tracking. `true` means the visitor actively granted consent, `false` means actively denied, and `undefined` means no decision has been made yet.
```
boolean
```
marketing
The visitor's consent for marketing and targeted advertising. `true` means the visitor actively granted consent, `false` means actively denied, and `undefined` means no decision has been made yet.
```
boolean
```
preferences
The visitor's consent for storing preferences such as language and currency. `true` means the visitor actively granted consent, `false` means actively denied, and `undefined` means no decision has been made yet.
```
boolean
```
saleOfData
The visitor's consent for the sale or sharing of their personal data with third parties. `true` means the visitor actively granted consent, `false` means actively denied, and `undefined` means no decision has been made yet.
```
boolean
```

Examples

jsx

import '@shopify/ui-extensions/preact';

import {render} from 'preact';

export default function extension() {

render(<Extension />, document.body);

}

function Extension() {

const {

analytics,

marketing,

preferences,

saleOfData,

} =

shopify.customerPrivacy.value.visitorConsent;

console.log('analytics', analytics);

console.log('marketing', marketing);

console.log('preferences', preferences);

console.log('saleOfData', saleOfData);

}

Examples

Description

Display the buyer's current tracking consent status for each category. This example renders `shopify.customerPrivacy.visitorConsent` and logs the analytics, marketing, preferences, and sale-of-data consent values.

jsx

import '@shopify/ui-extensions/preact';
import {render} from 'preact';

export default function extension() {
  render(<Extension />, document.body);
}

function Extension() {
  const {
    analytics,
    marketing,
    preferences,
    saleOfData,
  } =
    shopify.customerPrivacy.value.visitorConsent;

  console.log('analytics', analytics);
  console.log('marketing', marketing);
  console.log('preferences', preferences);
  console.log('saleOfData', saleOfData);
}

Description

Check whether the buyer has responded to analytics and marketing consent prompts. This example reads `shopify.customerPrivacy` and shows a banner when either preference is still undefined. See the [`customer_privacy` capability](/docs/apps/build/checkout/capabilities#collect-buyer-consent) for configuration.

jsx

import '@shopify/ui-extensions/preact';
import {render} from 'preact';

export default function extension() {
  render(<Extension />, document.body);
}

function Extension() {
  const customerPrivacy = shopify.customerPrivacy.value;

  const {analytics, marketing} =
    customerPrivacy.visitorConsent;

  if (
    analytics === undefined ||
    marketing === undefined
  ) {
    return (
      <s-banner heading="Cookie preferences">
        We use cookies to improve your experience.
        Update your preferences in your browser
        settings.
      </s-banner>
    );
  }

  return null;
}

Anchor to Best practicesBest practices

Use shouldShowBanner as the initial banner state: This property considers the visitor's current consent, the shop's region visibility settings, and the visitor's location. Use it instead of building custom logic to determine when to show a consent banner.
Distinguish between false and undefined in consent values: A false value in visitorConsent means the buyer explicitly declined consent. An undefined value means they haven't responded yet. Handle these states differently in your extension.

Was this page helpful?