Skip to content

Storefront analytics consent handoff

Use this contract to report a storefront's analytics choice for one ordinary CART / ONE_TIME hosted checkout. It is independent of your framework or consent-management platform (CMP). Enforcement covers the platform-owned hosted Google Analytics integration only. You remain responsible for your storefront tags, CMP, consent capture, disclosures, and public-document handoff. Marketing/newsletter consent and payment authorization are separate.

Platform source status — 22 October 2026: the public API, hosted consent controller, event handling and adoption UI have landed on staging. The comparison record pins S4/S5/S6, the entry-event correction and the remaining gates. HOSTED_ADOPTED_ANALYTICS_ENABLED and HOSTED_CONSENT_POLLING_ENABLED are both false; API adoption availability defaults closed. No deployed setting was inspected for this comparison. Implemented source is not Production availability, tenant adoption or browser/network acceptance. Tenant runtime remains UNVERIFIED by this comparison. Existing storefront GA4 and never-adopted hosted analytics have separate behavior and authority; these dormant gates do not establish that either is off. Follow the onboarding checklist before any separately authorized adoption.

Choice and lifetime

Wire valueMeaning
grantedAn affirmative analytics choice collected by the storefront; usable only within its original cutoff and all remaining configuration, freshness, host, surface, and activation gates.
deniedRefusal or withdrawal. Known denial survives lapse.
unknownNo usable choice. Omission, malformed input, an unusable read, or missing evidence never grants.

A malformed handoff can be rejected; it is not an accepted unknown record. Unavailable analytics consent must leave commerce available. Neither a Google cookie, account login, geography, linker, newsletter choice nor measurement ID proves a grant.

The initial handoff records one tenant/environment/original-session snapshot. The platform freezes the checkout's expiry at acceptance as originalCutoffAt. Repricing, activity, retries, reload, re-entry, and updates cannot move it. A paid transition alone is not withdrawal. The current reader reports a stored grant as unknown after cutoff, while retaining the original cutoff and ordered summary; a known denial stays denied.

A successor checkout needs its own fresh handoff, secret, and retry key. Reasserting a still-valid explicit storefront choice need not require another banner click, but copying the predecessor's hosted grant is insufficient. Carry known refusal explicitly as state: "denied", inheritedDenial: true; that flag is invalid with any other state. No predecessor lookup or automatic cross-device consent system is supplied, and no preference center is promised.

Browser-local recovery scope and limits

Product planning amendment — 3 November 2026: the following exact P1–P8 clauses apply to conforming storefront integrations relying on the admitted browser-local recovery mechanism, not only one tenant. Product selected A subject to its conditions; the conditional P6 heading below preserves the selected text. Product source and exact clauses and independent planning validation record that scope. DR-5301-03 is VALIDATED for planning, noncanonical pending required incorporation and the operator-held completion receipt. DR-5301-01/-02 remain conditional and unqualified. This is a guarantee boundary, not a delivered browser adapter, runtime acceptance, or a change to the source/readiness status above. The API examples below remain storage-adapter examples; they do not implement or qualify the browser-local mechanism.

The historical P1–P8 text below is preserved exactly. The 11 November first-rollout amendment changes P2/P5 availability only for the demonstrated recovery observations.

P1 — Narrow excluded history. The browser-local consent currentness/recovery guarantee excludes an external restoration or rollback of a complete persistent browser-profile snapshot that coherently replaces all relevant existing preference/choice-time bridge, custody-cookie, journal/intent-generation/Deny-fence state and applicable local denial carriers with an earlier mutually consistent image, concealing a later genuine choice. Examples are external profile/backup replacement or an operating-system/profile recovery that actually rewinds those persistent records together. The mechanism does not claim to detect that otherwise indistinguishable history. This is a guarantee boundary, not an application instruction to grant on a “restored” flag.

P2 — Normal browser continuity stays supported. Ordinary reload, re-entry, browser restart using current retained storage, focus/visibility return, back/forward or BFCache return, reconstructed callers and cooperating same-origin/partition tabs remain in scope, with all required current-state checks and ordering before positive use/resumption. Closing/reopening a tab, ordinary navigation, a crash or release of a browser lock is not by itself the P1 exclusion. A supported flow is not reclassified as profile rollback merely because a proof fails.

P3 — Known Deny and storage failures remain failclosed. Immediate local suppression, newer-Deny fencing, current-intent checks, monotonic matching-result handling and F1's prompt loaded-tag stop remain required. Missing, blocked, malformed, expired, mismatched, partly lost or failed-readback storage remains unavailable/non-granting under the existing rules; none is excused by P1 or treated as fresh initialization. A live cooperating context retaining newer Deny/currentness evidence must honor it. Stale application writes, late provider/cookie replies, app-created partial restores and incorrect merges remain defects, not excluded external history.

P4 — Acknowledged withdrawals remain authoritative. Every durable platform-accepted withdrawal remains effective for each explicitly addressed tenant/environment/session authority, including later entries and reconstructed callers. A restored historical Allow, receipt, replay, local counter, preparation or late reply cannot reverse that accepted fact or bypass the current authoritative check. A same-scope current read returning Deny is honored. Only an otherwise permitted, demonstrably genuine newer affirmative choice can re-grant under the existing revision/generation and original-cutoff rules; the exclusion itself supplies no such choice. This does not weaken platform server-recovery/accepted-revision reconciliation or #4283.

