Customer Privacy API
The Customer Privacy API is a browser-based, JavaScript API that you can use to verify data processing permissions or build a cookie consent banner.
This API is used to apply consent decisions to Shopify-managed surfaces, like pixels, audiences, and checkout.
Mobile app developers using Checkout Kit should see privacy compliance guide to learn how to pass visitor consent through the Storefront API's @inContext directive.
Mobile app developers using Checkout Kit should see privacy compliance guide to learn how to pass visitor consent through the Storefront API's @inContext directive.
Refer to the full list of cookies that Shopify uses.
Anchor to What you'll learnWhat you'll learn
Check what processing is allowed
To build a cookie banner
- Load the Customer Privacy API
- Collect and set consent
- Custom storefront installation
- Control the cookie banner
Anchor to Loading the Customer Privacy APILoading the Customer Privacy API
To use the Customer Privacy API, you must load it using loadFeatures as follows:
The second argument to loadFeatures is a callback that indicates that the API has loaded. When invoked without an error, the API is globally available at window.Shopify.customerPrivacy.
Anchor to Check data processing permissionsCheck data processing permissions
Collecting data without consent might not comply with applicable laws. Consult legal counsel to discuss the requirements that apply to your business.
Collecting data without consent might not comply with applicable laws. Consult legal counsel to discuss the requirements that apply to your business.
To check what processing is allowed, use the Allowed methods. These methods combine the following factors to determine what processing is allowed:
-
The current merchant settings: Is consent required in this region?
-
User location: Is the customer in a region where consent is required?
-
User consent given: Did the customer give consent for a specific purpose?
You can check for permission by calling the API or with an event listener.
The default permissions state depends on how merchants have configured their privacy settings. For regions that are configured to require consent, non-essential purposes are not allowed by default until consent is given. For other regions, the default behavior is to allow all processing purposes.
Anchor to Call the APICall the API
The Customer Privacy API offers the following methods to check if data can be processed:
These methods return true / false if permission is given for the following:
preferencesProcessingAllowed: customer preferences such as language, currency, size, and more.analyticsProcessingAllowed: customer analytics about how the storefront was used and interactions made on the storefront.marketingAllowed: Marketing, attribution and targeted advertising from the merchant.saleOfDataAllowed: Sharing data with third parties, usually for behaviorial advertising.
Anchor to Use an event listenerUse an event listener
The Customer Privacy API publishes the document event visitorConsentCollected when consent changes.
Output
Updates are published only when consent changes, not when the listener is added.
Anchor to Check customer locationCheck customer location
You can see the detected geolocation by using the getRegion method. It returns a ISO 3166-2-formatted string with a two character country code, followed by an optional one to three character region code. Returns an empty string if the location can't be determined.
Examples:
- "USCA": California, USA
- "CAON": Ontario, Canada
- "IEL": Leinster, Ireland
- "GBENG": England, United Kingdom
Anchor to Retrieve a Consent IDRetrieve a Consent ID
A customer can retrieve their consent id using the consentId command. This is useful to check their consent history in the merchants consent audit log.
Anchor to Collect and register consentCollect and register consent
- Never read/modify any Shopify cookies directly or your processing will fail when new versions are released. Instead, always use this API to manage customer privacy settings.
- Recording customer consent should only be done on a visitor interaction (such as a visitor accepting or declining via a cookie banner), and never done automatically on behalf of the visitor.
- Never read/modify any Shopify cookies directly or your processing will fail when new versions are released. Instead, always use this API to manage customer privacy settings.
- Recording customer consent should only be done on a visitor interaction (such as a visitor accepting or declining via a cookie banner), and never done automatically on behalf of the visitor.
To record customer consent, use the setTrackingConsent method:
The following consent purposes are supported:
-
Preferences: Cookies that remember customer preferences, such as country or language, to personalize visits to the website. -
Analytics: Cookies to understand how customers interact with the site. -
Marketing: Cookies to provide ads and marketing communications based on customer interests.See the Shopify Cookie Policy for the full list of cookies used by Shopify.
You can set one or more consent signals at once:
Output
Output
Anchor to Collect and register data sale / sharing opt-outCollect and register data sale / sharing opt-out
Data sale / sharing opt-out should be managed in an opt-out flow started by customers, instead of an opt-in flow that activates immediately upon page load.
Data sale / sharing opt-out should be managed in an opt-out flow started by customers, instead of an opt-in flow that activates immediately upon page load.
To record a customer's opt-out from data sale / sharing, use the setTrackingConsent method with the sale_of_data option:
Data sale opt-outs should be initiated by the customer, not presented immediately with a banner. For this reason, true allows data sale / sharing and false blocks data sale / sharing when requested by a customer.
Data sale / sharing opt-out is enforced independently from consent, and caution is advised when combining them.
To opt a Customer out of server-side data sale / sharing use the dataSaleOptOut GraphQL API.
The GPC signal is automatically collected and honored in regions configured for data sale opt-out and cannot be adjusted through setTrackingConsent.
Output
Anchor to MetafieldsMetafields
You can save custom data to this API using the optional metafields argument, which is also available through checkout UI extensions.
Metafields takes an Array containing an object with two keys:
key: A string containing the key used to identify this value. This value must be 25 characters or less.value: A string containing the value.Nullmay be passed to delete the key. This value must be 100 characters or less. Themetafieldsobject must be less than 250 characters in total.
Anchor to Custom storefrontsCustom storefronts
For custom storefronts, pass the following additional parameters to the setTrackingConsent method:
-
headlessStorefront:true, -
checkoutRootDomain: Your checkout domain -
storefrontRootDomain: Your storefront domain -
storefrontAccessToken: Your Storefront API access tokenLearn more about installing the Customer Privacy API into a custom storefront.
Anchor to Check consent givenCheck consent given
Check users' consent decisions by calling the currentVisitorConsent method. This returns the preferences selected by the users and doesn't include critical information like location and merchant configuration.
Use the Allowed methods to check what processing is allowed. They combine several factors missing from the currentVisitorConsent method.
Use the Allowed methods to check what processing is allowed. They combine several factors missing from the currentVisitorConsent method.
Output
'yes'- the current visitor has actively granted consent.'no'- the current visitor has actively denied consent.''(empty string) - the current visitor has not yet granted or denied consent.
To check if a cookie consent banner should be displayed to the current customer, use shouldShowBanner. This method indicates if the current customers is in a region that's configured to show a cookie banner.
The method doesn't indicate if consent has already been given.
The method doesn't indicate if consent has already been given.
Output
This is true if consent isn't already set and the visitor is in a region showing consent.
Anchor to Check if data sale opt out is availableCheck if data sale opt out is available
To check if the current customer is eligible for data sale opt-out, use the saleOfDataRegion method. This method indicates whether the current customers is in a region configured for data sale opt outs.
Output
This is true if the visitor is from a region that requires data sale opt-outs.
When the Shopify cookie banner is enabled, it displays in the configured regions and automatically passes consent to this API.
If you're using an app to provide cookie banners, then contact the app's developer to understand where the consent banner is rendered.
Learn more about configuring a cookie banner.
Anchor to Regions showing data sale opt outRegions showing data sale opt out
When the data sale opt out page is enabled, the opt out form is available to visitors from the configured regions, which is usually US states. In these regions, the Global Privacy Control (GPC) is honored automatically, sale_of_data will be set to false, refer above for details.
Anchor to Installation on a custom storefrontInstallation on a custom storefront
Use Hydrogen analytics and consent to collect visitor consent and analytics. Hydrogen Analytics manages the Shopify session server-side, so consent persists across page loads and is honored by checkout. It's also the only way to fully integrate the cookie banner with Shopify Analytics.
These API methods let you control and interact with the Shopify cookie banner at runtime.
Anchor to Showing the preferences modalShowing the preferences modal
You can show the preferences modal of the Shopify cookie banner using the showPreferences() method: