Add support for Stencil-style add-to-cart URLs
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_idorsku - Quantity support via
qtyparameter - Coupon code application via
couponcodeparameter - Action-based redirects (
add→ cart,buy→ checkout)
- Product lookup by
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
searchProductsAPI (searches Name, SKU, and Description)
Testing
Manually tested with:
- Product ID lookup
- SKU lookup
- Quantity parameter
- Coupon code application
- Both routes (
/cart.phpand/add-to-cart) - Error handling scenarios
Migration
Minor change - New files added to support legacy Stencil and new Catalyst style routes.
🦋 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
@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.