P5 — New checkouts retain their normal qualification. Every genuinely new/successor checkout still requires the separately qualified original context and a fresh, currently valid storefront signal; copying an old hosted grant/receipt is insufficient. No lost original can be reminted/reconstructed from absence, and there is no cross-session identity lookup. Reassertion of a still-valid explicit storefront choice still need not require another banner click; no new click requirement or journey reduction is introduced. Under the specific unobservable P1 history, the integration cannot guarantee that the restored genuine older preference is still the shopper's latest origin-wide choice. That residual—not a positive-send bypass—is what this amendment discloses.

P6 — Residual risk accepted only if Product selects A. After an excluded coherent rollback, an older real Allow can appear current after a later genuine Deny has disappeared locally. Where the newer Deny never reached the platform, or was accepted only for another addressed authority not recoverably represented by the restored state, the ordinary protocol may use the restored choice for a separately otherwise-eligible new handoff. This is not origin-wide latest-choice protection. A previously acknowledged withdrawal on its addressed checkout is not undone; the platform does not infer a universal ban for every future checkout by hidden identity lookup. The integration/disclosure must not promise more. If the desired meaning is “an acknowledged Deny universally governs every future new checkout even after all origin evidence is rolled back,” A does not provide that guarantee and must not be represented as doing so.

P7 — Other accepted limits and authorities stay fixed. Preserve exact capability/reference/operation/key/body/actual choice time, finite D6, IH-1, all admitted caller coverage, original-cutoff nonextension, suppression for unknown/denied/unusable evidence, analytics-independent commerce, bounded cleanup and the original provider/session delivery limits. The two-lifetime DR-5301-02 inventory, fields/access/copies/disposal permission is unchanged. No new marker, state, store/API, identity, recipient/copy, lifetime, crypto or operational control is admitted. F-C's proposed service/lease/event/I3 changes remain separate and unaccepted; all currently accepted 30-second, inactivity, focus and configuration guarantees remain in force. Platform server backup/restore I9/#4283, tenant policy/adoption/enable controls and existing Global/privacy/controller gates remain separate.

P8 — Truthful evidence and disclosure. Document P1–P6 as a scoped limitation for conforming storefront integrations that rely on the admitted browser-local mechanism, not an EKGIS-only hidden exception. Do not claim universal rollback safety, detectability, legal clearance, complete measurement, delivered withdrawal or runtime readiness. If known unusable or inconsistent state is observed, existing failclosed behavior applies. Selection does not assert the remaining supported mechanism works.

The additional onboarding mapping keeps supported-flow proof and disclosure work explicit. N01's synchronous choice/time bridge race remains an architectural proof obligation: immediate local denial and prompt loaded-tag stop cannot wait for asynchronous storage, locks, preparation or provider work. N02's public-contract/publication and actual browser/native/provider acceptance remain separate. This amendment supplies no new store, API, marker, lifetime or operational permission, and does not resolve F-C, the existing thirty-second/configuration guarantees, I9/#4283, or #5261.

First-rollout recovery availability and prompts

Planned qualification — 11 November 2026: DR-5301-04 selects the following availability and shopper behavior for first-rollout qualification of the browser-local integration. Product selection, shopper clarification and incorporated Product source record the scope validated by Round 4. Final canonical completion remains operator-held. The recovery mechanism remains unqualified; this is not a claim of deployed behavior or tenant availability.

When a failed-save/competing-tab recovery or ordinary restart cannot distinguish a current Allow from the demonstrated newer-Deny history, keep both unconfirmed histories off: no GA4 tag/event, linker use or hosted grant from the recovering caller. An older readable Allow is insufficient on its own. This accepts missing measurement on the otherwise ordinary arm too, including storefront-only measurement after an unverified failed save and post-restart measurement from an older saved Allow. Ordinary restart remains outside P1's external complete-profile-rollback exclusion. That exclusion and the separate earlier two-case qualification waiver retain their own scopes. This concession does not extend to unrelated histories or all storefront mechanisms; further availability reductions return to Product.

Current choiceEligible storefront surfaceHosted cartonium checkout
Confirmed AllowHonor the proved current choice, including a proved later Allow, without another prompt or click. Independently proved page-only Allow is limited to analytics in that storefront document.An eligible confirmed persistent Allow may use the existing handoff. Page-only Allow supplies zero linker or hosted eligibility.
Confirmed DeclineKeep GA4 off without another automatic prompt. Keep the existing analytics preferences accessible for a voluntary change or check.Checkout continues with analytics off.
Unconfirmed choiceOffer the existing optional analytics prompt again and keep GA4 and linker use off. A new Allow still needs applicable currentness and persistence evidence; failed confirmation stays off with truthful feedback. Privacy-sensitive routes remain silent.Checkout continues with analytics off and no additional prompt. Uncertainty or no answer supplies no grant.

