Storeconnect Controllers

StoreConnect Liquid Controllers

A Liquid controller is a theme template whose key matches a registered controller/action pair. It runs around the platform's own handling of that request: {% before %} before the action, {% after %} when the response is about to be sent, {% final %} as the last hook of the request. Controllers are the storefront-side alternative to Apex for request-time logic, and they can write to store data, so treat every one as a security-relevant change.

Controllers are entirely opt-in. The base theme ships no controller templates, so nothing you see on a default store comes from one, and there is no built-in fallback to inherit behavior from.

Is a controller the right tool?

Work down this list and stop at the first row that fits.

A controller is right when all of these hold: the work must happen on the server, it must happen during an existing registered request, it only touches the current store and the current session's own data, and it is cheap enough to run on every matching request.

Will it run at all?

• Template key is controllers/<controller>/<action>, for example controllers/carts/update, controllers/pages/show, controllers/checkout/steps/terms/update.
• The pair must already be registered. An unregistered key is never invoked and fails silently — no error, no log entry you will notice.
• Do not derive a key from a URL. The Liquid controller name often differs from the URL: /checkout/accept_terms is checkout/steps/terms, a content page at any slug is pages/show, and the home page is pages/home (a separate key).
• Confirm the exact pair against the controllers.csv exported with the target theme, or the published Liquid Controllers reference on https://support.storeconnect.com/. Neither guessing nor pattern-matching is acceptable here.
• controllers/theme is the global controller and runs on every request to the store, including component reloads and asset-adjacent routes. Keep it minimal.

Adding or changing a controller template is a theme change. Use the current supported publish and cache-refresh workflow described in storeconnect-sync-deploy, then verify the resolved storefront behavior.

Phases

Two controller templates can run per request: the global controllers/theme and the route's own controller.

Ordering and short-circuit rules, all verified:

• The first {% respond %} or {% redirect %} wins; later ones anywhere in the request are ignored.
• {% redirect %} skips everything from that point on: the rest of the same phase, the platform action, after, and final.
• {% respond %} skips all later phases. In before it also cancels the platform action.
• Both are inert in final — there is no responder in that phase, so the tag silently does nothing.
• {% variables %} set in before reach the page. Set in after, the page has already rendered and only the layout sees them.
• {% after %} does not tell you whether the platform action succeeded. original_response is populated only on the render path, so after a redirect there is nothing to inspect, and the phase fires on both the success and the failure branch. Some actions bypass after entirely and only reach final. If a write must happen exactly once regardless of branch, do it in final and make it idempotent.

Keep every side-effecting tag inside a phase block. The controller template is evaluated once per phase, so a {% params %}, {% action %}, {% update %}, {% session %}, or {% api %} left at the top level of the file fires on every pass — up to three times per request. This is the single most common controller bug in real themes. Top-level {% assign %} and {% capture %} are harmless.

Security rules — non-negotiable

This skill authorizes server-side writes. Every rule below applies before you write a single tag.

• Validate and normalize every request value before any write. Values read from current_request.params are HTML-escaped, which is not validation. Check type, length, and allowed range, and reject anything unexpected instead of coercing it.
• Never pass a raw request value into a tag option. Match it against an expected set, or rebuild it from trusted data, first.
• Require an unambiguous single-match target. Resolve the record you are about to write by iterating trusted server-side state and confirming exactly one match. If zero or more than one match, do nothing and surface a message.
• Scope by store, and for customer data by the authenticated customer. Only act on records reachable from current_store, current_customer, current_cart, or the current session. Never widen that scope.
• Never trust a request-supplied SFID or record ID. Treat it as an untrusted hint to be matched against a trusted current-store or current-customer collection, never as authorization. Resolve exactly one permitted record before calling any record-selecting action.
• {% update %} requires a read-write Custom Data Mapping for that object and field, plus the required field access. A field with no mapping, or a read-only mapping, is silently ignored — no error, no warning. See storeconnect-salesforce-data for mapping setup and storeconnect-liquid for cast rules.
• Do not use a controller for privileged administration or payment data. Never place a literal credential in a template, browser asset, repository file, or manually constructed authorization value. Where an approved integration uses the established Store Variable pattern, keep the value server-side in the documented option and never render or log it. Card data, bank details, and payment mutation belong in Salesforce with proper enforcement (storeconnect-apex-integration).
• Outbound calls go only to an approved endpoint. Never build the URL for {% api %} from a request value, and never forward request headers, cookies, raw paths, customer identifiers, record IDs, or payment details to an external service. Send the minimum an approved integration needs, with consent where required.
• Never cache output a controller varied per customer, session, or request. Keep it outside every {% cache %} block.

Failure modes to design around

Controllers fail quietly. Assume nothing worked until you have verified it.

Performance

A controller runs inside the request, so its cost is page latency.

• controllers/theme runs on every request. Guard all work behind a narrow condition before doing anything expensive.
• The template body is evaluated once per phase. A {% query %} outside a phase block runs up to three times per request.
• {% api %} blocks the render. Synchronous calls in before or after hold the response open for as long as the HTTP client allows, and the tag sets no timeout of its own, so an unreachable endpoint can stall a page for tens of seconds. Never make a synchronous call to an endpoint you do not control the latency of on a page-render path.
• {% final %} is still inside the request cycle, not after the response is delivered. Only {% api %} is forced async there; a {% query %} or {% update %} in final still delays the response.
• Cache the result of an external lookup in the page or snippet that consumes it, never the controller block that fetches it.

Verification after any controller change

1. Use the current supported publish and cache-refresh workflow (storeconnect-sync-deploy).
2. Load the exact URL the registered pair serves and confirm the intended behavior, including the case where the input is missing or invalid.
3. Confirm the phase actually ran with a temporary {% debug key: value %} probe using non-sensitive values, and check the platform Console. If nothing appears, the key does not match a registered pair. Remove the probe afterwards.
4. Check the Console for Liquid errors on that template. Any error means the controller's params, variables, and responder were discarded.
5. For a write, read the record back through the storefront and confirm the value persisted and is correctly escaped where it is displayed.
6. Confirm an unauthenticated visitor and a second customer cannot reach or influence the write.
7. Re-check any cached fragment on the affected pages for cross-customer leakage.

Which reference to read

• Writing any action tag, or unsure of an option name → read references/action-tags.md. It has the exact signature and options for params, variables, redirect, respond, update, action (with every registered action name), api, session, header, and debug, plus the tag-option parsing rules that silently break inline filters.
• Calling an external service from a controller → read the api section of references/action-tags.md before writing it. It runs inside the page render, sets no timeout, and needs explicit status handling.
• Building one of the common controller shapes (capture an extra form field, gate a page, inject render data, call an API with failure handling, return JSON, add a virtual route) → read references/controller-patterns.md for a working generic example to start from.
• Choosing between before, after, and final for a specific job → the phase-selection rules and the registry excerpt are in references/controller-patterns.md.

Related skills

storeconnect-liquid for tags, filters, drops, and {% update %} cast rules. storeconnect-forms for form names and field inventory. storeconnect-components for async reload and the built-in JSON response. storeconnect-apex-integration for anything that needs Salesforce-side enforcement. storeconnect-debug-performance for the Console, {% timer %}, and {% cache %} strategy. storeconnect-sync-deploy for pushing the template through the reviewed publish and supported cache-refresh workflow.