For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
Dev Portal
DocsAPI ReferenceLearnCommunityChangelog
DocsAPI ReferenceLearnCommunityChangelog
  • Overview
    • Quick Start
    • Sandboxes
    • Tools & SDKs
    • Support
  • Docs
      • Getting Started
        • Introduction to Headless Commerce
          • REST Management API: Headless Checkout Flow
          • GraphQL Storefront API: Headless Checkout Flow
          • Session Syncing: Headless Checkout
        • Creating Channels
        • Orders
        • Customers
        • PCI Compliance
        • Routes
        • Using API Site Content
    • Archive
    • Closed Beta Programs
Dev Portal
LogoLogo
On this page
  • Intended Behavior
  • Login Flow
  • Diagram: Login Flow
  • Logout Flow
  • Diagram: Logout Flow
  • Setup Instructions
DocsStorefrontHeadlessEnd-to-End Guides

End-to-End Guide: Session Syncing Between Headless Storefront and Stencil Checkout

Was this page helpful?
Previous

GraphQL Storefront API: Headless Checkout Flow

Next

Creating Channels

Built with

This guide outlines the interim solution to sync a shoppers authentication (login/logout) session between a headless storefront and Stencil checkout.

Intended Behavior

Be aware that this solution removes the ability to sign in directly at checkout. Instead, authentication must occur through the headless storefront’s login flow.

Login Flow

  1. The shopper navigates to Stencil Checkout as a guest.
  2. They click Sign In.
  3. They’re redirected to the login page on the headless storefront.
  4. After signing in, they’re redirected back to Stencil Checkout, now signed in.

Diagram: Login Flow

Logout Flow

  1. The shopper navigates to Stencil Checkout while signed in.
  2. They click Sign Out.
  3. They’re redirected to the logout route on the headless storefront.
  4. After signing out, they’re redirected back to Stencil Checkout, now as a guest.

Diagram: Logout Flow

Setup Instructions

1

Step 1: Headless Storefront Configuration (Prerequisite)

Before session syncing can work, your headless storefront must be configured to support authentication redirects.

Required Routes and Behavior

Security note: For Login/Logout routes, developers are responsible for validating the redirectTo parameter to prevent open redirects. We recommend restricting this to relative paths (e.g. /checkout) only.

  • /checkout route
    Your headless storefront should include a /checkout route that redirects to BigCommerce Stencil Checkout.

  • Login route with redirectTo support
    Your storefront’s login page must accept a redirectTo query parameter that determines where the shopper is redirected after login.

  • Logout route with redirectTo support
    Your storefront must also expose a /logout route that logs the shopper out and then consumes a redirectTo query parameter.

Channel Guidance

While this setup can be configured on the default channel, we recommend using a secondary channel to avoid coupling with your primary storefront.

2

Step 2: Configure BigCommerce routes

Use the Update a Site’s Routes API call:

PUT https://api.bigcommerce.com/stores/{store_hash}/v3/sites/{site_id}/routes

Payload:

[
	{
		"type": "home",
		"matching": "*",
		"route": "/"
	},
	{
		"type": "cart",
		"matching": "*",
		"route": "/cart/"
	},
	{
		"type": "login",
		"matching": "*",
		"route": "/login/"
	},
	{
		"type": "logout",
		"matching": "*",
		"route": "/logout/"
	}
]
3

Step 3: Enable storefront redirection in checkout settings

Use the Update Channel-Specific Checkout Settings API call:

PUT https://api.bigcommerce.com/stores/{store_hash}/v3/checkouts/settings/channels/{channel_id}

Payload:

{
	// Required to enable session-based redirect
	"should_redirect_to_storefront_for_auth": true,
	// Required if no custom checkout settings exist for this channel
	"custom_checkout_script_url": "",
	"custom_order_confirmation_script_url": "",
	"order_confirmation_use_custom_checkout_script": false
}