--- title: Customer Privacy API description: >- 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. 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/account-apis/customer-privacy-api md: >- https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/target-apis/account-apis/customer-privacy-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. # Customer Privacy API **Requires access to \[protected customer data]\(/docs/apps/store/data-protection/protected-customer-data). The \`region\` property requires level 1 access. The \`applyTrackingConsentChange\` property requires the \[\`collect\_buyer\_consent\` capability]\(/docs/api/customer-account-ui-extensions/2025-07#configuration).:** 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. ### Use 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 * 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 Customer Privacy API object provides the buyer's privacy consent settings. Access the following properties on the API object to read privacy data. * **applyTrackingConsentChange** **ApplyTrackingConsentChangeType** **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\. [](https://shopify.dev/apps/store/data-protection/protected-customer-data)Requires access to [protected customer data](https://shopify.dev/docs/apps/store/data-protection/protected-customer-data). * **customerPrivacy** **StatefulRemoteSubscribable\** **required** The buyer's current privacy consent settings, including consent flags, allowed processing activities, and region information. ### ApplyTrackingConsentChangeType * visitorConsent ```ts VisitorConsentChange ``` returns ```ts Promise ``` ### VisitorConsentChange * analytics Whether the visitor consents to analytics tracking that measures how they interact with the site. ```ts boolean ``` * marketing Whether the visitor consents to ads and marketing communications based on their interests. ```ts boolean ``` * metafields Tracking consent metafield data to be saved. If the value is \`null\`, the metafield will be deleted. ```ts TrackingConsentMetafieldChange[] ``` * preferences Whether the visitor consents to storing preferences, such as country or language, to personalize their experience. ```ts boolean ``` * saleOfData Whether the visitor opts out of data sharing or sale of their personal data. ```ts boolean ``` * type The type of consent change. Always \`'changeVisitorConsent'\`. ```ts 'changeVisitorConsent' ``` ### TrackingConsentMetafieldChange * key The name of the metafield. It must be between 3 and 30 characters in length (inclusive). ```ts string ``` * value The information to be stored as metadata. If the value is \`null\`, the metafield will be deleted. ```ts string | null ``` ### TrackingConsentChangeResult ```ts TrackingConsentChangeResultSuccess | TrackingConsentChangeResultError ``` ### TrackingConsentChangeResultSuccess The result returned when a tracking consent preference update succeeds. * type Always \`'success'\`, indicating the consent change was applied. ```ts '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. ```ts string ``` * type Always \`'error'\`, indicating the consent change failed. ```ts 'error' ``` ### CustomerPrivacy * allowedProcessing Flags indicating which data processing activities are allowed, based on the visitor's consent, merchant configuration, and the visitor's location. ```ts 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. ```ts TrackingConsentMetafield[] ``` * region The visitor's geolocation data, used to determine whether region-specific consent controls should be displayed. ```ts CustomerPrivacyRegion ``` * saleOfDataRegion Whether the visitor is in a region that requires explicit opt-out controls for the sale of personal data. ```ts 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. ```ts 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). ```ts VisitorConsent ``` ### AllowedProcessing * analytics Whether the app can collect analytics about how the buyer interacted with the shop. ```ts boolean ``` * marketing Whether the app can use the buyer's data for marketing, attribution, and targeted advertising. ```ts boolean ``` * preferences Whether the app can store the buyer's preferences, such as language, currency, and size. ```ts boolean ``` * saleOfData Whether the buyer has opted out of data sharing with third parties for behavioral advertising. ```ts boolean ``` ### TrackingConsentMetafield * key The name of the metafield. It must be between 3 and 30 characters in length (inclusive). ```ts string ``` * value The stored consent preference value, such as a consent level or a stringified JSON object with granular settings. ```ts 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). ```ts 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). ```ts string ``` ### CountryCode ```ts '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. ```ts boolean ``` * marketing Whether the visitor consents to ads and marketing communications based on their interests. ```ts boolean ``` * preferences Whether the visitor consents to storing preferences, such as country or language, to personalize their experience. ```ts boolean ``` * saleOfData Whether the visitor opts out of data sharing or sale of their personal data. ```ts boolean ``` Examples ### 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 ```tsx 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', () => , ); function consentLabel(value?: boolean) { if (value === true) return 'Allowed'; if (value === false) return 'Not allowed'; return 'No decision'; } function Extension() { const privacy = useCustomerPrivacy(); return ( Privacy settings Analytics: {consentLabel(privacy.visitorConsent.analytics)} Marketing: {consentLabel(privacy.visitorConsent.marketing)} ); } ``` ##### TS ```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 ```tsx 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', () => , ); function Extension() { const privacy = useCustomerPrivacy(); if (!privacy.shouldShowBanner) return null; return ( Please review your cookie preferences to personalize your experience. ); } ``` ##### TS ```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 ```tsx 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', () => , ); function Extension() { const privacy = useCustomerPrivacy(); return ( {privacy.region && ( Region: {privacy.region.countryCode} {privacy.region.provinceCode && `, ${privacy.region.provinceCode}`} )} {privacy.saleOfDataRegion && ( Data sale opt-out controls are available in your region. )} ); } ``` ##### TS ```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); }, ); ``` *** ## Best 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. *** ## Limitations * Applying tracking consent changes requires the [`collect_buyer_consent` capability](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07#configuration) to be enabled in your extension's configuration. * The `region` property requires level 1 access to [protected customer data](https://shopify.dev/docs/apps/store/data-protection/protected-customer-data). Without this access, the visitor's location is unavailable. ***