Checkout Failures

Symptoms

• “Proceed to Checkout” button does nothing
• Checkout redirect fails or shows error page
• “Failed to generate checkout URL” error message
• Customer stuck on cart page, can’t complete purchase

Common Causes

1. Cart Data Issues

• No active cart cookie found
• Cart ID expired or invalid
• Empty cart attempting checkout
• Cart-cookie domain mismatch

2. BigCommerce Connection Problems

• GraphQL API authentication failure
• Checkout URL generation API timeout
• Store channel not properly configured
• Expired or invalid access token

3. Redirect URL Failures

• Null checkout URL returned from API
• CORS issues blocking redirect
• Browser blocking third-party cookies
• Customer logged into wrong BigCommerce account

Solutions

Check Cart Cookie

Verify the cart cookie exists and is valid:

1. Open browser DevTools (F12)
2. Go to Application → Cookies
3. Look for bigcommerce_cart_id cookie
4. Verify cookie domain matches your WordPress® site domain

If cookie missing or domain wrong:

• Clear all cookies for the site
• Add item to cart to generate new cart
• Verify cart cookie appears with correct domain

Test GraphQL Connection

Verify BigCommerce API connectivity:

1. Go to Commerce Connect → Settings → Connection
2. Click “Test Connection” button
3. Check API status - should show “Connected”

If connection fails:

• Verify store URL in settings matches BigCommerce store
• Check access token is valid and not expired
• Regenerate token in BigCommerce admin if needed

Debug Checkout URL Generation

Check if checkout URL is being created:

1. Enable WordPress® debug logging in wp-config.php:

   define('WP_DEBUG', true);
   define('WP_DEBUG_LOG', true);

2. Attempt checkout and check logs:

   tail -f wp-content/debug.log | grep "checkout"

3. Look for specific errors:

   • No active cart found - Cart cookie missing or invalid
   • Failed to create checkout redirect URLs - API request failed
   • Null checkout URL returned - API returned empty response

Fix Cart Cookie Domain Issues

If cart works but checkout fails due to domain mismatch:

1. Verify WordPress® site URL:

   wp option get siteurl

2. Check cookie domain in DevTools matches site URL

3. Clear browser cookies completely

4. Add product to cart again to regenerate cookie with correct domain

Handle Empty Cart Errors

If error says “No active cart found”:

1. Verify cart has items before attempting checkout

2. Check cart API response:

   // In browser console
   fetch('/wp-json/commerce-connect/v1/cart')
     .then((r) => r.json())
     .then(console.log);

3. Expected response: Cart object with line items

4. If empty or error: Clear cookies and rebuild cart

Fix CORS/Third-Party Cookie Issues

Modern browsers block third-party cookies by default:

1. Verify BigCommerce checkout domain is whitelisted
2. Check browser console for CORS errors
3. Test in incognito mode to rule out browser extensions
4. Consider embedded checkout instead of redirect (future feature)

Verification

After applying fixes:

1. Clear browser cache and cookies completely
2. Add product to cart from WordPress® site
3. Click “Proceed to Checkout” button
4. Verify redirect to BigCommerce checkout page
5. Confirm cart items appear in checkout
6. Complete test purchase (or cancel at payment step)

Success indicators:

• Smooth redirect to BigCommerce checkout URL
• Cart items display correctly in checkout
• Customer information pre-filled (if logged in)
• No JavaScript errors in browser console

Prevention

Monitor API Health

1. Test checkout flow weekly with test product
2. Monitor error logs for checkout-related failures
3. Set up uptime monitoring for BigCommerce API (optional)
4. Subscribe to BigCommerce status updates at status.bigcommerce.com

Maintain Token Freshness

1. BigCommerce access tokens are long-lived but can expire
2. Plugin handles refresh automatically when possible
3. Monitor connection status in admin dashboard
4. Regenerate token manually if persistent failures occur

Optimize Cookie Configuration

1. Use consistent domain across WordPress® and checkout
2. Avoid switching between www/non-www URLs
3. Ensure HTTPS is enforced site-wide
4. Test cross-browser (Chrome, Safari, Firefox) regularly

Customer Communication

For customer-facing checkout issues:

1. Display clear error messages when checkout fails
2. Provide fallback instructions: “Try clearing cookies and adding to cart again”
3. Offer support contact for persistent problems
4. Consider alternate checkout link to BigCommerce directly as backup

Advanced Debugging

Inspect GraphQL Requests

Check the actual API request/response:

1. Open browser DevTools → Network tab

2. Filter by “graphql”

3. Click “Proceed to Checkout”

4. Inspect request payload:

   {
     "query": "mutation createCartRedirectUrls...",
     "variables": {
       "input": {
         "cartEntityId": "abc-123"
       }
     }
   }

5. Check response for redirectedCheckoutUrl field

Common GraphQL Error Codes

Error	Cause	Solution
UNAUTHORIZED	Invalid/expired token	Regenerate access token
NOT_FOUND	Cart ID doesn’t exist	Clear cookies, rebuild cart
VALIDATION_ERROR	Invalid cart data	Check product variants/options
INTERNAL_ERROR	BigCommerce API issue	Wait and retry, check status page

WordPress® Error Log Patterns

Key log messages to watch for:

Failed to create checkout redirect URLs

→ BigCommerce API rejected the request. Check cart ID validity and connection status.

Null checkout URL returned

→ API response missing expected field. Verify GraphQL query matches BigCommerce API version.

No active cart found

→ Cart cookie missing or cart expired. Customer needs to rebuild cart.

Test with WP-CLI

Manually test cart and checkout operations:

# Get current cart (requires cart cookie context)
wp eval 'do_action("rest_api_init"); $response = rest_do_request("/commerce-connect/v1/cart"); print_r($response->get_data());'

# Check if checkout endpoint is registered
wp rest-api list-routes | grep checkout

Cart Cookie Lifecycle

Understanding cart persistence:

1. Creation: Cookie set when first item added to cart
2. Expiration: Default 30 days (configured in BigCommerce)
3. Update: Cookie value updated after each cart mutation
4. Deletion: Cleared after successful order or manual logout
5. Validation: Checked on every cart operation

If cart cookie present but checkout fails:

• Cart may have expired on BigCommerce side
• Customer may have completed/abandoned cart previously
• Solution: Delete cart cookie and rebuild cart fresh