Runtime actions

Switch the visitor's country and language, and record the visitor's cookie-consent choice.

POST /consent

{% form 'consent_give' %}

Records the visitor's cookie-consent choice on their session. Categories are platform-defined (analytics, marketing, personalization; essential is implicit). Grant timestamp and country are stamped server-side.

Form fields

categories Optional: Repeatable. Categories the visitor grants: analytics, marketing, personalization. Essential is implicit and never posted. Omit all (and no accept_all) to record a necessary-only choice.
accept_all Optional: Any non-empty value grants every category — the banner's Accept-all button.
return_to Optional: Path to return to; defaults to the referring page.
_format Optional: Set to json when submitting with fetch; omit for the normal browser redirect.

Validation

Requires a visitor session. Category values are validated against the platform set (analytics, marketing, personalization) — an unknown category is refused. Timestamp and country are stamped server-side; client-supplied values are ignored.

Limits

One consent record per session; a new submission replaces the previous choice.

Response

Form mode 303s back to return_to (or the referrer); JSON returns {success, consent}.

POST /consent/withdraw

{% form 'consent_withdraw' %}

Withdraws consent: records an explicit no-consent choice; capture reverts to anonymous and the attribution cookie is deleted on the next render.

Form fields

return_to Optional: Path to return to; defaults to the referring page.
_format Optional: Set to json when submitting with fetch; omit for the normal browser redirect.

Validation

Requires a visitor session.

Limits

Idempotent — withdrawing with no prior grant still records an explicit no-consent choice.

Response

Form mode 303s back to return_to (or the referrer); JSON returns {success, consent}.

POST /localization

{% form 'localization_set' %}

Switches the visitor's country and/or language; form mode 303s to the localized page, JSON returns the resolved localization + redirect_url.

Form fields

country_code Optional: ISO country to localize to; empty keeps the current country.
locale Optional: Locale code to switch to; empty keeps the current language.
return_to Optional: Path to return to; defaults to the referring page (re-prefixed for the chosen locale).
_format Optional: Set to json when submitting with fetch; omit for the normal browser redirect.

Validation

At least one supported country or locale is resolved from ctx.localization choices. return_to is reduced to a safe internal path and re-prefixed for the selected locale.

Limits

Country is an available ISO code; locale is an available storefront locale; external return URLs are rejected as destinations.

Response

{
  success:true,
  data:{market,currency,localization,available_countries,available_languages,stamped,redirect_url}
}

stamped reports whether the choice was saved to a visitor session; resolution failures return {success:false,error}.

Localization action#

{% form 'localization_set' %} posts to /localization and switches the visitor's market context. It accepts country_code and locale as INDEPENDENT fields — send one, the other, or both. A country picker posts only country_code; a language picker posts only locale.

vein

{% for c in localization.available_countries %}
  {% form 'localization_set' %}
    <input type="hidden" name="country_code" value="{{ c.iso_code }}">
    <button type="submit"{% if c.selected %} aria-current="true"{% endif %}>{{ c.flag }} {{ c.name }} ({{ c.currency_code }})</button>
  {% endform %}
{% endfor %}

{% for l in localization.available_languages %}
  {% form 'localization_set' %}
    <input type="hidden" name="locale" value="{{ l.iso_code }}">
    <button type="submit"{% if l.selected %} aria-current="true"{% endif %}>{{ l.native_name | default: l.name }}</button>
  {% endform %}
{% endfor %}

Field	Meaning
country_code	ISO country to switch the market context to. Optional when locale is sent.
locale	Language code to switch to. Optional when country_code is sent.
return_to	Path to redirect back to. Optional — defaults to the referring page (the localized equivalent of where the visitor was).

A language-only switch KEEPS the visitor's current country: the platform resolves it from the session's market stamp first, then visitor geo, then the domain's default country. Your form never needs to smuggle the current country along — posting just locale is the supported contract.

The response is a redirect to the localized path of return_to (locale-prefixed routes switch prefix automatically). Values must come from ctx.localization.available_countries / available_languages — an unknown value is a user error, not a silent fallback.