WP Consent API integration

Beautiful Cookie Banner works with the WP Consent API: it passes the visitor’s consent choice to other WordPress plugins that read it, such as Google Site Kit or WooCommerce. This feature is part of the free plugin.

The WP Consent API is a free plugin by the WordPress community. It gives all plugins one shared way to ask “may I set cookies for this purpose?”. It does not show a banner and does not block anything itself; it only passes the consent from a cookie banner to other plugins.

It knows five consent categories:

CategoryUsed for
functionalStorage that is strictly necessary for the site or a service the visitor requested
preferencesStorage of preferences, e.g. a chosen language
statisticsAnalytics
statistics-anonymousAnonymous, first-party analytics
marketingAdvertising and tracking across websites

Which plugins read it

You need the WP Consent API only if you use a plugin that reads it. The plugin page lists these “Consent Requiring Plugins”, among others:

  • AddToAny
  • Burst Statistics
  • Google Site Kit
  • HandL UTM Grabber
  • Pixel Manager for WooCommerce (Beautiful Cookie Banner also has a direct integration)
  • WooCommerce
  • WP Statistics

The current list is on the WP Consent API plugin page. Beautiful Cookie Banner is listed there as a consent management plugin.

  1. Install and activate the WP Consent API plugin from WordPress.org.
  2. Go to Settings > Cookie Consent Banner > Consent APIs > WordPress Consent API.
  3. For each WP Consent API category, choose the banner categories that allow it. A WP Consent API category is set to “allow” as soon as one of its banner categories is allowed; with no mapping it stays “deny”.
  4. Save, and clear the cache of your caching plugin.
WP Consent API Plugin mapping
Example mapping for a banner with the categories “tech” and “marketing”.

Important: complete the mapping. Without it, every category stays “deny”, and the supporting plugins act as if the visitor had refused.

To choose the right mapping, check the documentation of the plugins that read the API: they decide what they do for each category.

Example

You map the banner category “marketing” to the WP Consent API category “marketing”. When a visitor allows “marketing” in the banner, the WP Consent API reports marketing as allowed, and e.g. WooCommerce starts recording order attribution.

How to check that it works

Open your site in a private browser window and open the console of the developer tools. Then:

  1. Check the stored choice per category. The WP Consent API writes one cookie per category, e.g. wp_consent_marketing with the value allow or deny. You see them in the Application (Chrome) or Storage (Firefox) tab.
  2. Ask the API directly:
['functional', 'preferences', 'statistics', 'statistics-anonymous', 'marketing']
  .map(c => c + ': ' + wp_has_consent(c))

Before the visitor chooses, only the categories mapped to a “default checked” banner category return true. Allow a category in the banner and run the command again: the mapped categories now return true, without a page reload.