Hosted forms and actions manage the visitor state needed for carts, customer sign-in, and consent. Theme code does not need to create, inspect, or copy session cookies. Use CTX to render the current state and the documented actions to change it.
Customer access#
customer is absent when the visitor is not signed in. customer_settings describes the sign-in methods, registration options, and customer features available for this store. Use those settings when showing account controls; do not assume that phone, email, or new-customer registration is always available.
Use the hosted sign-in and registration actions. The platform verifies the supplied code and determines the customer identity. Render localized form_error or auth_notice feedback, and use the safe auth_form values when redisplaying a form. Do not infer sign-in from a URL parameter or a previously displayed customer name.
Cart and wishlist state#
A visitor may have a cart before signing in. Read cart.item_count for a badge and cart.items for the full lines. Use cart_add, cart_update, and cart_remove forms to change quantities; display the returned state rather than calculating your own stock or pricing rules. Check wishlist.enabled and wishlist.login_required before presenting wishlist controls.
Declare the data used by each section. A cart-count badge does not require the full cart, and a wishlist count does not require every saved product. Session duration and cart retention are managed by the store and platform; themes should not implement their own expiry policy.
Consent controls#
Declare consent in the banner section. consent.required is true when this visitor must be asked before optional categories apply. consent.given and consent.categories describe the recorded choice. consent.available_categories lists the optional categories the banner offers, in display order; render the checkboxes from it rather than from a fixed list. Essential storage, such as the cart and sign-in, is always allowed and has no checkbox. Consent categories explains what each category covers and when visitors are asked.
{% if consent.required %}
{% form 'consent_give' %}
{% for category in consent.available_categories %}
<label>
<input type="checkbox" name="categories" value="{{ category }}"{% if consent.categories contains category %} checked{% endif %}>
{{ 'consent_' | append: category | t }}
</label>
{% endfor %}
<button type="submit">{{ 'consent_save' | t }}</button>
<button type="submit" name="accept_all" value="1">{{ 'consent_accept_all' | t }}</button>
{% endform %}
{% form 'consent_give' %}
<button type="submit">{{ 'consent_necessary_only' | t }}</button>
{% endform %}
{% endif %}Label each category from your theme's locale files; the example reads keys such as consent_analytics and consent_advertising_data with the t filter. Keep the necessary-only action in a separate form so selected optional checkboxes are not submitted with it. Offer a Cookie preferences control so visitors can revisit their choice; the example checks the categories already granted in consent.categories. consent_withdraw records an explicit withdrawal of optional consent.
A category outside the platform set refuses the whole choice with STOREFRONT_CONSENT_CATEGORY_INVALID. Fields, responses, and errors are on Localization and consent.
The theme editor can display the consent banner while its section is selected. Previewing the banner does not save a real visitor's choice. On the storefront, use the supplied consent state.