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 value | Meaning |
|---|---|
granted | An affirmative analytics choice collected by the storefront; usable only within its original cutoff and all remaining configuration, freshness, host, surface, and activation gates. |
denied | Refusal or withdrawal. Known denial survives lapse. |
unknown | No 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 choice | Eligible storefront surface | Hosted cartonium checkout |
|---|---|---|
| Confirmed Allow | Honor 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 Decline | Keep GA4 off without another automatic prompt. Keep the existing analytics preferences accessible for a voluntary change or check. | Checkout continues with analytics off. |
| Unconfirmed choice | Offer 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 path | Input / result |
|---|---|
POST /api/v1/public/checkout/sessions/{token}/analytics-consent | x-idempotency-key; body state, assertedAt, updateCapability, optional inheritedDenial; 201 handoff result. |
POST /api/v1/public/checkout/sessions/{token}/analytics-consent/updates | x-idempotency-key, x-consent-update-capability; body state, assertedAt, expectedRevision; 200 decision, including refused decisions. |
GET /api/v1/public/checkout/sessions/{token}/analytics-consent | Private current state and configuration; no update secret. |
GET /api/v1/public/checkout/sessions/{token}/analytics-consent/cleanup | Private 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 failure | Required handling |
|---|---|
superseded | A newer choice outranks this intent, or unknown would erase denial. Do not rebase an old grant. |
rejected_stale_revision | Re-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_newer | Assertion is not strictly newer than the accepted choice; do not forge a later timestamp. |
rejected_after_cutoff | A grant cannot extend the original ceiling. |
rejected_unknown_never_grants | No usable explicit grant; keep analytics suppressed. |
rejected_capability_unavailable | Wrong, 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 / 409 | Validation 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 / 5xx | Delivery 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 attempt | Meaning for an identical retry |
|---|---|
| Handoff commits | Authority 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 commits | Any 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 back | Its 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 digest | 409 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-consent | Access and landed contract |
|---|---|
GET | Authenticated organization member; current safe status/reason/source/evaluation time and coarse trends. |
POST /enable | Owner/Admin; body acknowledgementVersion: "e32_adoption_v1", bound to the current attested measurement ID and attestation instant. Existing current enable is a no-op. |
POST /disable | settings:manage; adopted environments stay adopted and dark. A never-adopted environment returns 409 NOT_ADOPTED. |
GET /control-evidence | Owner/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.
| Class | Minimum fields, purpose and access | Lifetime / deletion |
|---|---|---|
| I1 — enforcement summary | Tenant/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 retry | Capability 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 page | Current 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 dedupe | Scoped 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 configuration | Adoption/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 — counts | Tenant/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 controls | Tenant/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 proof | Synthetic 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 copies | Only 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.