A prompt or click supplies no currentness, retirement or withdrawal proof. Fresh Allow cannot silently clear an unrelated Deny, remint old hosted authority or replay skipped events. Independently proved current Allow stays supported; the selected concession does not authorize disabling it everywhere. Consent controls remain optional for shopping.

Two proofs remain open: currentness at the point of every positive use and bounded exact retirement that prevents stale writers from restoring old evidence. A previously proved Allow alone does not establish currentness after an intervening invisible Deny; that failure is outside this selected concession. Keeping all records indefinitely, or deleting them because a timeout passed or evidence is absent, does not prove safe retirement. The onboarding checks retain these obligations separately from fixture results.

Preserve immediate local Deny and prompt loaded-tag navigation after the bounded synchronous capture attempt, truthful pending/failed delivery, exact addressed operation/capability/reference/key/body and genuine choice time, original cutoff/revision, D6, IH-1 and admitted custody limits. Active hosted analytics must stop within 30 seconds of durable platform acceptance of an addressed withdrawal, with immediate action on received Deny and suppression on failed current-state checks or inactive resume. This is not a deadline from an unacknowledged storefront click. No new storage, identifier, recipient, copy, lifetime, checkout consent UI, provider setting or activation is admitted.

Landed public API

Paths below include /api/v1. Use the API origin for the intended environment from Environments. The opaque original checkout reference is the existing token credential. These public routes require neither a merchant bearer token nor x-organization-slug; updates additionally require the consent capability. A browser origin must satisfy the platform's existing CORS admission. Do not add consent state or the update secret to the hosted checkout URL, query, linker, or return URL.

Method and pathInput / result
POST /api/v1/public/checkout/sessions/{token}/analytics-consentx-idempotency-key; body state, assertedAt, updateCapability, optional inheritedDenial; 201 handoff result.
POST /api/v1/public/checkout/sessions/{token}/analytics-consent/updatesx-idempotency-key, x-consent-update-capability; body state, assertedAt, expectedRevision; 200 decision, including refused decisions.
GET /api/v1/public/checkout/sessions/{token}/analytics-consentPrivate current state and configuration; no update secret.
GET /api/v1/public/checkout/sessions/{token}/analytics-consent/cleanupPrivate minimum cleanup obligation; no update secret.

Use the current OpenAPI reference for full schemas. assertedAt is the actual storefront choice time, an ISO-8601 string with a timezone offset. Never replace it with retry time. expectedRevision is the current positive integer revision. Idempotency keys are nonblank and at most 200 characters. Keep the same key and identical body for a transport retry; new requests need new keys.

Generate and persist before sending

Generate an independent secret for each checkout: literal n, followed by at least 32 CSPRNG bytes encoded as base64url (43 characters) or hex (64). The API validates format, not randomness. The platform stores a hash, never returns the secret, and cannot recover it. Do not use the checkout token, customer identity, predictable input, or padding as the random material.

This JavaScript is an integration example, not a storage SDK. privateStore is your protected, tenant/environment/session-scoped adapter: save must durably finish before resolving; load must return the same pending operation on retry. Protect it from unrelated users, scripts, telemetry and logs. Prefer server custody when your storefront supports it. A browser implementation must explicitly address script access and loss/re-entry; this example does not prescribe a browser-storage key or a new retention permission. Do not forward the update secret to hosted checkout. Preserve it only for the necessary update/retry lifecycle, and define safe disposal and lost-secret handling.

// Inputs are placeholders/adapters supplied by your storefront.
// apiBase example: "https://api.example.invalid/api/v1" (never a live target).
function consentUrl(apiBase, checkoutToken, suffix = "") {
  return `${apiBase}/public/checkout/sessions/${encodeURIComponent(checkoutToken)}/analytics-consent${suffix}`;
}
 
async function prepareHandoff(privateStore, scope, choice) {
  const existing = await privateStore.load(scope);
  if (existing) return existing; // Reuse the original secret, key, and body.
  const bytes = crypto.getRandomValues(new Uint8Array(32));
  const secret = "n" + Array.from(bytes, b => b.toString(16).padStart(2, "0")).join("");
  const operation = {
    key: crypto.randomUUID(),
    body: {
      state: choice.state,
      assertedAt: choice.assertedAt,
      updateCapability: secret,
      ...(choice.inheritedDenial === true ? { inheritedDenial: true } : {}),
    },
  };
  await privateStore.save(scope, operation);
  return operation;
}
 
async function sendHandoff(apiBase, checkoutToken, operation) {
  const response = await fetch(consentUrl(apiBase, checkoutToken), {
    method: "POST",
    headers: { "Content-Type": "application/json", "x-idempotency-key": operation.key },
    body: JSON.stringify(operation.body),
    cache: "no-store", credentials: "omit", redirect: "error", referrerPolicy: "no-referrer",
  });
  if (response.status !== 201) return {
    delivery: "unacknowledged",
    status: response.status,
    retryable: response.status === 429 || (response.status >= 500 && response.status < 600),
  };
  return { delivery: "acknowledged", result: await response.json() };
}

