finsilabs/cart-logic

Cart Logic

Overview

Cart logic covers how your store manages items a shopper intends to buy: adding, removing, and updating items; persisting the cart across page loads and devices; and merging a guest cart into an account when the customer logs in. On Shopify, WooCommerce, and BigCommerce, the cart is built into the platform — the goal is to configure it correctly and extend it when needed. Custom code is only required for headless storefronts.

When to Use This Skill

• When cart state is lost when users navigate between pages (missing persistence)
• When guest cart items disappear after login (missing merge logic)
• When implementing real-time cart price updates (coupons, quantity changes, shipping estimates)
• When building a headless storefront that needs a custom cart implementation

Core Instructions

Step 1: Understand how your platform handles cart logic

| Platform | Cart Behavior | Where to Configure | |----------|--------------|-------------------| | Shopify | Built-in cart with automatic persistence; uses cookies/localStorage | Theme Liquid templates + Cart API; extend with Cart Transform Shopify Function | | WooCommerce | Built-in cart with session persistence; configures via PHP hooks | WooCommerce settings + woocommerce_add_cart_item_data and woocommerce_cart_item_price filters | | BigCommerce | Built-in Storefront Cart API; cart persists via cookie | BigCommerce Stencil theme + Storefront Cart API | | Custom / Headless | Must build from scratch using platform APIs or Shopify/BigCommerce Storefront API | See Custom / Headless section below |

Step 2: Configure and extend cart behavior

---

Shopify

Shopify's cart is managed automatically. To extend it:

Customize the cart drawer or page:

1. Go to Online Store → Themes → Customize
2. Select the cart section and configure: cart type (drawer vs. page), item display, quantity controls
3. Enable Cart notes and Shipping estimate in the cart settings if needed

Enable cart persistence across devices (requires accounts):

• Shopify automatically persists cart for logged-in customers; the cart is stored server-side on their account
• For guest carts, Shopify uses a cart_token cookie (30-day expiry by default)

Merge guest cart on login:

• Shopify handles this automatically — when a guest logs in, their cart is merged with any existing account cart

Cart customization via Shopify Functions: Use Cart Transform Shopify Functions to modify cart items, apply custom discounts, or bundle products. Go to Settings → Custom data and deploy a Cart Transform function via the Shopify CLI.

Custom cart upsells and cross-sells: Install CartHook, ReConvert, or Frequently Bought Together from the Shopify App Store for cart upsell logic without custom code.

---

WooCommerce

WooCommerce's cart is built-in and session-based.

Configure cart behavior:

1. Go to WooCommerce → Settings → Products → General to configure cart and add-to-cart behavior
2. Enable or disable Redirect to cart page after successful addition based on your store's UX preference
3. Under WooCommerce → Settings → Advanced → Cart page, verify the cart page is assigned

Enable persistent cart for logged-in users:

1. Go to WooCommerce → Settings → Accounts & Privacy
2. Enable Persistent cart — this stores a logged-in customer's cart in the database so it survives across sessions and devices

Guest cart to account merge: WooCommerce automatically merges the guest cart with the customer's saved cart when they log in. To ensure this works, keep Persistent cart enabled.

Extend cart item data (e.g., for product customization options): Use the woocommerce_add_cart_item_data filter in your theme's functions.php or a custom plugin to attach extra data to cart items (gift messages, engraving text, etc.).

Cart abandonment tracking: Install CartFlows or WooCommerce Cart Abandonment Recovery plugin to track and recover abandoned carts.

---

BigCommerce

BigCommerce uses its Storefront Cart API for cart management.

Configure cart settings:

1. Go to Settings → Storefront to configure cart and checkout behavior
2. Cart persistence is automatic via BigCommerce's session management

Customize the cart via Stencil theme: Edit cart templates in your Stencil theme (templates/components/cart/) to modify the cart page layout, item display, and available actions.

Cart upsells: Use the BigCommerce Cart API to detect items in the cart and conditionally show related products or promotions in the cart template.

---

Custom / Headless

For a headless storefront, use your platform's Storefront API rather than building cart storage from scratch:

Shopify Storefront API (recommended for Shopify-backed headless stores):

