commerce-js-integration

What this skill does

# Commerce.js Integration

## Overview

Commerce.js (Chec) is a headless commerce platform offering a JavaScript SDK that wraps its REST API for managing products, carts, checkouts, and orders. It is designed for developers who want to add commerce functionality to any website or JavaScript framework without the complexity of a full e-commerce platform. The SDK handles product fetching, cart lifecycle, checkout token creation, and order capture in a straightforward, promise-based API.

## When to Use This Skill

- When you want to add e-commerce to a static site or simple React/Vue/Svelte project quickly
- When you don't need a complex backend and want a managed commerce API without server-side code
- When building a portfolio project, MVP, or proof-of-concept headless store
- When your catalog is small (under 1,000 products) and you don't need custom fulfillment logic
- When you want a simple SDK without managing a full Shopify or commercetools environment

## Prerequisites & Platform Notes

**This skill is written for custom/headless storefronts** (Node.js, Python, or similar backend). The code examples use TypeScript/Node.js and can be adapted to any stack.

**Shopify**: Shopify Hydrogen is Shopify's headless framework. MACH/composable patterns apply when using Shopify as the commerce backend with a custom frontend, or when mixing Shopify with other best-of-breed services.
**WooCommerce**: WooCommerce can serve as a headless backend via its REST API and WPGraphQL. These patterns apply when decoupling the frontend from WordPress.
**Magento**: Magento's GraphQL API and PWA Studio support headless architectures. These composable patterns apply to Magento as a backend service in a MACH stack.

**You'll need**:
- Node.js 18+ (or adapt to your backend language)
- Stripe account and API keys
- An email sending service (SendGrid, AWS SES, or Postmark)

## Core Instructions

1. **Install the SDK and initialize the client**

   ```bash
   npm install @chec/commerce.js
   ```

   ```javascript
   import Commerce from '@chec/commerce.js';

   // Public key is safe to expose in the browser
   const commerce = new Commerce(process.env.NEXT_PUBLIC_CHEC_PUBLIC_KEY, true); // true = debug mode
   ```

   Get your public API key from the Chec Dashboard under **Developer → API keys**.

2. **Fetch and display products**

   ```javascript
   // Fetch all products
   const {data: products} = await commerce.products.list({
     limit: 20,
     page: 1,
     sort_by: 'created',
     sort_direction: 'desc',
   });

   // Fetch a single product by permalink (slug)
   const product = await commerce.products.retrieve('my-product-slug', {type: 'permalink'});

   // Products include structured data
   console.log({
     id: product.id,
     name: product.name,
     price: product.price.formatted_with_symbol, // "$29.99"
     description: product.description,           // HTML string from Chec CMS
     image: product.image?.url,
     variants: product.variants,                 // Size, color options
   });
   ```

   React component example:

   ```tsx
   import {useEffect, useState} from 'react';
   import Commerce from '@chec/commerce.js';

   const commerce = new Commerce(process.env.NEXT_PUBLIC_CHEC_PUBLIC_KEY!);

   export function ProductGrid() {
     const [products, setProducts] = useState<any[]>([]);
     const [loading, setLoading] = useState(true);

     useEffect(() => {
       commerce.products.list()
         .then(({data}) => setProducts(data))
         .finally(() => setLoading(false));
     }, []);

     if (loading) return <div>Loading...</div>;

     return (
       <div className="grid grid-cols-3 gap-6">
         {products.map(product => (
           <div key={product.id} className="border rounded-lg p-4">
             <img src={product.image?.url} alt={product.name} className="w-full h-48 object-cover" />
             <h2 className="mt-2 font-semibold">{product.name}</h2>
             <p className="text-gray-600">{product.price.formatted_with_symbol}</p>
             <AddToCartButton productId={product.id} />
           </div>
         ))}
       </div>
     );
   }
   ```

3. **Manage the cart**

   Commerce.js stores the cart ID in localStorage automatically:

   ```javascript
   // Get or create the current cart
   const cart = await commerce.cart.retrieve();

   // Add a product to the cart
   const updatedCart = await commerce.cart.add(productId, quantity, {
     // Optional: specify variant selections
     variantId: 'variant_id_here',
     optionId: 'option_id_here',
   });

   // Update line item quantity
   await commerce.cart.update(lineItemId, {quantity: 3});

   // Remove a line item
   await commerce.cart.remove(lineItemId);

   // Empty the cart
   await commerce.cart.empty();

   // Refresh the cart
   const refreshedCart = await commerce.cart.refresh();
   ```

   Cart state management with React Context:

   ```tsx
   // context/cart-context.tsx
   import {createContext, useContext, useState, useEffect} from 'react';
   import Commerce from '@chec/commerce.js';

   const commerce = new Commerce(process.env.NEXT_PUBLIC_CHEC_PUBLIC_KEY!);
   const CartContext = createContext<any>(null);

   export function CartProvider({children}: {children: React.ReactNode}) {
     const [cart, setCart] = useState<any>(null);

     useEffect(() => { commerce.cart.retrieve().then(setCart); }, []);

     const addToCart = async (productId: string, quantity = 1) => {
       const {cart: updated} = await commerce.cart.add(productId, quantity);
       setCart(updated);
     };

     const removeFromCart = async (lineItemId: string) => {
       const {cart: updated} = await commerce.cart.remove(lineItemId);
       setCart(updated);
     };

     return (
       <CartContext.Provider value={{cart, addToCart, removeFromCart}}>
         {children}
       </CartContext.Provider>
     );
   }

   export const useCart = () => useContext(CartContext);
   ```

4. **Generate a checkout token and capture the order**

   ```javascript
   // Step 1: Generate a checkout token from the cart
   const checkoutToken = await commerce.checkout.generateToken(cart.id, {type: 'cart'});

   // Step 2: Get live checkout information (shipping options, taxes)
   const checkoutData = await commerce.checkout.getLive(checkoutToken.id);

   // Step 3: Capture the order
   const order = await commerce.checkout.capture(checkoutToken.id, {
     customer: {
       firstname: 'Jane',
       lastname: 'Doe',
       email: '[email protected]',
     },
     shipping: {
       name: 'Jane Doe',
       street: '123 Main Street',
       town_city: 'San Francisco',
       county_state: 'US-CA',
       postal_zip_code: '94103',
       country: 'US',
     },
     fulfillment: {
       shipping_method: checkoutData.shipping.available_options[0].id,
     },
     payment: {
       gateway: 'stripe',
       stripe: {
         payment_method_id: stripePaymentMethodId, // from Stripe.js
       },
     },
   });

   console.log(`Order #${order.customer_reference} placed!`);
   // Clear the cart after successful order
   await commerce.cart.refresh();
   ```

5. **Handle product variants**

   ```javascript
   const product = await commerce.products.retrieve(productId);

   // Variants are organized as variant groups (e.g., "Size") with options (e.g., "S", "M", "L")
   product.variants.forEach(variantGroup => {
     console.log(`Variant group: ${variantGroup.name}`);
     variantGroup.options.forEach(option => {
       console.log(`  - ${option.name}: +${option.price.formatted_with_symbol}`);
     });
   });

   // When adding to cart, provide the full variant selection
   const selections = {
     [sizeVariantGroupId]: selectedSizeOptionId,
     [colorVariantGroupId]: selectedColorOptionId,
   };

   await commerce.cart.add(product.id, 1, selections);
   ```

6. **List and display orders**

   ```javascript
   // Requires a customer JWT (obtained via commerce.customer.login)
   const customerToken = await comme