Serialize preparation per scoped checkout so concurrent tabs/processes cannot create different initial secrets. If persistence fails, do not send. If sending times out or JSON cannot be read, keep the operation pending and retry with bounded backoff within the available seven-day replay window. For an HTTP failure, inspect status and retryable: only 429 or 5xx permits an automatic retry with backoff. Stop automatic retries on 400/404/409 and correct the cause; an expired receipt's 400 or a changed body's 409 cannot recover through repeated identical sends. Preserve the protected persisted operation for diagnosis; do not regenerate its secret or change its key/body merely to retry. Avoid tight retry loops, respect rate limits, and never log request URLs, headers, bodies or raw errors containing them. Commerce continues even when consent handoff fails. Once acknowledged, keep the capability separately from pending-operation state and process later choices through the update API.

The 201 result includes state, handoffAt, revision, grantGeneration, originalCutoffAt and updateCapabilityExpiresAt, not the capability. handoffAt dates evaluation of the returned state; it is not the durable acceptance timestamp or shopper choice time. A delayed response is not a fresh grant. Replays report the recorded acceptance without minting a secret or renewing either deadline; use the current reader before acting on state.

The capability expires 72 hours from first handoff acceptance, independently of the original grant cutoff. A new withdrawal can be accepted after cutoff while this capability remains valid. After capability expiry, a new withdrawal on that authority is impossible; null expiry means retired, never unlimited. The read/cleanup lifecycle can continue. Handoff retry receipts last at most seven days: identical retries are safe no-ops during that window; after receipt expiry, a second handoff is refused 400. A different secret/body under the same key is a 409 conflict. Neither window is permission to prolong grant use.

Withdraw and interpret the decision

Persist each update's retry key and exact body before sending, alongside the protected capability and existing scoped checkout reference. For example, pending.body can be the following schema-valid synthetic choice (the date must come from the real choice in an integration):

{
  "state": "denied",
  "assertedAt": "2026-09-28T12:11:00.000Z",
  "expectedRevision": 1
}
async function sendWithdrawal(apiBase, checkoutToken, capability, pending) {
  const unacknowledged = (retryable, status = null) => ({
    delivery: "unacknowledged", status, retryable,
    message: "We could not confirm your analytics consent change for this checkout.",
  });
  // Only the storefront holding the capability can know it is missing.
  if (typeof capability !== "string" || !capability.trim()) {
    return unacknowledged(false);
  }
  try {
    const response = await fetch(consentUrl(apiBase, checkoutToken, "/updates"), {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "x-idempotency-key": pending.key,
        "x-consent-update-capability": capability,
      },
      body: JSON.stringify(pending.body),
      cache: "no-store", credentials: "omit", redirect: "error", referrerPolicy: "no-referrer",
    });
    if (response.status !== 200) return unacknowledged(
      response.status === 429 || (response.status >= 500 && response.status < 600),
      response.status,
    );
    const result = await response.json();
    // Validate all four published fields before acknowledging. Null revision
    // belongs to an unusable-capability refusal, never an accepted decision.
    // An accepted replay can return granted, denied, or unknown effective state.
    const accepted = result !== null && typeof result === "object" && !Array.isArray(result)
      && result.outcome === "accepted"
      && typeof result.replayed === "boolean"
      && ["granted", "denied", "unknown"].includes(result.state)
      && Number.isFinite(result.revision) && result.revision >= 1;
    if (!accepted) {
      return { ...unacknowledged(false, 200), result };
    }
    return {
      delivery: "acknowledged", result,
      message: "The platform acknowledged this withdrawal request.",
    };
  } catch {
    // Network/body-read failures can hide a committed decision. Preserve the
    // operation for an identical bounded retry; never log the raw error.
    return unacknowledged(true);
  }
}

outcome: "accepted" acknowledges a durable decision; replayed: true reports the original decision, not a new acceptance time. It does not prove a browser has stopped or Google has received anything. A replay is not permission to overwrite a later current state. A timeout/lost reply is pending or failed delivery, even if the platform may have committed; recover through an identical retry within the available window. Do not tell the shopper withdrawal completed merely because they clicked or received a 2xx status.

Show the unacknowledged message visibly beside the storefront's existing, validated Privacy link. Do not substitute a success state, silently discard the failed intent, or invent a recovery link. Keep the original tenant/environment/checkout scope, choice time and pending key/body. Before applying any asynchronous result to the UI, confirm that both its scope and intent are still current; an older response must not replace a newer choice. Even an accepted replay acknowledges that request, not a new current choice: reconcile its returned current state separately. A missing/expired/retired capability is not recoverable or re-armable; a new checkout's fresh choice does not withdraw the old authority.

This reference-example copy follows the selected #4307 direction. That direction remains noncanonical and actual caller implementation and acceptance remain separate. The hosted /cookies notice has no capability and cannot know whether the storefront still holds it; it supplies generic information and the existing tenant Privacy link, not a withdrawal control.

