Shopify renames headless checkout silent SSO parameter to `sso=silent` — what developers need to know

Table of Contents

1. Key Highlights
2. Introduction
3. What changed and why the rename matters
4. How silent SSO works: the OIDC-compliant verification flow
5. Continuous cart authentication vs. silent SSO: recommended approaches
6. Implementation guide: constructing checkout URLs and using sso=silent
7. Migrating from logged_in=true to sso=silent
8. Common implementation patterns and real-world examples
9. Edge cases and fallbacks: when silent SSO doesn’t authenticate
10. Security and privacy considerations
11. Testing and debugging silent SSO implementations
12. Monitoring and operational considerations
13. Developer tips and best practices
14. Real-world scenarios: how retailers benefit from silent SSO and cart authentication
15. Common pitfalls and how to avoid them
16. Where to find authoritative guidance
17. FAQ

Key Highlights

• Shopify updated headless checkout authentication docs to use the query parameter sso=silent instead of logged_in=true; existing URLs with logged_in=true continue to work.
• Use sso=silent to trigger an OIDC-compliant silent single sign-on check from a headless storefront to checkout; Shopify still recommends continuous cart authentication via customerAccessToken and redirecting to the cart’s checkoutUrl.
• Practical guidance, implementation patterns, security notes, and testing steps to migrate or implement silent SSO for headless storefronts.

Introduction

Shopify adjusted terminology in its headless checkout documentation: the silent single sign-on query parameter has been renamed from logged_in=true to sso=silent. The change is documentation-only and backward compatible, but it clarifies the parameter’s intent and aligns examples with the OpenID Connect (OIDC) verification flow Shopify uses for confirming a buyer’s active session on the customer accounts domain.

For merchants and developers building headless storefronts, authentication between storefront and checkout is a core concern. The rename matters because it reduces ambiguity about what that parameter does, and it pairs cleanly with recommended authentication strategies—most notably, continuous cart authentication using the Customer Account API and the cart’s customerAccessToken. This article unpacks the rename, explains the technical flow behind silent SSO, outlines recommended implementation patterns, and provides practical examples and troubleshooting steps so teams can deploy or migrate with confidence.

What changed and why the rename matters

Shopify replaced references to logged_in=true with sso=silent in documentation for headless checkout authentication. The functionality—an instruction to make checkout verify an active session on the customer accounts domain—remains unchanged. The rename standardizes language around single sign-on and emphasizes that the parameter triggers a silent OIDC-style check rather than a visible login redirect or an explicit flag indicating authentication status.

Why this matters:

• Clarity: sso=silent describes the behavior: a single sign-on verification performed silently (without explicit user interaction or showing a login prompt unless necessary).
• Standards alignment: The sso label ties the behavior to SSO and OIDC flows, which improves comprehension for teams familiar with identity protocols.
• Documentation consistency: Future examples and code samples will use the new parameter, reducing confusion for developers integrating headless storefronts with Shopify checkout.

Backward compatibility: URLs containing logged_in=true continue to function. No forced migrations or code breaks are required. Still, updating integrations to sso=silent is recommended to reflect current documentation and to avoid confusion during onboarding or handoffs.

How silent SSO works: the OIDC-compliant verification flow

Silent SSO validates whether a buyer has an active authenticated session on the customer accounts domain without requiring an overt sign-in step. The process follows an OIDC-compliant pattern that exchanges authentication context between the storefront and Shopify’s checkout system.

High-level flow:

1. Headless storefront crafts a checkout redirect URL, including sso=silent.
2. The buyer is redirected to Shopify checkout with the parameter included.
3. Shopify checkout performs a silent SSO check against the customer accounts domain using an OIDC-style request. If the buyer holds an active session, checkout accepts the session and completes the authenticated checkout flow without interrupting the buyer.
4. If the silent check cannot authenticate (no active session, expired session, or the accounts domain requires interactive authentication), checkout proceeds without assuming the user is authenticated or may prompt for sign-in depending on the store’s configuration.

Key technical notes:

• Silent SSO is not a token exchange performed entirely client-side. It relies on the accounts domain and checkout to perform a secure, server-mediated verification consistent with OIDC requirements.
• Because the check is silent, it avoids redirecting the buyer to a login page when a valid session exists. That preserves conversion flow and reduces friction.
• The parameter signals an authentication behavior rather than providing an authorization token. For persistent authentication tied to the cart, Shopify recommends using the customerAccessToken on the cart.

