Checkout Session Syncing Solutions

In a previous release, we improved our GraphQL Authentication implementation which added the ability for a shopper to login from their Catalyst/headless storefront and remain logged in as they proceed into the Stencil checkout page.

This document outlines step-by-step instructions to further improve that feature which allow the shopper to login (and logout) from the Stencil checkout page, and have their login state persist back to the Catalyst/headless storefront.

Intended Behavior

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 Catalyst/headless storefront.
4. After signing in, they’re redirected back to Stencil Checkout, now signed in.

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 Catalyst/headless storefront.
4. After signing out, they’re redirected back to Stencil Checkout, now as a guest.

Setup Instructions

1. Use the latest Catalyst code.

   Ensure you’ve merged the following pull requests:

   • PR #2182
   • PR #2186

2. Configure login and logout routes.

   Send a request to GET a Channel Site to retrieve the site_id for your Catalyst/headless storefront.

   GET https://api.bigcommerce.com/stores/{store_hash}/v3/sites

   Send a request to PUT Routes to configure the login and logout routes.

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

   [
     {
       "type": "home",
       "matching": "*",
       "route": "/"
     },
     {
       "type": "cart",
       "matching": "*",
       "route": "/cart/"
     },
     {
       "type": "login",
       "matching": "*",
       "route": "/login/"
     },
     {
       "type": "logout",
       "matching": "*",
       "route": "/logout/"
     },
     // Optional: Included by One-Click Catalyst but not required for session syncing
     {
       "type": "search",
       "matching": "*",
       "route": "/search/"
     },
     {
       "type": "account",
       "matching": "*",
       "route": "/account/"
     }
   ]

3. Enable storefront redirection in checkout settings.

   To enable storefront redirection in checkout settings, send a request to PUT Checkout Settings to update the should_redirect_to_storefront_for_auth setting.

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

   {
     // 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
   }