Update outcome / HTTP failureRequired handling
supersededA newer choice outranks this intent, or unknown would erase denial. Do not rebase an old grant.
rejected_stale_revisionRe-read current state. Only a still-applicable explicit choice may be resubmitted with its original choice time, a current revision and a new key. Never silently upgrade an old grant over withdrawal.
rejected_not_newerAssertion is not strictly newer than the accepted choice; do not forge a later timestamp.
rejected_after_cutoffA grant cannot extend the original ceiling.
rejected_unknown_never_grantsNo usable explicit grant; keep analytics suppressed.
rejected_capability_unavailableWrong, expired or retired capability. Returned unknown / null revision is a non-disclosing sentinel, not proof of the stored choice; no secret recovery is provided.
400 / 404 / 409Validation failure, neutral unavailable reference, or key reused for a different request. None acknowledges this withdrawal. Correct the cause; never blindly regenerate the handoff secret.
429 / network failure / 5xxDelivery unacknowledged; bounded backoff and truthful pending/failure reporting. Admission is source-based before token resolution.

A demonstrably newer explicit affirmative choice may restore a grant only before the immutable cutoff and under valid authority. It advances the grant generation; it never resurrects work from an earlier generation or backfills events. Update receipts last at most seven days from the decision: the matching capability can replay its own unexpired receipt even after its 72-hour validity ends, but retirement clears that proof and prevents replay. The replay returns the original outcome alongside the current effective state and revision. Retry-receipt expiry does not reset revision, denial or cutoff.

Overlapping POSTs and uncertain delivery

Both the initial handoff and update route serialize decisions for the same tenant/environment/original checkout. An admitted identical request that reaches the same authority while the first transaction is pending waits for it; there is no separate transient "request still in flight" 409 protocol. Admission, infrastructure and transaction timeouts can still fail an attempt, so serialization is not a promise that every waiting HTTP request succeeds.

First attemptMeaning for an identical retry
Handoff commitsAuthority and its retry receipt commit together. While the receipt remains usable, the retry reports the existing acceptance without creating another authority or replacing the capability.
Update commitsAny authority transition and its decision receipt commit together. A usable receipt replays that decision without applying the update again; inspect outcome, not HTTP 200 alone.
Either transaction rolls backIts writes, including the receipt, roll back together. The retry is evaluated against the authority that remains and the applicable validity/ordering rules; success is not guaranteed.
A usable, unexpired receipt exists and the authenticated same-key request has a different digest409 is a conflict with that request identity, not a signal to wait for an in-flight copy. Backoff cannot make the changed request identical. Restore the original operation for recovery; handle a genuinely new choice separately.

Keep the same API environment, original checkout reference, operation, capability, idempotency key and body, including the genuine assertedAt and, for updates, expectedRevision. If the checkout already has handoff authority, changing the key or retrying after its receipt expires yields 400 for a second handoff. After an update receipt expires, the API evaluates the request under the current capability rules. By the end of the seven-day receipt window, the 72-hour capability has expired, so an otherwise valid request for that original checkout returns HTTP 200 with outcome: "rejected_capability_unavailable". Neither response acknowledges an earlier ambiguous attempt.

Aborting fetch, timing out a server route handler, closing a connection or releasing a local lease/lock proves neither remote completion nor rollback. The platform may commit after the caller has stopped waiting. There is no hard completion deadline that makes a later attempt safe merely because time passed. Keep the delivery unacknowledged and reconcile with the exact stored operation; do not mint a replacement secret or advance the choice timestamp to escape an uncertain result. A later 404 or transport failure also cannot prove that an earlier attempt rolled back. Local suppression and immediate Deny/navigation must not wait for that reconciliation.

A receipt establishes what happened to one request, not continuing permission to send analytics. Returned state is a projection, not a reservation against later writers or a guarantee of freshness on arrival. In particular, the update response has no evaluation timestamp or cutoff; use the timestamped current-state reader, respect its cutoff, and guard replies against newer local intent. An accepted historical grant must never overwrite a later Deny.

Server callers and source admission

A backend or server route handler can call these POSTs without a browser Origin header. Browser CORS admission is separate from server authentication and does not replace the checkout reference or update capability. The public API resolves the tenant/original checkout from the presented reference and the consent environment from its own runtime. Your backend must retain and validate its own tenant/environment/checkout association; adding a tenant header does not turn the token-only route into the independently host-bound hosted reader.

The existing source limiter runs before checkout resolution and is shared by the public consent reads and writes. Its current implementation uses a fixed 60-second window per warm API instance: at most 300 admitted requests per source, 2,048 tracked sources and 20,000 admitted requests total. An unresolved source uses a shared unknown bucket. These are source ceilings, not separate allowances per shopper, checkout, tenant or route. Backend callers sharing an egress address can consume the same bucket. Cold starts reset it and additional instances multiply the envelope; this is neither a tenant-wide budget nor a throughput guarantee. The separate polling-budget decisions remain open.

Source identity comes from Express req.ip with one trusted proxy hop, falling back to the socket address. That describes application configuration; the deployed proxy chain and header sanitization require separate verification. Do not assume that forwarding an arbitrary shopper IP from a tenant backend gives that shopper a supported separate allowance. No tenant-controlled forwarding-header contract or custom proxy arrangement is established here.

A source-admission 429 includes a positive integer Retry-After in seconds. Honor it before another attempt, retain the exact pending operation, and use bounded backoff rather than parallel retry loops. A 429 does not reveal whether the checkout reference is valid or settle an earlier ambiguous attempt. If a POST returns 5xx or its response is lost, keep delivery unacknowledged and retry the exact stored operation with bounded backoff within the available replay window. Stop automatic retries on 400, 404, 409 or a refused update outcome.