Continuous cart authentication vs. silent SSO: recommended approaches

Shopify continues to recommend continuous cart authentication for most headless storefronts using the Customer Account API. Continuous authentication means maintaining and attaching the cart’s customerAccessToken so the cart remains associated with a known customer, then redirecting the buyer to the cart’s checkoutUrl.

Why continuous cart authentication is preferred:

• Direct association: The cart is consistently linked to a customer identity, ensuring discounts, shipping profiles, customer-specific pricing, and stored addresses apply at checkout.
• Reduced reliance on redirect-time checks: By attaching customerAccessToken earlier in the flow, the storefront avoids depending solely on a redirect-triggered silent SSO to transfer authentication state.
• Cleaner UX: Buyers already identified in the storefront experience fewer surprises at checkout because their session and cart metadata are preserved.

When to use sso=silent:

• For flows where the storefront does not or cannot reliably maintain a customerAccessToken on the cart.
• For quick verification to determine if the buyer’s checkout should be treated as authenticated without interrupting the flow.
• As a fallback or supplemental mechanism alongside continuous authentication for resilience.

Practical recommendation:

• Prefer setting the cart’s customerAccessToken and forwarding buyers to the cart checkoutUrl. Use sso=silent to check the customer accounts session only when continuous cart authentication is unavailable or as an additional verification layer.

Implementation guide: constructing checkout URLs and using sso=silent

This section provides concrete examples and patterns for integrating sso=silent into headless checkout redirect flows. The exact URL format depends on the storefront’s architecture and how carts and checkouts are generated.

Basic checkout redirect with silent SSO:

• When preparing a redirect to checkout, append sso=silent to the checkout URL query string.
• Example (illustrative):
  • https://checkout.shopify.com/store-name/checkouts/abcd1234?sso=silent

Existing logged_in=true compatibility:

• URLs that include logged_in=true continue to work exactly as before. They will be processed by Shopify checkout as equivalent to sso=silent for the silent SSO behavior.

Sample server-side flow (Node.js pseudocode):

• Create a cart and generate a checkout URL via the Storefront or Cart API.
• If the storefront has the customer session token, attach it to the cart when creating or updating the cart.
• Redirect the buyer to the checkout URL; if you cannot attach the token, append sso=silent.

Node.js example outline:

// Pseudocode — adapt to your API client
const cart = await cartApi.create({ lines: cartLines });
if (customerAccessToken) {
  // Attach the customer token to the cart for continuous authentication
  await cartApi.update(cart.id, { customerAccessToken });
  redirectUrl = cart.checkoutUrl;
} else {
  // Fallback to silent SSO when no customer token is available
  redirectUrl = `${cart.checkoutUrl}${cart.checkoutUrl.includes('?') ? '&' : '?'}sso=silent`;
}
res.redirect(redirectUrl);

Client-side considerations:

• Avoid exposing sensitive tokens in the browser URL. Use server-side endpoints to create or update carts and return the checkout URL.
• When appending sso=silent, ensure proper URL encoding and respect existing query parameters.

Complex checkout flows:

• Multi-cart or split fulfillment flows should maintain the same patterns: use customerAccessToken where possible and employ sso=silent as necessary.

Migrating from logged_in=true to sso=silent

Because Shopify maintains backward compatibility, migration is straightforward. Still, a planned update ensures consistency across codebases and documentation.

Migration checklist:

1. Inventory: Search codebase(s) and templates for logged_in=true occurrences.
2. Replace: Update to sso=silent in application logic, documentation, and example snippets.
3. Test: Verify both logged_in=true and sso=silent redirects authenticate when sessions exist, and that the checkout behaves correctly when no session is present.
4. Monitor: Deploy with feature flags or staged rollouts if changes are widespread, and monitor conversion and error rates during the rollout.
5. Communicate: Document the change for future developers and update README files or developer portals.

Why not rush? Immediate action is unnecessary from a functionality perspective because the older parameter continues to function. Prioritize updates when you touch related code or during scheduled refactors.

Common implementation patterns and real-world examples

