Consent Cookie

OptinStack stores the visitor's current consent state in a first-party cookie named optinstack.

The runtime reads this cookie during initialization to decide whether a visitor has already made a consent choice, which categories are granted, and whether the banner should appear again.

Cookie format

The cookie value is URL-encoded JSON. After decoding, it has this shape:

{
  "id": "f3f5cc3b-9c49-4f7b-9d30-4f5a5f6c2a10",
  "choices": {
    "necessary": true,
    "analytics": false,
    "marketing": false,
    "preferences": false
  },
  "timestamp": 1760000000000,
  "configVersion": "site-config-version"
}

The cookie is written with path=/ and expires based on the consent duration configured in the dashboard.

Cross-subdomain sharing

When cross-domain consent sharing is enabled for a project on Business or Enterprise, OptinStack writes the consent cookie for the registrable site domain. For example, a site configured for example.com can share the same optinstack cookie across:

• example.com
• www.example.com
• app.example.com
• docs.example.com

That means a visitor who accepts consent on www.example.com can carry the same consent state to app.example.com, as long as both pages are under the same registrable domain and use the same OptinStack project configuration.

For sharing to work reliably, every subdomain should install the same project snippet and be served over HTTPS when secure cookies are enabled. Sharing is not available for localhost, preview hosts on unrelated domains, or separate production domains.

Browser cookies cannot be shared across unrelated domains, such as example.com and example.net. For that case, each domain needs its own consent state.

Preview or staging hostnames from Webflow, Framer, and similar platforms usually live on a different registrable domain than your production site. They can be used to test banner behavior, but browser consent state will not carry from that preview hostname to your production hostname.

Reading consent from a subdomain

If another page on a subdomain needs to check consent before the runtime API is available, it can read the optinstack cookie directly:

function readOptinStackConsent() {
  const value = document.cookie
    .split('; ')
    .find((part) => part.startsWith('optinstack='))
    ?.split('=')
    .slice(1)
    .join('=');

  if (!value) return null;

  try {
    return JSON.parse(decodeURIComponent(value));
  } catch {
    return null;
  }
}

const consent = readOptinStackConsent();

if (consent?.choices.analytics) {
  // Analytics consent is granted.
}

When the OptinStack runtime is loaded, prefer the JavaScript API because it validates the stored consent, handles expiry and configuration changes, and keeps subscribers updated:

await window.OptinStack.ready;

if (window.OptinStack.analytics) {
  // Analytics consent is granted.
}

Renewal and configuration changes

The runtime may ignore or replace the stored cookie when:

• The cookie has expired based on your configured consent duration.
• Consent renewal is enabled and the saved choice is older than the allowed duration.
• The published configuration version changed and visitors must be prompted again.
• The visitor chooses to change consent through the banner, preferences dialog, or JavaScript API.

Use window.OptinStack.renew() when you intentionally want to clear stored consent and re-prompt the visitor.