Caller custody without a prescribed database

The platform keeps consent authority, capability hashes and bounded retry receipts. It does not keep a recoverable copy of your original capability secret or know the storefront's latest unsent choice. A state read or receipt cannot reconstruct lost caller custody, discover all previously addressed checkouts, or establish that an older reply still matches current intent.

Your integration must retain the protected scoped checkout reference, capability, pending operation/key/exact body and genuine choice time before sending, plus enough ordering/current-intent information and acknowledged withdrawal evidence to reject stale results. Serialize preparation and reconcile uncertain sends without manufacturing a second initial handoff. These obligations do not prescribe a tenant-managed database or a database product. They also do not qualify browser storage plus a stateless route handler as a complete recovery design: browser-only restart, cross-tab and lost-custody behavior still need their own accepted mechanism and evidence. Do not infer that platform receipts replace those obligations or extend permitted retention. Use the request-recovery checklist to record the supported boundaries before tenant acceptance.

Private current-state and cleanup readers

async function readConsent(apiBase, checkoutToken) {
  const response = await fetch(consentUrl(apiBase, checkoutToken), {
    cache: "no-store", credentials: "omit", redirect: "error", referrerPolicy: "no-referrer",
  });
  if (!response.ok) return null; // Unusable evidence: suppress, never guess.
  return await response.json();
}

Both GETs return Cache-Control: private, no-store and Pragma: no-cache. They do not reconcile payment, reprice, create/resume a checkout, terminalize commerce, or renew consent. Do not substitute the ordinary commerce-session GET for them. Missing/ineligible authority gives an empty state projection or { "cleanupRequired": false, "cleanupRequiredAt": null }; some underlying lookup failures can still fail the request. A neutral result or error is not proof that cleanup succeeded.

The state response supplies readAt, revision, grantGeneration, originalCutoffAt, configurationRevision, and analyticsConfiguration. For adopted analytics, state: "granted" and configuration { policy: "adopted", permitted: true } are necessary, not sufficient. Null configuration suppresses. policy: "legacy", permitted: false says nothing about whether legacy analytics runs. The configuration marker supports equality only; it is not a tenant identity or a sequence number.

Hosted consumption is implemented separately: the token-only BYO reader above does not independently bind a token to the hosted request's tenant. The hosted server resolves the canonical host and deployment environment independently before token use. The dormant #4303 consolidation uses GET /api/session/{token}/analytics-consent/read, backed by one GET /api/v1/public/checkout/sessions/{token}/analytics-consent/hosted-read API call for an ordinary adopted refresh. Its required state and cleanup projections share one original-reference resolution, one consent-read reservation and one authority-row snapshot. It does not wrap two old API calls. Original and already-authorized resume references retain the same host/tenant/environment binding and source admission order.

Cleanup takes precedence: an outstanding instruction suppresses state and skips configuration reads. Otherwise, the current configuration is read afresh and state is narrowed against the cutoff after awaited work. Invalid scope, unusable references, absent/ended authority and backend/reservation failure return neutral unknown state with null authority/configuration fields and false/null cleanup; source admission can still refuse with 429. These responses remain private and noncacheable and disclose no lookup reason.

The unavailable shell keeps the separate minimal hosted-cleanup path. It receives only cleanupRequired and cleanupRequiredAt, never a commerce recovery DTO or update secret. Page state consumption requires a successful tenant-bound ordinary commerce read and adopted policy. Equal configuration markers alone are not proof of tenant binding. Neither a neutral cleanup result nor a non-throwing cookie write proves deletion.

Implemented hosted enforcement and remaining gates

The S4/S5 controller and adapter implement the accepted contract below, but positive adopted delivery and recurring polling remain disabled. Initial entry, reload, re-entry and resume require current usable, scoped consent and configuration. The controller uses ten-second polling when enabled and leases of at most twenty seconds, capped by the original cutoff, with conservative latency accounting from server readAt. A delayed response cannot gain a fresh full lease on arrival. Stale, out-of-order, mismatched or failed reads suppress.

The consolidation preserves that cadence: six recurring refreshes per active minute target six API calls instead of twelve paired calls. Source and inert fixture counts establish the call structure, not measured runtime, contention, billing or provider acceptance. The distinct optional one-shot SSR occurrence-bracket read remains separate; it is not recurring refresh traffic and is still absent while adopted delivery is disabled. No polling, lease, visibility/focus, revision/generation or event-delivery gate changes.

#5014 landed a GET-only read-budget mechanism for #4303. It has no installed reservation backend, selected numerical limits, counters or storage policy. Existing source admission still applies. Backend, retention and cost acceptance plus integrated proof remain prerequisites to polling activation; this guide supplies no new budget permission.

An accepted withdrawal must stop new hosted analytics requests on an active page within thirty seconds of durable platform acceptance; received denial acts immediately. The bound also covers accepted disable, ID change/clear, and invalidated acknowledgement. Loading and already-loaded tags, platform commands, and unsent work must all stop. Unknown/denied means tag and request suppression, including no denied-mode pings. An unacknowledged storefront update is outside this acceptance-to-stop bound: if hosted reads continue to succeed, the old grant may remain usable until delivery succeeds or its original cutoff expires. There is no click-to-stop deadline.