Headless storefronts vary widely—from React single-page applications to static Jamstack sites using serverless functions. These examples show how teams typically integrate checkout authentication, then illustrate where sso=silent fits.

Pattern 1 — SPA with server-side cart creation

• SPA calls a server endpoint to create a cart. Server uses Storefront API to create/update the cart and attach customerAccessToken if available.
• Server returns the cart checkout URL.
• SPA redirects the buyer to the returned checkoutUrl.
• If customer token was not attached, server appends sso=silent.

Real-world scenario:

• A subscription-focused retailer collects customer profiles in the SPA. Returning customers have active sessions stored as secure HTTP-only cookies that the server uses to attach customerAccessToken to the cart. New or guest buyers are redirected to checkout with sso=silent set to allow checkout to check for accounts session without interrupting approved flows.

Pattern 2 — Jamstack with client-side cart and serverless functions

• Client creates cart via a serverless function that interfaces with Shopify’s APIs.
• Serverless function sets customerAccessToken if the client provides it or if the cookie can be read.
• If no token exists, the checkout redirect URL returned contains sso=silent.

Real-world scenario:

• A small apparel brand uses a static site hosted on a CDN and serverless functions for backend operations. The architecture prioritizes speed and caching. Silent SSO minimizes redirect friction for returning users who may have an active Shopify session from prior interactions.

Pattern 3 — Universal rendering (Next.js, Remix)

• Universal app renders critical pages on server side; uses server session for customer identity.
• Attach customerAccessToken server-side; redirect to checkout without sso=silent when token exists.
• Use sso=silent when server session is missing, to allow checkout to verify authentication status if the user is signed into Shopify separately.

These patterns illustrate a single principle: prefer cart-level authentication, but use silent SSO as a practical fallback.

Edge cases and fallbacks: when silent SSO doesn’t authenticate

Silent SSO verifies the buyer’s session if one exists. Several situations can cause the silent check to fail or be insufficient:

Expired or invalid sessions:

• If the buyer’s session on the customer accounts domain has expired, silent SSO cannot authenticate silently. Checkout may then behave like an unauthenticated flow or prompt for sign-in.

Third-party cookies blocked:

• Some browsers and privacy settings limit cross-site cookie access, impairing silent session checks that rely on cookies set by the accounts domain. In those environments, silent SSO may fail silently and checkout will continue without identifying the customer.

SameSite cookie restrictions:

• If the accounts domain’s cookies have restrictive SameSite policies, the accounts session may not be presented during the silent check, producing the same outcome as third-party cookie restrictions.

Multiple accounts or identity mismatches:

• If the buyer has multiple accounts or session tokens inconsistent with the storefront state, checkout may not reconcile identities automatically.

Fallbacks and mitigations:

• Continuous cart authentication via customerAccessToken prevents most of these issues because the cart carries the authentication state.
• For browsers that block third-party cookies, consider progressive enhancement: present account actions or subtle UI prompts in the storefront to reauthenticate before redirecting.
• Offer clear checkout messaging when authentication fails and encourage users to sign in manually.

Security and privacy considerations

Silent SSO performs verification without direct user interaction. That imposes responsibilities for data protection and secure implementation.

Authentication vs. authorization:

• sso=silent requests only confirm the existence of an active session. The storefront should not assume authorization beyond what the session represents. Always validate server-side and apply checkout rules accordingly.

Token handling:

• Never expose long-lived tokens in URLs or client-visible storage. customerAccessToken should be handled server-side and stored in secure, HTTP-only cookies where appropriate.
• Avoid writing tokens into logs or analytics unless properly masked.

Cross-site request handling:

• Silent SSO depends on the accounts domain’s cookie behavior. Ensure the accounts domain sets cookies with appropriate secure flags and SameSite attributes consistent with cross-site verification needs and security best practices.

Privacy:

• Be transparent in privacy policies about cross-domain session usage and any third-party cookies that may be used to facilitate checkout experiences.
• Respect user privacy preferences and offer explicit account sign-in options when silent verification is unavailable or disallowed by the user.

Replay and CSRF risks:

• Although silent SSO checks are session-based, protect checkout endpoints from cross-site request forgery and replay attacks by enforcing CSRF tokens, origin checks, and server-side validation when modifying carts or attaching tokens.

