Session Dropoff URLs

Session dropoff URLs allow you to securely redirect users from your headless frontend to WordPress pages while maintaining their session (cart, authentication, etc.).

When users need to access WordPress-rendered pages (checkout, account, payment methods), you generate a special URL that includes a cryptographic nonce. WordPress validates this nonce and "picks up" the user's session.

• Redirecting to WordPress checkout page
• Accessing WooCommerce account pages
• Managing payment methods
• Handling WooCommerce Subscriptions

The library supports these dropoff URL types:

import { generateDropoffURL, URLTypes } from '@woographql/session-utils';

// Generate a checkout URL
const checkoutUrl = generateDropoffURL(
  clientSessionId,    // From tokenManager.getClientSessionId()
  userId,             // User/session identifier
  URLTypes.CheckoutPage
);

// Redirect the user
window.location.href = checkoutUrl;

import { TokenManager, URLTypes, generateDropoffURL, getUid } from '@woographql/session-utils';

async function redirectToCheckout(tokenManager: TokenManager) {
  // Ensure session is ready
  if (!tokenManager.isReady()) {
    await tokenManager.renewTokens();
  }

  // Get client session ID
  const clientSessionId = tokenManager.getClientSessionId();
  if (!clientSessionId) {
    throw new Error('Client session ID not available');
  }

  // Get user ID from session token
  const { sessionToken } = tokenManager.getTokens();
  const uId = getUid(sessionToken);

  // Generate and redirect
  const url = generateDropoffURL(clientSessionId, uId, URLTypes.CheckoutPage);
  window.location.href = url;
}

Generated URLs follow this pattern:

https://your-wordpress-site.com/transfer-session?session_id={userId}&{nonceParam}={nonce}

Example:

https://shop.example.com/transfer-session?session_id=abc123&_wc_checkout=a1b2c3d4e5

For more control, create a custom URL generator:

import { createUrlGenerator, URLTypes } from '@woographql/session-utils';

// Create a custom generator with different base URL or path
const generateUrl = createUrlGenerator(
  'https://my-wordpress-site.com',  // WordPress URL
  'session-handoff',                 // Custom path
  customNonceParams,                 // Optional: custom nonce params
  customNonceKeys                    // Optional: custom nonce keys
);

// Use the custom generator
const url = generateUrl(clientSessionId, userId, URLTypes.CheckoutPage);

For subscription-related URLs, the generated URL includes a placeholder:

const changeSubUrl = generateDropoffURL(
  clientSessionId,
  userId,
  URLTypes.ChangeSubscriptionPage
);
// Result: https://site.com/transfer-session?session_id=abc&_wc_change_sub=xyz&sub=%SUBSCRIPTION_ID%

// Replace the placeholder with the actual subscription ID
const finalUrl = changeSubUrl.replace('%SUBSCRIPTION_ID%', subscriptionId);

The dropoff functionality requires the WooGraphQL Pro plugin or a custom WordPress endpoint that:

1. Accepts the transfer-session route
2. Validates the nonce against the stored Client Session ID
3. Loads the WooCommerce session
4. Redirects to the appropriate page

# Your WordPress backend URL
BACKEND_URL=https://your-wordpress-site.com

Nonces are generated using a WordPress-compatible algorithm:

1. Combines user ID, Client Session ID, and action type
2. Creates a time-limited hash
3. Hash can only be verified by WordPress with the same inputs

┌─────────────────────────────────────────────────────────────┐
│                    Verification Flow                         │
├─────────────────────────────────────────────────────────────┤
│  1. User clicks dropoff URL                                 │
│                                                             │
│  2. WordPress receives request at /transfer-session         │
│                                                             │
│  3. WordPress extracts:                                     │
│     - session_id from URL                                   │
│     - Nonce from URL parameter                              │
│     - Client Session ID from WooCommerce session meta       │
│                                                             │
│  4. WordPress regenerates expected nonce using:             │
│     - session_id                                            │
│     - Stored Client Session ID                              │
│     - Action type (from nonce param name)                   │
│                                                             │
│  5. If nonces match:                                        │
│     - Load user's WooCommerce session                       │
│     - Redirect to destination page                          │
│                                                             │
│  6. If nonces don't match:                                  │
│     - Return error or redirect to login                     │
└─────────────────────────────────────────────────────────────┘

• Client Session ID expires after 1 hour
• Nonces are derived from the Client Session ID, so they share this expiration
• Users must complete the handoff within this window

'use client';

import { useSession } from '@/client/SessionProvider';
import { generateDropoffURL, URLTypes } from '@woographql/session-utils';

export function CheckoutButton() {
  const { tokenManager, cart, customer } = useSession();

  const handleCheckout = async () => {
    // Ensure we have a valid session
    if (!tokenManager.isReady()) {
      await tokenManager.renewTokens();
    }

    const clientSessionId = tokenManager.getClientSessionId();
    if (!clientSessionId) {
      // Handle error - client session ID required
      console.error('Client session ID not available');
      return;
    }

    // Get user ID (from customer or session token)
    const userId = customer?.databaseId?.toString() ||
                   cart?.sessionToken?.split('||')[0] ||
                   'guest';

    // Generate checkout URL
    const checkoutUrl = generateDropoffURL(
      clientSessionId,
      userId,
      URLTypes.CheckoutPage
    );

    // Redirect to WordPress checkout
    window.location.href = checkoutUrl;
  };

  return (
    <button onClick={handleCheckout}>
      Proceed to Checkout
    </button>
  );
}

• Client Session ID Usage - Prerequisites for dropoff URLs
• Session Behaviors - Enabling withClientSession behavior