// Create a cart
const createCart = async () => {
  const response = await fetch(`https://${SHOP_DOMAIN}/api/2024-01/graphql.json`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-Shopify-Storefront-Access-Token': STOREFRONT_TOKEN,
    },
    body: JSON.stringify({
      query: `
        mutation cartCreate($input: CartInput!) {
          cartCreate(input: $input) {
            cart { id checkoutUrl }
            userErrors { field message }
          }
        }
      `,
      variables: { input: { lines: [{ merchandiseId: variantGid, quantity: 1 }] } },
    }),
  });
  const { data } = await response.json();
  return data.cartCreate.cart;
};

// Add an item to an existing cart
const addToCart = async (cartId, variantGid, quantity) => {
  const response = await fetch(`https://${SHOP_DOMAIN}/api/2024-01/graphql.json`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-Shopify-Storefront-Access-Token': STOREFRONT_TOKEN,
    },
    body: JSON.stringify({
      query: `
        mutation cartLinesAdd($cartId: ID!, $lines: [CartLineInput!]!) {
          cartLinesAdd(cartId: $cartId, lines: $lines) {
            cart { id totalQuantity cost { totalAmount { amount currencyCode } } }
          }
        }
      `,
      variables: { cartId, lines: [{ merchandiseId: variantGid, quantity }] },
    }),
  });
  const { data } = await response.json();
  return data.cartLinesAdd.cart;
};

Store the cartId in a cookie or localStorage. On login, use cartBuyerIdentityUpdate to associate the cart with the customer's account — Shopify handles the merge automatically.

BigCommerce Storefront API (for BigCommerce-backed headless stores):

Use the BigCommerce Storefront Cart API (/api/storefront/carts) which handles cart creation, item management, and customer association automatically.

Step 3: Implement key cart UX behaviors

Regardless of platform, these are the cart behaviors that most affect conversion:

1. Show mini-cart on add-to-cart — most Shopify, WooCommerce, and BigCommerce themes support a slide-out cart drawer that opens when an item is added; enable this instead of redirecting to the cart page
2. Show stock levels in the cart — display "Only 2 left" warnings on items with low inventory; both Shopify and WooCommerce support this via metafields and cart item data
3. Guest cart persistence — ensure guest carts survive for at least 30 days so returning visitors find their items; Shopify does this by default; WooCommerce requires the session duration setting to be configured
4. Free shipping progress bar — show a "You're $X away from free shipping" bar in the cart; install Free Shipping Bar (Shopify) or WooCommerce Free Shipping Bar plugin

Best Practices

• Use your platform's native cart — Shopify, WooCommerce, and BigCommerce carts are battle-tested and handle edge cases (stock validation, price changes, tax calculation) correctly
• Enable persistent cart for logged-in customers — all three platforms support server-side cart storage for accounts; enable it
• Validate stock at checkout, not only on add-to-cart — items may sell out while in a guest's cart; re-validate at checkout time (platforms do this automatically)
• Show the cart total prominently — including item count and subtotal; reduces anxiety about total spend
• For headless: use the platform's Storefront API — Shopify and BigCommerce Storefront APIs are production-hardened and handle cart merging, stock checks, and checkout initiation correctly

Common Pitfalls

| Problem | Solution | |---------|----------| | Cart disappears when user logs in (WooCommerce) | Ensure Persistent cart is enabled in WooCommerce → Settings → Accounts & Privacy | | Guest cart is empty after browser restart | Check cookie expiry settings; Shopify uses 30-day cart tokens by default; WooCommerce session duration is configurable | | Same item added twice instead of incrementing quantity | The platform's native cart handles this; if using headless with Storefront API, use cartLinesUpdate to increment quantity on existing lines | | Cart shows outdated prices after a price change | Shopify and WooCommerce automatically use current prices at checkout, not add-to-cart prices; a "price changed" notice appears automatically | | Custom add-to-cart code bypasses stock checks | Always use the platform's official add-to-cart mechanisms; custom code that writes directly to cart storage skips inventory validation |

Related Skills

• @checkout-flow-optimization
• @guest-checkout
• @inventory-tracking
• @stripe-integration