Compliance:

• Ensure that data flows triggered by silent SSO match regulatory obligations (e.g., GDPR) and that session storage and user data access comply with retained consent and data minimization rules.

Testing and debugging silent SSO implementations

Testing is essential before rolling changes into production. Focus on multiple browser environments and real-world user scenarios.

Testing checklist:

• Functional tests:
  • Verify that a buyer with an active Shopify accounts session is recognized at checkout when sso=silent is present.
  • Confirm behavior when sso=silent is omitted and the cart contains a customerAccessToken.
  • Validate scenarios where neither method is present.
• Cross-browser tests:
  • Test in Chrome, Firefox, Safari, Edge, and mobile browsers to surface cookie and SameSite differences.
• Incognito and privacy mode:
  • Test in private browsing modes where cookies may be treated differently.
• Third-party cookie restrictions:
  • Test environments where third-party cookies are blocked to determine how silent SSO fails and how your storefront should handle it.
• Load tests:
  • Simulate concurrent redirects to checkout to ensure backend endpoints and the cart update/attachment logic scale.
• Analytics and conversion tracking:
  • Verify that redirects with sso=silent still preserve UTM parameters and that attribution tracking remains accurate.

Debugging tips:

• Reproduce with verbose logging on the server side when creating or updating carts; log the presence or absence of customerAccessToken without logging token values.
• Use browser developer tools to inspect cookies associated with the accounts domain and verify their attributes (Secure, HttpOnly, SameSite).
• Capture network traces to confirm the checkout redirect includes the expected query parameter and no unwanted mutations occur.

Monitoring and operational considerations

Monitor both functional and business metrics after implementing or migrating to sso=silent.

Operational metrics to track:

• Checkout conversion rates before and after change.
• Rate of unauthenticated checkouts vs. authenticated checkouts.
• Error rates associated with cart creation or checkout redirects.
• Support tickets related to login or checkout issues.

Instrumentation:

• Add logging for when a redirect includes sso=silent vs. when a cart has a customerAccessToken. Correlate these logs with purchase outcomes.
• Use synthetic monitoring to verify end-to-end checkout flows for both authenticated and guest buyers.

Rollback strategy:

• Given backward compatibility, you can safely update documentation and code incrementally. If unexpected behavior appears, revert changes in the next deployment cycle.
• Implement feature flags where rollout is broad, allowing you to enable new behavior for a subset of traffic.

Developer tips and best practices

• Prefer server-side generation of checkout URLs: This reduces token exposure and centralizes logic for attaching customerAccessToken.
• Keep the cart authenticated early: Attach customer tokens at cart creation or soon after sign-in to minimize reliance on redirect-time checks.
• Standardize URL parameter handling: Use a utility to append query parameters safely so that multiple parameters and existing search strings are treated correctly.
• Document your authentication flows: Make clear when you use customerAccessToken, when you rely on sso=silent, and how the storefront handles failed silent checks.
• Automate tests: Add integration tests that cover both token-attached and sso=silent flows so regressions are caught during CI.
• Communicate with stakeholders: Ensure marketing and analytics teams understand how redirects are structured so tracking tags and UTM parameters are preserved.

Real-world scenarios: how retailers benefit from silent SSO and cart authentication

Retailers implementing headless storefronts use different mixes of authentication strategies depending on product complexity, customer lifecycle, and user experience priorities. These examples show how sso=silent and continuous cart authentication play out in practice.

Case 1 — High-frequency reorders

• A grocery subscription service maintains logged-in sessions across devices. Attaching customerAccessToken at cart creation ensures recurring customers see saved addresses and subscription pricing at checkout. Silent SSO is unnecessary but useful as fallback for rare sessions initiated from marketing emails where the storefront session may be absent.

Case 2 — Multi-store/brand experience

• A retailer operating multiple brands uses a shared customer accounts domain. Visitors may have an active account from one brand and shop another. sso=silent checks the accounts domain to detect an active session across brands and silently applies account details when appropriate. The store couples this with cart-level tokens when the user signs in during browsing.

Case 3 — Campaign-driven traffic

• A DTC brand runs a time-limited campaign that sends users to the storefront through a referral link. Many visitors arrive as guests. The store uses silent SSO on checkout redirects in case the referral user had previously signed into Shopify on that browser, preserving a smoother checkout for returning customers while keeping onboarding quick for new users.

