Customer Privacy API
The Customer Privacy API is a browser-based, JavaScript API that you can use to register consent and query data processing permission.
You can use the Customer Privacy API to build a custom cookie consent banner for your storefront or guard certain activities behind consent.
This API is used to report consent decisions that can be honored on Shopify-managed surfaces, like pixels, audiences, and checkout.
What you'll learn
Anchor link to section titled "What you'll learn"- Load the Customer Privacy API on the storefront
- Collect and register consent in your app
- Upgrade to the newest version of the Customer Privacy API.
Loading the Customer Privacy API
Anchor link to section titled "Loading 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
.
Collect and register consent
Anchor link to section titled "Collect and register consent"To record customer consent, use the setTrackingConsent
method:
The 4 supported signals are defined as:
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.Sale_of_data
: Opts the customer out of data sharing / sales.
The GPC signal is automatically collected by the Customer Privacy API and cannot be set through setTrackingConsent
.
See the Shopify Cookie Policy for the full list of cookies used by Shopify.
You can set one or more consent signals at once:
Check consent
Anchor link to section titled "Check consent"You can check the current users' consent at any time by calling the currentVisitorConsent
method:
'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.
Check if a consent banner should be displayed
Anchor link to section titled "Check if a consent banner should be displayed"Check if a cookie consent banner should be displayed (via visitor IP address):
This is true
if consent isn't already set and the visitor is in a region showing consent.
Check if an opt out is required for data sale / sharing
Anchor link to section titled "Check if an opt out is required for data sale / sharing"Check if the visitor is in a region showing data sale opt outs.
This is true
if the visitor is from a region that requires data sale opt-outs.
Regions showing consent banners
Anchor link to section titled "Regions showing consent banners"When the consent banner is enabled from the Shopify Privacy & Compliance app it renders in the following regions:
European Economic Area (EEA): Austria, Belgium, Bulgaria, Croatia, Czech Republic, Denmark, Estonia, Finland, France, Germany, Greece, Hungary, Iceland, Ireland, Italy, Latvia, Liechtenstein, Lithuania, Luxembourg, Malta, Netherlands, Norway, Poland, Portugal, Republic of Cyprus, Romania, Slovakia, Slovenia, Spain, and Sweden
United Kingdom
If you're using an app other than than the Shopify Privacy & Compliance app, then contact the app's developer to understand where the consent banner is rendered.
Regions showing data sale opt out
Anchor link to section titled "Regions showing data sale opt out"When the data sale opt out page is enabled, links are shown to visitors from the following US states:
- California
- Virginia
- Connecticut
- Colorado
The Global Privacy Control (GPC) will be honored in accordance with US state laws.
If you're using an app other than than the Shopify Privacy & Compliance app, then contact the app's developer to understand where the the data sales opt outs information is rendered.
Verify data processing permission
Anchor link to section titled "Verify data processing permission"You can use the Customer Privacy API to check if you are allowed to process data for “non-essential” purposes. There are two ways to check for permission:
- Call the API to get the current permissions, or
- Use an event listener to respond to consent chan.
Call the API
Anchor link to section titled "Call the API"The Customer Privacy API offers 4 methods to check if data can be processed for non-essential purposes:
These methods return either true
or false
and are defined as:
preferencesProcessingAllowed
: Permission to remember preferences such as language, currency, size, etc.analyticsProcessingAllowed
: Permission to store information about how the storefront was used and interactions made on the storefront.firstPartyMarketingAllowed
: Permission to collect and process data for marketing, attribution and targeted advertising from the merchant.thirdPartyMarketingAllowed
: Permission to collect and share data with third parties to perform marketing, attribution and targeted advertising.
Use an event listener
Anchor link to section titled "Use an event listener"The Customer Privacy API publishes document events when consent change. Use this listener to react to changes in consent over time.
Updates are published only when consent changes, not when the listener is added.
Upgrading the Customer Privacy API
Anchor link to section titled "Upgrading the Customer Privacy API"The Customer Privacy API is backwards compatible.
Collecting Consent
Anchor link to section titled "Collecting Consent"You must decide how to map the consent you collect in your banner to the four consent signals used by Shopify. The following snippet shows the backwards compatibility between the legacy Boolean argument and the new granular argument.
Migrating consent banners
Anchor link to section titled "Migrating consent banners"Two methods have been renamed to generalize their use:
Migrating data processing permission checks
Anchor link to section titled "Migrating data processing permission checks"Data processing has been separated into granular use. You must decide how to map your processing needs to one of the data processing purposes provided by Shopify.
userCanBeTracked
and userDataCanBeSold
use the following consent signals to determine if consent has been granted:
userCanBeTracked
: Analytics and marketing both must be accepted (when required)userDataCanBeSold
: Sale of data must not be rejected
Legacy documentation
Anchor link to section titled "Legacy documentation"shouldShowGDPRBanner(): boolean
Anchor link to section titled "shouldShowGDPRBanner(): boolean"You can use this method to determine if you should show a GDPR banner.
Request data
Anchor link to section titled "Request data"window.Shopify.customerPrivacy.shouldShowGDPRBanner();
This method returns a boolean value that indicates if you should show a GDPR banner.
The response aggregates the visitor’s location, the app user's preference, and whether the visitor has already provided a consent value in the past year.
Visitor consent provided in past year | Visitor in EU | App user limits tracking for customers in Europe | Boolean value |
---|---|---|---|
Not applicable | Not applicable | ✘ | false |
✘ | ✔ | ✔ | true |
✘ | ✘ | ✔ | false |
✔ | ✔ | ✔ | false |
✔ | ✘ | ✔ | false |
setTrackingConsent(consent: boolean, callback: function)
Anchor link to section titled "setTrackingConsent(consent: boolean, callback: function)"You can use this method to set a buyer's response to a tracking consent request.
Request data
Anchor link to section titled "Request data"window.Shopify.customerPrivacy.setTrackingConsent(consent: boolean, callback: function);
Request parameters:
Name | Type | Description |
---|---|---|
consent |
boolean | Indicates the buyer's response to the tracking consent request. You can obtain the response using a banner UI element or other similar mechanism. If set to true , then the API returns a custom event called trackingConsentAccepted . If set to false , then no custom event is returned but the callback function is still executed. |
callback |
function | A function that executes after the API has set tracking consent. You can use this function to hide the UI banner element or execute a similar task. |
Example request:
The following example request shows a JavaScript function that sets consent
to true
and executes another function to hide the banner. For a complete implementation, refer to Create a cookie compliance banner for your online store.
The API executes the callback function and optionally emits a custom event called trackingConsentAccepted
.
Example response:
A successful request returns an empty object:
If there is an error with the request, then an error object is returned:
Visitor tracking
Anchor link to section titled "Visitor tracking"You can use the Customer Privacy API to check if customers have consented to be tracked and if app users have decided to disallow the sale of visitor data. Your implementation must include a loading pattern to ensure that the API is available. For visitor tracking consent, you should implement a mechanism for listening to consent collection events that can fire asynchronously on the page, to ensure that you don't miss any tracking opportunities.
You can use the following methods for consent collection:
userCanBeTracked(): boolean
- Covers the scenario of tracking a visitor (GDPR).userDataCanBeSold(): boolean
- Covers the scenario of selling visitor data (CCPA).
If userCanBeTracked
is set to false
, then the following behaviour must be observed:
- No persistent, non-essential cookies should be set
- No data should be emitted to third-party platforms
If userDataCanBeSold
is set to false
, then the following behaviour must be observed:
- Data can be emitted (if tracking isn't blocked)
- Data can't be sold to third-parties
If the Customer Privacy API isn't available, then tracking and data emission can proceed. All methods should be preceded with a check that the API is available before checking that tracking or sale of data is blocked.
Example API check:
if (!window.Shopify.customerPrivacy || window.Shopify.customerPrivacy.userCanBeTracked()) { startTracking() }
userCanBeTracked(): boolean
Anchor link to section titled "userCanBeTracked(): boolean"You can use this method to return whether the storefront visitor has consented to be tracked.
Request data
Anchor link to section titled "Request data"window.Shopify.customerPrivacy.userCanBeTracked();
The API returns a boolean value that indicates whether a user can be tracked.
The response aggregates the visitor’s consent and location, as well as the app user's preference.
Visitor consent | Visitor in EU | App user limits tracking for customers in Europe | Boolean value |
---|---|---|---|
Not applicable | Not applicable | ✘ | true |
✔ | ✔ | ✔ | true |
✔ | ✘ | ✔ | true |
✘ | ✔ | ✔ | false |
✘ | ✘ | ✔ | false |
Undeclared | ✔ | ✔ | false |
Undeclared | ✘ | ✔ | true |
Listening for consent collection
Anchor link to section titled "Listening for consent collection"A trackingConsentAccepted
event fires when positive tracking consent is collected on the page.
By listening for this event and calling your custom start tracking method when it fires, you avoid any possible data loss due to missing asynchronous consent collection.
userDataCanBeSold(): boolean
Anchor link to section titled "userDataCanBeSold(): boolean"Use this method to determine if the app user has explicitly disallowed selling data to third parties for visitors located in California or Virginia. This enables compliance with the CCPA and VCDPA.
Request Data
Anchor link to section titled "Request Data"window.Shopify.customerPrivacy.userDataCanBeSold();
The API returns a Boolean value indicating whether data can be sold to third parties for visitors located in California (CA) or Virginia (VA).
The API response aggregates the app user's preferences and the visitor’s location. However, you can't use the API to enable visitors to opt-out of the sale of their data.
User consent | Visitor in CA or VA | App user limits the third-party sale of CA or VA customers’ data | Boolean value |
---|---|---|---|
Not applicable | ✔ | ✔ | false |
Not applicable | ✘ | ✔ | true |
Not applicable | ✔ | ✘ | true |
Not applicable | ✘ | ✘ | true |