Understanding Session Tokens

WPGraphQL for WooCommerce supports two different session token systems. Understanding when to use each is critical for building reliable headless WooCommerce applications.

The Store-API cart token is created by WooCommerce's native CartTokenUtils class, originally designed for the WooCommerce Store API. This is the recommended token type for all new projects.

1. WPGraphQL for WooCommerce creates a cart token using WooCommerce's CartTokenUtils
2. The token is returned in the Customer.cartToken field
3. On subsequent requests, include the token in the Cart-Token header (no prefix needed)

Retrieving the token:

query GetSession {
  customer {
    cartToken
  }
}

Sending the token:

const response = await fetch(graphqlEndpoint, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Cart-Token': cartToken,
  },
  body: JSON.stringify({ query, variables }),
});

• Full WooCommerce Blocks support - The same token system used by WooCommerce's native blocks
• NextPress compatibility - Required when using NextPress to render WordPress/Gutenberg content containing WooCommerce Blocks
• Uses WooCommerce's official session handling mechanism
• Future-proof as WooCommerce continues to evolve

The original session token created by WooGraphQL's QL_Session_Handler class.

1. When a customer makes their first cart-related request, WooGraphQL creates a session
2. The session token is returned in the Customer.sessionToken field
3. On subsequent requests, include the token prefixed with Session in the woocommerce-session header

Retrieving the token:

query GetSession {
  customer {
    sessionToken
  }
}

Sending the token:

const response = await fetch(graphqlEndpoint, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'woocommerce-session': `Session ${sessionToken}`,
  },
  body: JSON.stringify({ query, variables }),
});

• Not fully compatible with WooCommerce Blocks - If you're rendering WordPress content that contains WooCommerce Blocks (Cart Block, Checkout Block, etc.), the legacy token may not properly hydrate the session state in those blocks.
• Not compatible with NextPress when rendering WooCommerce Block content
• Designed specifically for the WPGraphQL/WooGraphQL workflow before Store-API support was added

Recommended for all projects. Use the Store-API cart token if:

• You're starting a new project
• You're using NextPress to render WordPress content
• Your site uses WooCommerce Blocks (Cart Block, Checkout Block, Mini Cart Block, etc.)
• You want maximum compatibility with WooCommerce's native features

Only recommended if you already have an existing application using the legacy token without NextPress, and you don't have the time or resources to migrate.

For all other cases, use the Store-API cart token.

The TokenManager class in this library is agnostic to which token type you use. Configure your startSession callback to return whichever token type is appropriate:

const tokenManager = new TokenManagerWithBrowserStorage({
  ID: 'my-store',
  behavior: [SessionBehavior.withAuth],
  startSession: async (tokens) => {
    const response = await graphqlClient.query({
      query: gql`
        query GetSession {
          customer {
            cartToken  # Use cartToken for Store-API
          }
        }
      `,
      context: {
        headers: tokens.authToken
          ? { Authorization: `Bearer ${tokens.authToken}` }
          : {},
      },
    });
    return response.data.customer.cartToken;
  },
  // ... other options
});

const tokenManager = new TokenManagerWithBrowserStorage({
  ID: 'my-store',
  behavior: [SessionBehavior.withAuth],
  startSession: async (tokens) => {
    const response = await graphqlClient.query({
      query: gql`
        query GetSession {
          customer {
            sessionToken  # Use sessionToken for legacy
          }
        }
      `,
      context: {
        headers: tokens.authToken
          ? { Authorization: `Bearer ${tokens.authToken}` }
          : {},
      },
    });
    return response.data.customer.sessionToken;
  },
  // ... other options
});

When making GraphQL requests, the header format differs:

Example request with both auth and session:

// Using Store-API token (recommended)
const headers = {
  'Content-Type': 'application/json',
  'Authorization': `Bearer ${authToken}`,
  'Cart-Token': cartToken,
};

// Using Legacy token
const headers = {
  'Content-Type': 'application/json',
  'Authorization': `Bearer ${authToken}`,
  'woocommerce-session': `Session ${sessionToken}`,
};

If you're migrating from legacy tokens to Store-API tokens:

1. Update your session query to fetch cartToken instead of sessionToken
2. Change the HTTP header from woocommerce-session: Session {token} to Cart-Token: {token}
3. Clear any stored legacy tokens from client storage
4. Test cart persistence across page loads

The token format and lifecycle are similar, so the TokenManager configuration remains largely the same - only the GraphQL field and HTTP header change.