Shopify Consent Mode: What the Bridge Does
The CookieBeam Shopify consent bridge is the component that translates your cookie banner's accept or reject decision into a call to Shopify's Customer Privacy API, the platform's built-in consent layer at window.Shopify.customerPrivacy. When a visitor makes a consent choice, the bridge calls setTrackingConsent with three boolean fields: analytics (from your banner's analytics category), marketing (from marketing), and preferences (mirrors analytics). These values are derived from the Consent Mode v2 state your banner already computed for Google, so Shopify's privacy controls stay in sync without manual wiring. The bridge fires on every consent change: initial acceptance, rejection, and withdrawal. Unlike the Meta and Adobe bridges, it has no retry queue, so Shopify's runtime must be loaded when the consent event fires. For how the Customer Privacy API itself works, see the Shopify Customer Privacy API guide.
TL;DR
CookieBeam calls Shopify's setTrackingConsent whenever consent changes. Analytics category maps to analytics: true and preferences: true. Marketing category maps to marketing: true. The bridge has no queue: if Shopify's runtime hasn't loaded when the consent event fires, the signal is silently dropped. On Shopify stores this rarely matters because Shopify's JS loads early in the page lifecycle.
Which Shopify consent guide do you need?
- This guide: how CookieBeam's bridge maps consent to Shopify's
setTrackingConsent. - Shopify Customer Privacy API: how Shopify's built-in consent layer works and when to add a CMP.
- Server-side tagging on Shopify: consent handling for server-side setups.
How Shopify's Customer Privacy API Works
Shopify's Customer Privacy API is the platform's built-in consent layer. It lives at window.Shopify.customerPrivacy and exposes setTrackingConsent, which third-party Shopify apps and Shopify's own tracking pixels check before storing data or firing marketing tags. The API takes three boolean fields:
- analytics controls whether session recording, heatmaps, and analytics tools may set cookies
- marketing controls whether advertising pixels and remarketing tags may fire
- preferences controls whether the store may save non-essential preference data like recently viewed products or wish lists
When all three are false, compliant apps stop setting non-essential cookies. The API is separate from Google Consent Mode v2: Google tags read dataLayer consent commands, while Shopify apps read the Customer Privacy API. CookieBeam signals both from the same banner decision, so you don't maintain two parallel consent systems. For the broader Shopify setup, see Cookie Consent on Shopify: Customer Privacy API Guide.
How CookieBeam Maps Banner Categories to Shopify Consent
The bridge reads the consent mode state that CookieBeam computes from your banner categories. Two consent mode keys drive the three Shopify fields. analytics_storage (set to granted when a visitor accepts your analytics category) maps to both the analytics and preferences fields. ad_storage (set to granted when a visitor accepts marketing) maps to the marketing field. The bridge also treats ad_user_data and ad_personalization as contributing to the marketing signal: if any of the three ad-related consent mode keys is granted, marketing becomes true.
One detail worth noting: CookieBeam's bridge always sets preferences to the same value as analytics. There's no separate banner category for Shopify preferences. In practice, this works well because Shopify's preference data (recently viewed, currency selection) is functionally closer to analytics than to marketing.
| Banner Category | Consent Mode Key | Shopify API Field | Granted | Denied |
|---|---|---|---|---|
| Analytics | analytics_storage | analytics | true | false |
| Analytics | analytics_storage | preferences | true | false |
| Marketing | ad_storage / ad_user_data / ad_personalization | marketing | true | false |
Before Consent, After Accept, After Reject
Before the visitor decides: The bridge does not call setTrackingConsent. No default-denied signal is pushed to the Customer Privacy API. The protection here comes from two things: Shopify's own default behavior (which is conservative on stores using Shopify Markets) and your banner blocking marketing and analytics scripts from loading until consent. The absence of a bridge call before consent doesn't create a gap because compliant apps should already be in a denied-by-default state.
After accept: CookieBeam dispatches a cookiebeam:consentUpdate window event. The bridge reads the event's consent mode state and calls setTrackingConsent. If the visitor accepted analytics but not marketing, the API receives { analytics: true, marketing: false, preferences: true }. If they accepted both, all three are true.
After reject: The same event fires, but all consent mode keys are denied. The bridge calls setTrackingConsent({ analytics: false, marketing: false, preferences: false }).
On withdrawal: When a visitor reopens the preferences panel and changes their choice, the bridge fires again with the updated state. Shopify apps see the new booleans immediately.
Returning visitors: On later page views, the runtime re-announces the stored explicit choice as cookiebeam:consentRestored, and the bridge re-applies setTrackingConsent with the stored state, so apps see the right values from the start of the session. A consent change on the current page fires cookiebeam:consentUpdate. This restatement ships with the runtime release that includes the vendor bridge fix. Machine-written defaults (such as US opt-out auto-grants) are not restated.
How to Verify the Shopify Bridge in Your Browser
Open DevTools on your Shopify store
Load your store in Chrome or Firefox, open DevTools (F12), and go to the Console tab.
Check the Customer Privacy API exists
Type window.Shopify.customerPrivacy in the console. You should see the API object. If it's undefined, the Shopify runtime hasn't loaded yet or you're not on a Shopify store.
Dismiss or reject the cookie banner
Close the banner without accepting. Then check the API state by calling window.Shopify.customerPrivacy.currentVisitorConsent(). All three fields should show a non-granted state.
Accept all categories and check again
Accept the banner, then call window.Shopify.customerPrivacy.currentVisitorConsent() again. The fields should now reflect your acceptance: analytics, marketing, and preferences matching what you accepted.
Watch the network for cookie changes
Switch to the Application tab and look at Cookies. Marketing cookies (from ad pixels) should appear only after you accepted the marketing category. Analytics cookies should appear only after accepting analytics.
Test withdrawal
Reopen the cookie preferences panel (if your banner has one), change your choice, and verify that currentVisitorConsent() updates accordingly.
Common Mistakes with Shopify Consent Mode
Loading order issues. The bridge calls setTrackingConsent only when Shopify's Customer Privacy API is available. Unlike the Meta or Adobe bridges, CookieBeam's Shopify bridge has no retry queue. If a custom theme or app delays Shopify's runtime, the first consent signal could be lost. In practice this is rare on standard Shopify themes, but custom headless storefronts using the Storefront API should verify the timing.
Assuming preferences is a separate category. CookieBeam maps both analytics and preferences to the analytics consent mode key. If you want a separate preferences toggle in your banner, be aware that the Shopify bridge won't distinguish it from analytics. Both follow the same consent state.
Not enabling the bridge. The Shopify bridge is enabled by default in CookieBeam's vendor consent signals settings. But if someone disabled it (or disabled all vendor signals), no call reaches the Customer Privacy API. Check your banner settings under vendor consent signals to confirm Shopify is active.
For the full Shopify consent setup including GDPR and CCPA configuration, see Shopify Cookie Consent: GDPR and CCPA Setup Guide. For e-commerce consent patterns more broadly, see E-Commerce Cookie Consent.
Frequently Asked Questions
Does CookieBeam replace Shopify's built-in cookie banner?
Yes. CookieBeam replaces Shopify's native cookie banner with a more configurable one, while still communicating consent decisions to Shopify's Customer Privacy API through the bridge. You don't need both running.
What happens if a Shopify app ignores the Customer Privacy API?
Some older or poorly built apps don't check the Customer Privacy API and set cookies regardless of consent state. The bridge can only signal consent; it can't force apps to obey. Run a cookie scan to identify non-compliant apps and consider replacing them.
Does the Shopify bridge work on headless Shopify storefronts?
Only if the headless frontend loads Shopify's Customer Privacy API (window.Shopify.customerPrivacy). Hydrogen storefronts and custom Storefront API builds often skip this API, in which case the bridge has nothing to call. The consent mode signals for Google and other vendors still work normally.
Can I control Shopify's preferences consent separately from analytics?
Not through this bridge. CookieBeam maps both the analytics and preferences fields to the analytics consent mode key. They always have the same value. If your store needs independent preferences control, you'd need custom JavaScript alongside the bridge.
Why doesn't the bridge send a denied signal on page load before consent?
The bridge fires on the cookiebeam:consentUpdate event, which only dispatches when a consent decision exists. Before the visitor chooses, Shopify's own default state applies. On stores with Shopify Markets enabled, the Customer Privacy API defaults to a conservative state in regulated regions.
CookieBeam's Shopify bridge turns your single cookie banner decision into the API call Shopify apps expect. Enable it in your banner's vendor consent signals settings, verify it with the steps above, and your store's third-party apps will respect the same consent choice as your Google and Meta tags. For server-side tagging on Shopify, see the server-side tagging consent guide. For all vendor bridges, see the consent mode integrations overview.