How to Integrate Bolt.new with Salesforce Commerce Cloud

Before prompting Bolt.new, collect all four SFCC identifiers you will need. Log in to Salesforce Account Manager (account.demandware.com). Navigate to API Client → Create API Client. Set the grant type to client_credentials and assign the Shopper Login role plus any catalog roles needed. Copy the Client ID and Client Secret. Back in your SFCC Business Manager, find your Organization ID (starts with 'f_ecom_'), your Short Code (an 8-character string like 'kv7kzm78'), and your Site ID (e.g., 'RefArch' or your merchant site ID). The SCAPI base URL pattern is: https://{short-code}.api.commercecloud.salesforce.com. You will also need the SLAS token endpoint: https://{short-code}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{org-id}/oauth2/token. Write all five values down — you will paste them into a .env file in the next step. Never hard-code these values in source files that could be committed to a public repository.

Open Bolt.new and start a new Next.js project. Use the prompt below to generate the core API proxy layer. Bolt's AI will create three Next.js API routes: one for acquiring SLAS guest shopper tokens, one for product search, and one for individual product details. It will also generate TypeScript interfaces for SFCC product and basket objects, a server-side token cache using a module-level variable (appropriate for serverless), and a reusable SFCC fetch helper that attaches the Authorization header automatically. Review the generated code carefully — confirm that all process.env references match the variable names in your .env file, that no credentials appear in any file under /app or /components, and that the token helper correctly encodes client_id:client_secret as Base64 for the SLAS client-credentials request. If the AI generates Deno.env.get() patterns from other platforms, ask it to switch to process.env for Next.js.

1// lib/sfcc.ts
2const SFCC_SHORT_CODE = process.env.SFCC_SHORT_CODE!;
3const SFCC_ORG_ID = process.env.SFCC_ORG_ID!;
4const SFCC_SITE_ID = process.env.SFCC_SITE_ID!;
5const SFCC_CLIENT_ID = process.env.SFCC_CLIENT_ID!;
6const SFCC_CLIENT_SECRET = process.env.SFCC_CLIENT_SECRET!;
7
8const BASE_URL = `https://${SFCC_SHORT_CODE}.api.commercecloud.salesforce.com`;
9
10let cachedToken: { token: string; expiresAt: number } | null = null;
11
12export async function getGuestToken(): Promise<string> {
13  if (cachedToken && Date.now() < cachedToken.expiresAt) {
14    return cachedToken.token;
15  }
16  const credentials = Buffer.from(`${SFCC_CLIENT_ID}:${SFCC_CLIENT_SECRET}`).toString('base64');
17  const res = await fetch(
18    `${BASE_URL}/shopper/auth/v1/organizations/${SFCC_ORG_ID}/oauth2/token`,
19    {
20      method: 'POST',
21      headers: {
22        'Authorization': `Basic ${credentials}`,
23        'Content-Type': 'application/x-www-form-urlencoded',
24      },
25      body: new URLSearchParams({
26        grant_type: 'client_credentials',
27        channel_id: SFCC_SITE_ID,
28      }).toString(),
29    }
30  );
31  if (!res.ok) throw new Error(`SLAS token error: ${res.status}`);
32  const data = await res.json();
33  cachedToken = {
34    token: data.access_token,
35    expiresAt: Date.now() + (data.expires_in - 60) * 1000,
36  };
37  return cachedToken.token;
38}
39
40export async function sfccFetch(path: string, init?: RequestInit): Promise<Response> {
41  const token = await getGuestToken();
42  return fetch(`${BASE_URL}${path}`, {
43    ...init,
44    headers: {
45      'Authorization': `Bearer ${token}`,
46      'Content-Type': 'application/json',
47      ...(init?.headers || {}),
48    },
49  });
50}

In Bolt.new's file explorer, open the .env file at the project root (or create one if Bolt did not generate it). Add your five SFCC credentials as environment variables. These variables are server-side only — do not prefix them with NEXT_PUBLIC_ or VITE_, because that would expose them in the client bundle. The .env file is only read by Next.js's server-side runtime; it is never sent to the browser and should never be committed to a public Git repository. After saving the .env file, Bolt's WebContainer will automatically restart the Next.js dev server, picking up the new values. Verify the credentials loaded correctly by opening the browser DevTools Network tab, triggering the product grid, and checking that the /api/sfcc/token response returns a 200 with an access_token field. If you see a 401, the client_id:client_secret encoding is wrong — double-check that there are no trailing spaces in the .env values.