Hidden/background/inactive pages suspend analytics and obtain fresh authority before resuming. Offline/failed current reads suppress; re-entry cannot reuse an expired lease. Already transmitted data cannot be recalled.

Only existing sanitized page_view, begin_checkout and one-time purchase remain eligible. Prove grant at the underlying occurrence and again before send. First observing server CONFIRMED does not prove purchase-time consent: omit an event when that evidence is unavailable. Eligible unsent events can wait at most thirty seconds in the same active document and uninterrupted grant, shortened by cutoff. Discard on grant/configuration/freshness loss, inactivity or exit. No synthetic replay of missed page/checkout starts, no durable event queue, and no retry after dispatch merely because receipt is unknown. The order ledger stays authoritative.

Entry-event proof and adopted markers

The landed #4953 implements ADR-049 §5.1. After successful eligible commerce entry on the canonical host, the server can make one optional consent read with a 500 ms deadline. Its state, grant generation, configuration marker and original cutoff are a lower bound, not a lease. Error, timeout, malformed data or 429 omits that bound without changing the commerce response. While the adopted-delivery flag is false, this extra read and its optional render wait do not run.

The page's first consent read must close that bracket with the same granted state, generation, marker and unexpired cutoff. It is one shot: abort, failure, mismatch, unknown/denied, inactivity, exit or a persisted document restore spends it; a later successful read cannot backfill entry events. Ordinary first-load pageshow is not a restore. Sending still needs a current page lease and must occur less than 30 seconds from document entry or first payable render, never 30 seconds from the read's arrival. The lower bound and occurrences stay in memory; no public schema or stored field was added.

The adopted marker namespace is lc:ga4:adopted:v1:<digest>, with a scoped SHA-256 digest and only { expiresAt, dispatched: true } in its value. begin_checkout uses sessionStorage; purchase uses localStorage under an exclusive browser lock through claim and dispatch. Missing storage/lock proof suppresses the event. Logical use ends at the original cutoff, with pruning on reachable access; no physical deletion deadline is promised for unreachable browser residue. Legacy markers remain separate. These markers are not written by the disabled adopted-delivery path.

Withdrawal cleanup and expired returns

Suppression must not wait for cookie deletion. On accepted withdrawal, attempt only explicitly owned, reachable hosted GA cookies; report bounded success, partial success, or failure. Storefront cookies, other domains, browser-blocked storage, and provider-held historical data are outside that attempt. Essential checkout and consent records remain. Unknown or ordinary grant lapse alone does not create withdrawal-specific cleanup.

If the page closed before cleanup, return through the same original reference must support the attempt even ten days later when commerce reports expired/404, while original resolution remains authorized within its separate retention. The unavailable shell must not mount GA, emit events, restore commerce or renew the grant. Only existing primary or already recognized, still-authorized resume references for that original are eligible. Legitimate deletion, revocation, retirement, excluded surfaces, wrong scope, or lost authorized resolution produce no authorized instruction; no identity search or restored binding is promised. One browser's success cannot erase the shared withdrawal or establish that all browsers are clear. S4 attempts only _ga and, when a usable current measurement ID exists, its normalized _ga_<container> cookie at /, with host-only and exact-host domain forms; it does not search parent domains or retain old IDs. Attempt/failure counts do not prove physical removal. Actual browser/provider proof remains with S8.

Adoption, disclosures and diagnostics

The landed adoption backend defaults to dormant. With its availability gate closed, it rejects enable with 503 CHECKOUT_ANALYTICS_ADOPTION_UNAVAILABLE until separately authorized platform availability. This document is not an instruction to change that gate. Preview and Production have separate configuration, adoption and evidence.

Merchant API under /api/v1/merchant/checkout-analytics-consentAccess and landed contract
GETAuthenticated organization member; current safe status/reason/source/evaluation time and coarse trends.
POST /enableOwner/Admin; body acknowledgementVersion: "e32_adoption_v1", bound to the current attested measurement ID and attestation instant. Existing current enable is a no-op.
POST /disablesettings:manage; adopted environments stay adopted and dark. A never-adopted environment returns 409 NOT_ADOPTED.
GET /control-evidenceOwner/Admin; bounded new control evidence, separate from existing settings audit history.

These merchant routes require the existing merchant authentication and tenant context. Their environment comes from deployment, not a caller-selected plane. ID management retains its existing permissions and Owner/Admin disclosure attestation. A changed ID, including A → B → A, requires renewed adoption acknowledgement and applicable integration validation.

The landed S6 card is under Settings → Checkout → Consent-driven analytics. It identifies the API's answering environment, shows current status, coarse counts, acknowledgement and control history, and reports unavailable or unconfirmed status explicitly. The Settings page requires Owner/Admin or Staff with settings:manage, which is stricter than the API's any-member status read. Adopt/re-enable/renew and evidence history remain Owner/Admin; disable uses settings:manage. Unavailable adoption blocks enable controls. Actions recheck the active organization and permissions; a refreshed card clears stale acknowledgements and history after organization or ID changes. This source comparison does not attest a deployed merchant workflow.