Common pitfalls and how to avoid them

• Exposing tokens in URLs: Never include customerAccessToken or other sensitive tokens in public URLs or analytics. Keep tokens in secure cookies or server-side session stores.
• Assuming silent SSO always authenticates: Treat it as opportunistic; design flows that degrade gracefully when silent SSO fails.
• Ignoring privacy and cookie policies: Test for browsers and privacy settings that block cross-site cookies and prepare fallbacks.
• Breaking tracking parameters: Ensure that appending sso=silent does not remove UTM or tracking parameters. Merge query parameters carefully.

Where to find authoritative guidance

Shopify’s developer documentation provides the official implementation details and examples for authenticating buyers in checkout and building with the Customer Account API. The relevant documentation page is:

• https://shopify.dev/docs/storefronts/headless/building-with-the-customer-account-api/checkout-authentication

Refer to that page for the most recent examples and platform-specific notes. Bookmark it for changes because Shopify will use sso=silent consistently in future documentation.

FAQ

Q: Does sso=silent change any server-side behavior or security model? A: No. The rename is a documentation and terminology update. Shopify’s underlying verification remains the same. The parameter signals that checkout should attempt a silent single sign-on verification following OIDC-style checks. Existing logged_in=true usage continues to work.

Q: Should I immediately replace logged_in=true with sso=silent across all code? A: Replacement is recommended for clarity and consistency, but not required for functionality. Prioritize updates when you modify related code or during planned refactors. Since backward compatibility is maintained, replacements can be staged.

Q: When should I rely on sso=silent instead of attaching customerAccessToken to the cart? A: Prefer attaching customerAccessToken at cart creation for a reliable authenticated experience. Use sso=silent when you cannot attach the token—such as client-only flows, quick referral links, or when server-side session data is unavailable—and as an additional layer of verification.

Q: How does silent SSO behave when third-party cookies are blocked or SameSite policies prevent cross-site cookies? A: In those environments, silent SSO may fail to detect an accounts session. Design flows to handle that gracefully by relying on cart-level tokens where possible or prompting users to sign in manually when necessary.

Q: Are there analytics implications when appending sso=silent to checkout URLs? A: Appending sso=silent does not inherently alter analytics. Ensure your redirect logic preserves UTM parameters and tracking query strings. Monitor conversion and attribution metrics during any rollouts to detect unintended side effects.

Q: Does sso=silent carry any security risk? A: No inherent risk arises from using sso=silent itself; the usual authentication security best practices apply. Avoid exposing tokens, enforce CSRF protections, and protect account session cookies with secure attributes. Silent SSO simply instructs checkout to verify an existing session rather than supplying authentication data in the URL.

Q: What should I do if silent SSO intermittently fails for users? A: Investigate cookie settings, browser privacy modes, and SameSite attributes for the accounts domain. Add server-side logic to prefer customerAccessToken attachments. Provide clear user flows for manual sign-in at checkout and instrument errors for monitoring.

Q: Will third-party apps need changes because of this rename? A: Most apps will not require changes. If an app inserts or reads checkout URLs and depends on the exact query parameter name, update it to use sso=silent. Otherwise, existing behavior should continue to work.

Q: Where can I find the most current guidance from Shopify? A: The official Shopify developer documentation at https://shopify.dev/docs/storefronts/headless/building-with-the-customer-account-api/checkout-authentication contains the authoritative guidance and will reflect future updates.

Q: How do I test silent SSO locally during development? A: Use an environment that simulates the accounts domain and its cookies, or test on a staging site with configured accounts sessions. Verify behavior in multiple browsers and in private/incognito modes to see how cookie policies affect silent checks.

Q: Who should I contact if I encounter a bug related to silent SSO or checkout authentication? A: Report platform-level issues through Shopify’s developer support channels or Partner/Shopify support as appropriate. For application-specific problems, instrument logs and gather replication steps to expedite diagnosis.

---

Adopt sso=silent for clearer, standards-aligned headless checkout flows and continue prioritizing cart-level authentication for predictable user experiences. Update examples and documentation incrementally, test across real world conditions, and instrument flows to detect and handle scenarios where silent checks are unavailable.