How to Integrate BigCommerce with V0

Before writing any code, collect your BigCommerce API credentials from the admin panel. Log in to your BigCommerce store and go to Advanced Settings → API Accounts → Create API Account. Name it (e.g., V0 Headless Storefront) and select the API type as V2/V3 API Token. Under OAuth Scopes, you need at minimum: Products (read-only), Carts (modify), Checkouts (modify), Orders (read-only), and Content (read-only). Click Save and BigCommerce will show you the credentials once — save all three values immediately: the Client ID (starts with a long alphanumeric string), the Client Secret, and the Access Token. You also need your Store Hash, which is visible in the URL of your BigCommerce admin panel: it looks like store-xxxxxxxx in the URL https://store-xxxxxxxx.mybigcommerce.com/manage. For the Storefront API (customer-facing browsing), you'll also need a Storefront API Token if you want to use BigCommerce's GraphQL Storefront API. Generate one from Advanced Settings → Storefront API Tokens. The REST Management API is what most Next.js integrations use — it's the simpler approach and what this tutorial focuses on. Store your Store Hash and Access Token; you won't need the Client ID and Secret for server-to-server REST API calls.

Open V0 at v0.dev and start with the product listing page — this is the foundation of your storefront. Describe the layout you want: grid or list view, filtering sidebar, sorting controls, and the card design for each product. Be specific about the component interface: the card should accept a product object with id, name, price, images, and a URL slug. V0 generates the component with Tailwind CSS and shadcn/ui. Use mock data with 6-9 sample products so the grid looks representative. Once the catalog looks right, generate the product card component separately with a V0 prompt — this component will be reused across the catalog and potentially a featured products section on the homepage. After the catalog and card, generate the cart sidebar component. The cart needs to be managed in a shared state context so that adding a product from the catalog updates the cart count in the header. Ask V0 to generate a CartProvider context component that wraps the app layout. V0 may generate a cart that stores state in localStorage — this is acceptable for a starting point, but you'll replace it with BigCommerce's server-side cart API in a later step for a persistent cart that survives browser refreshes. Design Mode (Option+D) lets you adjust the visual design without spending credits.

Create two API route files: one for product catalog operations and one for cart operations. The BigCommerce Management API base URL is https://api.bigcommerce.com/stores/{storeHash}/v3. All requests require the header X-Auth-Token set to your access token — this header stays server-side in your route handler and is never sent to the browser. For the products route, the GET handler fetches the product catalog with pagination. The BigCommerce V3 Products endpoint returns a data array of products with all fields including images, variants, and custom fields. Add query parameters for filtering: include_fields, limit, page, and keyword for search. For the cart route, you need POST to create a new cart or add items, GET to retrieve a cart by ID, PUT to update item quantities, and DELETE to remove items. BigCommerce cart IDs are UUIDs stored in a cookie on the client. When creating a cart for the first time, store the returned cart ID in a cookie so subsequent requests can retrieve the same cart. For checkout, fetch the cart's redirect_urls.checkout_url from the cart API and redirect the customer there — BigCommerce handles the rest. The checkout URL is a one-time-use URL that expires, so generate it fresh each time the customer clicks checkout.

1import { NextRequest } from 'next/server';
2
3const STORE_HASH = process.env.BIGCOMMERCE_STORE_HASH!;
4const ACCESS_TOKEN = process.env.BIGCOMMERCE_ACCESS_TOKEN!;
5const BC_BASE = `https://api.bigcommerce.com/stores/${STORE_HASH}/v3`;
6
7const bcHeaders = {
8  'X-Auth-Token': ACCESS_TOKEN,
9  'Content-Type': 'application/json',
10  Accept: 'application/json',
11};
12
13export async function GET(request: NextRequest) {
14  const { searchParams } = new URL(request.url);
15  const page = searchParams.get('page') ?? '1';
16  const keyword = searchParams.get('keyword') ?? '';
17  const limit = searchParams.get('limit') ?? '12';
18
19  const params = new URLSearchParams({
20    limit,
21    page,
22    include: 'images,variants',
23    ...(keyword && { keyword }),
24  });
25
26  const res = await fetch(`${BC_BASE}/catalog/products?${params}`, {
27    headers: bcHeaders,
28    next: { revalidate: 60 }, // Cache for 60 seconds with ISR
29  });
30
31  if (!res.ok) {
32    return Response.json({ error: 'Failed to fetch products' }, { status: res.status });
33  }
34
35  const { data, meta } = await res.json();
36  return Response.json({ products: data, pagination: meta.pagination });
37}