For explicitly adopted environments, the accepted policy permits analytics_storage: granted in all regions only with usable affirmative consent and all other gates. ad_storage, ad_user_data, ad_personalization and advertising signals stay denied. Unknown/denied suppresses requests; Consent Mode's cookieless measurement is not a substitute. Disable/invalidated adoption stays dark, never falling back to legacy defaults. Environments that never adopted retain legacy DR-2265-03, including its regional Consent Mode posture, until an authorized transition. The scoped adopted policy does not fully supersede that legacy record. DR-1828-03 remains separate Production tag-activation authority.

Public-document handoff

Before adoption, publish tenant privacy disclosures describing the hosted GA events and data, the storefront's choice capture/update route, the adopted all-region policy, withdrawal acceptance versus delivery failure, the active thirty-second bound, expiry, cleanup limits and retention below. State the actual rollout status; do not publish pending safeguards as currently operating. Link the tenant privacy policy and hosted /cookies notice visibly from the storefront handoff. The platform notice is factual disclosure, not consent or a substitute for the tenant's policy. No automatic cross-device revocation or preference center is supplied. Keep notice text synchronized with delivered behavior and the qualified Owner/Admin acknowledgement.

Diagnostics describe platform decisions, not shoppers or provider receipt. Read failures yield explicit unknowns, not a clean bill of health. The current trend response covers today plus 28 preceding UTC days; counts can be lower bounds when observation recording fails. They do not prove Google collection, attribution continuity, or a browser's cleanup result.

Minimum data, access and retention

This is the selected I1–I9 / inventory B permission contract. A maximum is not a retention target, and it is not proof of provider configuration. Existing commerce retention, DR-2265 audits, legacy deduplication and source-owned protected QA receipts retain their separate obligations.

ClassMinimum fields, purpose and accessLifetime / deletion
I1 — enforcement summaryTenant/environment/session binding, initial/latest state, source/reason, revision/generation, original cutoff, latest choice/withdrawal times, configuration revision and minimal cleanup requirement. Service writes; scoped hosted projection only, no shopper-history UI.While the original is legitimately cleanup-addressable and obligations apply: no fixed-day maximum, potentially indefinite. Remove within 7 days after legitimate lifecycle end. Ordinary commerce expiry/404 alone does not start that clock. Never extend commerce retention.
I2 — capability and retryCapability hash/scope/validity; separate key hash, request digest, decision/revision/time. Consent service and holder's bounded response only; no raw secret, body, cookies or Google IDs in platform records.Verification facts only while update authority is needed; cleanup does not extend it. Landed new-update validity is 72 hours. Retry receipts at most 7 days from acceptance; receipt expiry cannot reset authority. Post-lifecycle cleanup within 7 days where applicable.
I3 — active pageCurrent revisions, lease/generation/visibility and minimal sanitized eligible unsent envelope/occurrence/deadline/dispatch guard; hosted document only.Memory only; lease ≤20 seconds, eligible wait ≤30 seconds, shortened by cutoff/loss/inactivity/exit. No retained polling history. Implemented; positive delivery and polling disabled.
I4 — adopted dedupeScoped opaque marker and expiry/dispatch fact; hosted browser logic only. No raw token, order/customer ID, amount or payload in new markers.Logical use ends at original cutoff; remove at next reachable access. Closed/offline browser residue has no fixed physical-deletion guarantee. Legacy markers unchanged. Implemented; adopted marker writes disabled.
I5 — current configurationAdoption/ever-adopted latch, enabled/revision, existing ID reference and acknowledgement/version; existing settings access and authenticated tenant/environment status.Existing tenant/integration lifecycle, no fixed-day maximum; no separate status history. Never expire the latch into legacy defaults.
I6 — countsTenant/environment/UTC day, fixed coarse reason categories and count; authorized tenant operators only. No shopper/session/order keys, amounts, IP, private URLs, free-text errors or new Google diagnostics.At most 30 days for every observation. Current backend reads 29-day buckets to leave purge margin.
I7 — new controlsTenant/environment, existing actor ID, action/time, config revision, acknowledgement/version and outcome; existing audit-reader roles. No shopper payload.At most 365 days from event; current backend expires at 364 days for purge margin. Existing audit obligations are separate.
I8 — synthetic proofSynthetic case ID, pinned code/environment/configuration revision, safe transitions, elapsed bounds, request classes/counts and redacted cleanup/deletion results; authorized Engineering/QA only.Temporary artifacts at most 30 days from capture. No credentials, raw cookie/storage dumps, private URLs or real shopper payloads. Durable signed conclusions remain source-owned.
I9 — recovery copiesOnly necessary copies of permitted I1/I2/I5/I6/I7 server records; tightly scoped recovery operators, no diagnostic or analytics reuse.At most 90 days from capture. Purge expired auxiliary data before use; fail closed until accepted authority is reconciled. Never recreate deleted authority.

Restore fencing #4283 and actual provider backup/PITR retention #4437 remain separate unresolved evidence/authority work. Do not infer either from a database migration, logical read filter or passing documentation test.