Authenticate buyers in checkout

When a buyer is authenticated on your headless storefront, there are two ways to authenticate them in checkout. Both rely on credentials issued by the identity provider, but they differ in which credential checkout verifies and how the resulting authorization is scoped.

Anchor to Option 1: Authenticate with the buyer identity on the cartOption 1: Authenticate with the buyer identity on the cart

The cart's checkoutUrl authenticates the buyer and authorizes the checkout session based on the buyer identity associated with the cart. Learn more about authenticating customers for logged-in checkouts.

When to use this option:

• You want the checkout identity to match the buyer identity set on the cart.
• You need buyer-specific pricing, discounts, or B2B terms reflected in the cart before checkout.
• You are migrating from a flow that already uses customerAccessToken on the cart.

How it works:

The customerAccessToken on the cart authenticates the buyer and authorizes the checkout session for that specific cart. The authorization is scoped to this cart — it doesn't establish a broader session on the Customer Accounts domain.

Requirements:

1. Set a valid customerAccessToken on the cart using the cartBuyerIdentityUpdate mutation or during cart creation. Keep the token up to date by refreshing it before it expires. When you refresh the token, you must also call cartBuyerIdentityUpdate again to update the cart with the new token.
2. When the buyer is ready to check out, retrieve the checkoutUrl from the Cart object.
3. Redirect the buyer to the checkoutUrl.

The buyer can complete the checkout, use saved payment methods, and manage subscriptions. However, to access customer account pages (such as order history), the buyer might need to log in separately if they don't already have an active session.

Anchor to Option 2: Authenticate with the Customer Accounts sessionOption 2: Authenticate with the Customer Accounts session

The sso=silent query parameter authenticates the buyer by verifying their active session on the Customer Accounts domain. Checkout redirects to the identity provider to check for a valid browser session using an OIDC-compliant flow.

When to use this option:

• You want checkout to verify the buyer's current session on the Customer Accounts domain.
• You want the checkout identity to always reflect the buyer's live browser session, not a stored token.
• Your storefront maintains the buyer's Customer Accounts session through periodic token refresh.

Append the sso=silent query parameter to the checkoutUrl returned by the Cart API. The checkoutUrl may already contain query parameters, so use & if needed:

{checkoutUrl}&sso=silent

How it works:

sso=silent authenticates the buyer by verifying their active session on the Customer Accounts domain. If a valid session exists, the buyer is authorized for a logged-in checkout. The authorization comes from the browser session, not from the cart — so it persists across carts but expires when the session does.

Requirements:

• The buyer must have an active session on the Customer Accounts domain (a browser cookie). If the session has expired, the buyer receives a guest checkout.
• You must periodically retrieve a new access token using the authorization code grant with prompt=none (see the prompt parameter) to keep the checkout session in sync with the IdP.