1# .env
2SFCC_CLIENT_ID=your_api_client_id_here
3SFCC_CLIENT_SECRET=your_api_client_secret_here
4SFCC_ORG_ID=f_ecom_your_org_id_here
5SFCC_SHORT_CODE=your8charcode
6SFCC_SITE_ID=YourSiteId

With the API layer working, prompt Bolt to generate the storefront UI components. The product grid, product detail page, and mini-cart will all call your local API routes — not SFCC directly — so they contain no credentials and work safely in the browser. Ask Bolt to add category navigation using the /api/sfcc/categories route (you may need to generate this route too), a product detail modal or page using the /api/sfcc/products/[id] route, and a cart managed via SFCC Shopper Baskets API. For the cart, you will need an additional API route that creates a basket, adds items, and retrieves the current basket state. The basket ID should be stored in localStorage on the client — this is the standard SFCC headless pattern. Bolt can generate all of this from a follow-up prompt. When reviewing the cart code, confirm that the basket ID is read from localStorage before each API call and that the POST /api/sfcc/cart/items route passes the basketId as a path parameter in the SCAPI URL, following the pattern: /checkout/shopper-baskets/v1/organizations/{orgId}/baskets/{basketId}/items.

1// app/api/sfcc/baskets/route.ts
2import { NextResponse } from 'next/server';
3import { sfccFetch } from '@/lib/sfcc';
4
5const ORG_ID = process.env.SFCC_ORG_ID!;
6const SITE_ID = process.env.SFCC_SITE_ID!;
7
8export async function POST() {
9  try {
10    const res = await sfccFetch(
11      `/checkout/shopper-baskets/v1/organizations/${ORG_ID}/baskets?siteId=${SITE_ID}`,
12      { method: 'POST', body: JSON.stringify({}) }
13    );
14    if (!res.ok) {
15      const err = await res.text();
16      return NextResponse.json({ error: err }, { status: res.status });
17    }
18    const basket = await res.json();
19    return NextResponse.json({ basketId: basket.basketId, basket });
20  } catch (error) {
21    return NextResponse.json({ error: String(error) }, { status: 500 });
22  }
23}

Bolt.new's WebContainer is a browser-based runtime — it cannot receive incoming HTTP requests from the outside world. This means SFCC webhook notifications (order status updates, inventory changes) and any OAuth callbacks cannot be tested in the preview. Deploy to Netlify to get a real server environment where your Next.js API routes run as proper serverless functions. In Bolt.new, go to Settings → Applications and connect your Netlify account via OAuth. Click Publish to trigger the first deploy. Once Bolt shows you the live Netlify URL, open the Netlify dashboard, go to Site Settings → Environment Variables, and add all five SFCC variables: SFCC_CLIENT_ID, SFCC_CLIENT_SECRET, SFCC_ORG_ID, SFCC_SHORT_CODE, and SFCC_SITE_ID. Click 'Trigger redeploy' so Netlify rebuilds with the new variables. Test the deployed URL to confirm real SFCC data loads. For SFCC order confirmation webhooks or inventory hooks, register the Netlify URL (e.g., https://your-site.netlify.app/api/sfcc/webhooks) as the endpoint in SFCC Business Manager → Order Notifications. Never use the Bolt preview URL as a webhook target — it only exists while the WebContainer is running in your browser tab.

1// app/api/sfcc/webhooks/route.ts
2import { NextResponse } from 'next/server';
3import { createHmac } from 'crypto';
4
5export async function POST(request: Request) {
6  const body = await request.text();
7  const signature = request.headers.get('x-sfcc-signature') ?? '';
8  const secret = process.env.SFCC_WEBHOOK_SECRET ?? '';
9
10  if (secret) {
11    const expected = createHmac('sha256', secret).update(body).digest('hex');
12    if (signature !== expected) {
13      return NextResponse.json({ error: 'Invalid signature' }, { status: 401 });
14    }
15  }
16
17  const payload = JSON.parse(body);
18  console.log('SFCC webhook received:', payload.eventType, payload.orderId);
19  // TODO: update database, send confirmation email, etc.
20  return NextResponse.json({ received: true });
21}