catalyst icon indicating copy to clipboard operation
catalyst copied to clipboard

Add support for Stencil-style add-to-cart URLs

Open BC-AdamWard opened this issue 2 months ago • 2 comments

What/Why?

Adds support for BigCommerce Stencil-style add-to-cart URLs via Next.js route handlers. This enables adding products to cart using query parameters, matching the behavior of Stencil stores for compatibility.

Changes

  • New route handlers:

    • /cart.php - Stencil compatibility route
    • /add-to-cart - Catalyst-native route
  • Shared handler logic:

    • Product lookup by product_id or sku
    • Quantity support via qty parameter
    • Coupon code application via couponcode parameter
    • Action-based redirects (add → cart, buy → checkout)

Features

✅ Product lookup by ID or SKU ✅ Quantity parameter support ✅ Coupon code application ✅ Action-based redirects (cart/checkout) ✅ Comprehensive error handling ✅ User-friendly error messages via server toasts ✅ Optimized SKU search (limited to 10 products, stops at first match) ✅ Verifies checkout exists before applying coupons

Supported URL Patterns

  • /cart.php?action=add&product_id=123
  • /cart.php?action=buy&sku=xlredtshirt
  • /add-to-cart?action=add&product_id=123&qty=3
  • /add-to-cart?action=add&product_id=123&couponcode=10off100

Implementation Details

  • Uses Next.js Route Handlers (optimal for GET requests and redirects)
  • Leverages existing Catalyst utilities (addToOrCreateCart, getCartId, applyCouponCode)
  • GraphQL queries for product lookup and validation
  • Error handling follows Catalyst patterns (matches checkout/route.ts)
  • SKU search uses searchProducts API (searches Name, SKU, and Description)

Testing

Manually tested with:

  • Product ID lookup
  • SKU lookup
  • Quantity parameter
  • Coupon code application
  • Both routes (/cart.php and /add-to-cart)
  • Error handling scenarios

Migration

Minor change - New files added to support legacy Stencil and new Catalyst style routes.

BC-AdamWard avatar Nov 19 '25 14:11 BC-AdamWard

🦋 Changeset detected

Latest commit: e1e20819d0b5a935f1c58aedc6103fe8a7b8722d

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package
Name Type
@bigcommerce/catalyst-core Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

changeset-bot[bot] avatar Nov 19 '25 14:11 changeset-bot[bot]

@BC-AdamWard is attempting to deploy a commit to the BigCommerce Platform Team on Vercel.

A member of the Team first needs to authorize it.

vercel[bot] avatar Nov 19 '25 14:11 vercel[bot]