Create a separate API route for cart operations at app/api/bigcommerce/cart/route.ts. Cart management is the most complex part of a headless BigCommerce storefront because you need to track the cart ID across requests. BigCommerce creates a cart with a UUID when you first add an item — you must store this UUID on the client (in localStorage or a cookie) and send it with every subsequent cart operation. The POST handler handles two cases: creating a new cart (no cartId) and adding to an existing cart (cartId provided). For a new cart, POST to /v3/carts with line_items containing the product ID, variant ID, and quantity. BigCommerce returns the full cart object including the cart ID. For adding to an existing cart, POST to /v3/carts/{cartId}/items. The GET handler retrieves the full cart by ID and also generates a fresh checkout redirect URL. The checkout URL is critical — fetch it from /v3/carts/{cartId}/redirect_urls to get a one-time URL that sends the customer to BigCommerce's PCI-compliant checkout. The DELETE handler removes items from the cart using the line item ID. Always include variant_id in add-to-cart requests even for products without variants — use the default variant ID from the product's variants array. BigCommerce returns a 422 error if variant_id is missing for products that require it.

1import { NextRequest } from 'next/server';
2
3const STORE_HASH = process.env.BIGCOMMERCE_STORE_HASH!;
4const ACCESS_TOKEN = process.env.BIGCOMMERCE_ACCESS_TOKEN!;
5const BC_BASE = `https://api.bigcommerce.com/stores/${STORE_HASH}/v3`;
6
7const bcHeaders = {
8  'X-Auth-Token': ACCESS_TOKEN,
9  'Content-Type': 'application/json',
10  Accept: 'application/json',
11};
12
13export async function POST(request: NextRequest) {
14  const { cartId, productId, variantId, quantity = 1 } = await request.json();
15
16  if (cartId) {
17    // Add to existing cart
18    const res = await fetch(`${BC_BASE}/carts/${cartId}/items`, {
19      method: 'POST',
20      headers: bcHeaders,
21      body: JSON.stringify({
22        line_items: [{ product_id: productId, variant_id: variantId, quantity }],
23      }),
24    });
25    const cart = await res.json();
26    return Response.json(cart.data ?? cart, { status: res.ok ? 200 : res.status });
27  }
28
29  // Create a new cart
30  const res = await fetch(`${BC_BASE}/carts`, {
31    method: 'POST',
32    headers: bcHeaders,
33    body: JSON.stringify({
34      line_items: [{ product_id: productId, variant_id: variantId, quantity }],
35    }),
36  });
37  const cart = await res.json();
38  return Response.json(cart.data ?? cart, { status: res.ok ? 201 : res.status });
39}
40
41export async function GET(request: NextRequest) {
42  const { searchParams } = new URL(request.url);
43  const cartId = searchParams.get('cartId');
44  if (!cartId) return Response.json({ error: 'cartId required' }, { status: 400 });
45
46  const [cartRes, redirectRes] = await Promise.all([
47    fetch(`${BC_BASE}/carts/${cartId}?include=redirect_urls`, { headers: bcHeaders }),
48    fetch(`${BC_BASE}/carts/${cartId}/redirect_urls`, { method: 'POST', headers: bcHeaders }),
49  ]);
50
51  const cartData = await cartRes.json();
52  const redirectData = await redirectRes.json();
53
54  return Response.json({
55    cart: cartData.data,
56    checkoutUrl: redirectData.data?.checkout_url,
57  });
58}

Add your BigCommerce credentials to Vercel's environment variable system. Connect your V0 project to GitHub using V0's Git panel, then open your Vercel project at vercel.com/dashboard. Go to Settings → Environment Variables and add: BIGCOMMERCE_STORE_HASH (your store-xxxxxxxx value), BIGCOMMERCE_ACCESS_TOKEN (your access token from the API account), and optionally BIGCOMMERCE_STOREFRONT_TOKEN if you plan to use the GraphQL Storefront API. Check all three environment scopes: Production, Preview, and Development. None of these should use the NEXT_PUBLIC_ prefix — all BigCommerce API calls must be server-side. Click Save after each variable, then trigger a redeployment. For local development, create .env.local with the same variables. After deployment, test the full flow: load the catalog page (products should appear from BigCommerce), add a product to the cart, verify the cart shows the correct item, and click checkout to confirm the redirect to BigCommerce's hosted checkout page. One important V0 limitation: the browser preview cannot call the BigCommerce API, so all API testing must happen on a Vercel deployment. Use Vercel preview deployments (created automatically for each GitHub branch push) to test API integrations before merging to production. For production BigCommerce stores with complex catalog structures, custom fields, and multi-channel configurations, RapidDev can help architect the full headless storefront integration.

1# .env.local — never commit to git
2BIGCOMMERCE_STORE_HASH=store-xxxxxxxx
3BIGCOMMERCE_ACCESS_TOKEN=your_access_token_here
4BIGCOMMERCE_STOREFRONT_TOKEN=your_storefront_token_here