--- title: Customer Privacy API description: >- The API for interacting with a customer's privacy consent. It is similar to the [Customer Privacy API in storefront](/docs/api/customer-privacy). api_version: 2026-04 api_name: checkout-ui-extensions source_url: html: >- https://shopify.dev/docs/api/checkout-ui-extensions/latest/target-apis/checkout-apis/customer-privacy-api md: >- https://shopify.dev/docs/api/checkout-ui-extensions/latest/target-apis/checkout-apis/customer-privacy-api.md --- # Customer Privacy API **Requires access to \[protected customer data]\(/docs/apps/store/data-protection/protected-customer-data) for some properties.:** The API for interacting with a customer's privacy consent. It is similar to the [Customer Privacy API in storefront](https://shopify.dev/docs/api/customer-privacy). ### Support Targets (31) ### Supported targets * purchase.​checkout.​actions.​render-before * purchase.​checkout.​block.​render * purchase.​checkout.​cart-line-item.​render-after * purchase.​checkout.​cart-line-list.​render-after * purchase.​checkout.​chat.​render * purchase.​checkout.​contact.​render-after * purchase.​checkout.​delivery-address.​render-after * purchase.​checkout.​delivery-address.​render-before * purchase.​checkout.​footer.​render-after * purchase.​checkout.​header.​render-after * purchase.​checkout.​payment-method-list.​render-after * purchase.​checkout.​payment-method-list.​render-before * purchase.​checkout.​pickup-location-list.​render-after * purchase.​checkout.​pickup-location-list.​render-before * purchase.​checkout.​pickup-location-option-item.​render-after * purchase.​checkout.​pickup-point-list.​render-after * purchase.​checkout.​pickup-point-list.​render-before * purchase.​checkout.​reductions.​render-after * purchase.​checkout.​reductions.​render-before * purchase.​checkout.​shipping-option-item.​details.​render * purchase.​checkout.​shipping-option-item.​render-after * purchase.​checkout.​shipping-option-list.​render-after * purchase.​checkout.​shipping-option-list.​render-before * purchase.​thank-you.​announcement.​render * purchase.​thank-you.​block.​render * purchase.​thank-you.​cart-line-item.​render-after * purchase.​thank-you.​cart-line-list.​render-after * purchase.​thank-you.​chat.​render * purchase.​thank-you.​customer-information.​render-after * purchase.​thank-you.​footer.​render-after * purchase.​thank-you.​header.​render-after ## StandardApi The base API object provided to `purchase` extension targets. * **applyTrackingConsentChange** **ApplyTrackingConsentChangeType** **required** Enables setting and updating customer privacy consent settings and tracking consent metafields. **Note:** Requires the \\\customer\\_privacy\\ 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** **SubscribableSignalLike\** **required** Customer privacy consent settings and a flag denoting if consent has previously been collected. ### ApplyTrackingConsentChangeType * visitorConsent ```ts VisitorConsentChange ``` Promise\ ```ts Promise ``` ### 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. ```ts 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. ```ts boolean ``` * metafields Tracking consent metafield data to be saved. If the value is \`null\`, the metafield is deleted. ```ts 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. ```ts 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. ```ts boolean ``` * type Identifies this as a visitor consent change. This is the only supported change type for \`applyTrackingConsentChange()\`. ```ts 'changeVisitorConsent' ``` ### TrackingConsentMetafieldChange * key The identifier for the tracking consent metafield to update. ```ts string ``` * value The new value to store in the metafield. Set to \`null\` to delete the metafield. ```ts string | null ``` ### TrackingConsentChangeResult ```ts TrackingConsentChangeResultSuccess | TrackingConsentChangeResultError ``` ### TrackingConsentChangeResultSuccess The returned result of a successful tracking consent preference update. * type Indicates that the tracking consent update was applied successfully. ```ts '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. ```ts string ``` * type Indicates that the tracking consent update couldn't be applied. Check the \`message\` property for details. ```ts '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. ```ts 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. ```ts () => Promise ``` * 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. ```ts (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. ```ts 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. ```ts AllowedProcessing ``` * metafields The tracking consent metafields that have been stored for this visitor. These contain app-specific consent data beyond the standard categories. ```ts TrackingConsentMetafield[] ``` * region The visitor's geographic location, used to determine whether more granular consent controls should be displayed based on regional privacy regulations. ```ts 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. ```ts 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. ```ts 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). ```ts 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. ```ts 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. ```ts 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. ```ts 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. ```ts boolean ``` ### TrackingConsentMetafield * key The identifier for the tracking consent metafield, such as \`'analyticsType'\` or \`'marketingType'\`. ```ts string ``` * value The value stored in the tracking consent metafield, such as \`'granular'\` or a stringified JSON object. ```ts 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). ```ts 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). ```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 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. ```ts 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. ```ts 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. ```ts 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. ```ts boolean ``` ## use​Customer​Privacy() Returns the current customer privacy settings and metadata and re-renders your component if the customer privacy settings change. ### Returns * **CustomerPrivacy** ### ### CustomerPrivacy * **allowedProcessing** **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. * **metafields** **TrackingConsentMetafield\[]** The tracking consent metafields that have been stored for this visitor. These contain app-specific consent data beyond the standard categories. * **saleOfDataRegion** **boolean** 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. * **shouldShowBanner** **boolean** 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. * **visitorConsent** **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). * **region** **CustomerPrivacyRegion** The visitor's geographic location, used to determine whether more granular consent controls should be displayed based on regional privacy regulations. Examples ### Examples * #### Read Customer Privacy ##### Preact ```jsx import '@shopify/ui-extensions/preact'; import {render} from 'preact'; export default function extension() { render(, 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); } ``` ## Related [Reference - Targets](https://shopify.dev/docs/api/checkout-ui-extensions/targets) [Reference - Components](https://shopify.dev/docs/api/checkout-ui-extensions/components) [Reference - Configuration](https://shopify.dev/docs/api/checkout-ui-extensions/configuration) [Learn - Tutorials](https://shopify.dev/apps/checkout)