How to Integrate Bolt.new with Shift4Shop

Shift4Shop uses a three-part authentication system that you include as HTTP request headers on every API call. Understanding each credential's purpose helps you use them correctly and securely. To generate credentials: log into your Shift4Shop admin panel, go to Settings (gear icon) → API → REST API. If you haven't enabled the REST API, toggle it on. Click Generate to create a new API access token. Shift4Shop shows you three values: 1. SecureURL — This is the base URL for all your API calls. It looks like `https://api.shift4shop.com/v3/{your-store-id}`. Every API request goes to this URL plus the endpoint path (e.g., `/Products`, `/Orders`). 2. PublicToken — A token that can be used for read-only catalog operations. Some integrations use this in client-side code for public data like product listings. However, for consistency and security, this guide uses it server-side only in API routes. 3. PrivateKey — This is the sensitive credential that authenticates write operations and access to order/customer data. It must never appear in client-side code, NEXT_PUBLIC_ environment variables, or be committed to Git. All three headers are sent together on every request: `SecureURL`, `PublicToken`, and `PrivateKey` as HTTP headers. The Shift4Shop API is RESTful with standard HTTP verbs (GET for reads, POST for creates, PUT for updates, DELETE for deletions) and returns JSON. Add all three values to your .env file in Bolt. The Shift4Shop REST API accepts HTTPS requests, and these outbound calls work correctly in Bolt's WebContainer during development.

1// lib/shift4shop.ts
2const getCredentials = () => {
3  const secureUrl = process.env.SHIFT4SHOP_SECURE_URL;
4  const publicToken = process.env.SHIFT4SHOP_PUBLIC_TOKEN;
5  const privateKey = process.env.SHIFT4SHOP_PRIVATE_KEY;
6
7  if (!secureUrl || !publicToken || !privateKey) {
8    throw new Error(
9      'Missing Shift4Shop credentials. Set SHIFT4SHOP_SECURE_URL, ' +
10      'SHIFT4SHOP_PUBLIC_TOKEN, and SHIFT4SHOP_PRIVATE_KEY in .env'
11    );
12  }
13  return { secureUrl, publicToken, privateKey };
14};
15
16export async function shift4shopFetch<T = unknown>(
17  endpoint: string,
18  init: RequestInit = {}
19): Promise<T> {
20  const { secureUrl, publicToken, privateKey } = getCredentials();
21  const url = `${secureUrl}${endpoint.startsWith('/') ? endpoint : '/' + endpoint}`;
22
23  const response = await fetch(url, {
24    ...init,
25    headers: {
26      SecureURL: secureUrl,
27      PublicToken: publicToken,
28      PrivateKey: privateKey,
29      'Content-Type': 'application/json',
30      Accept: 'application/json',
31      ...init.headers,
32    },
33  });
34
35  if (!response.ok) {
36    const errorText = await response.text();
37    throw new Error(`Shift4Shop API ${response.status}: ${errorText}`);
38  }
39
40  return response.json() as Promise<T>;
41}

The Shift4Shop Products endpoint (`GET /Products`) returns your store's full product catalog with rich data including name, description, SKU, price, sale price, stock levels, categories, images, and custom fields. This is the foundation for any custom storefront or catalog integration. The Products endpoint supports several useful query parameters for pagination and filtering. `countonly=1` returns just the count of matching products — useful for determining how many pages to show. `offset` and `limit` control pagination (max 200 per request). `categoryid` filters by category. `hide=false` returns only active/visible products. For custom storefronts, you typically want `hide=false` to match what your live store shows. Product images are returned in the `Images` array — the first image is typically the primary product image. Each image object includes `Url` (the full CDN URL) and `AltText`. Shift4Shop hosts these images on their CDN, so you can use the URLs directly in your React components without any additional asset handling. Inventory data is included in the product response as `Stock`, `StockAlert` (the low stock threshold), and `InventoryControl` (whether stock tracking is enabled for this product). This makes it easy to build inventory-aware UIs — showing 'Out of Stock' badges, filtering to in-stock products only, or building the inventory alert dashboard described in the use cases. For large catalogs, implement pagination in your API route using `offset` and `limit` parameters. A catalog with 500+ products should never be fetched in one call — load the first page immediately and implement infinite scroll or 'load more' pagination in your React component.

1// app/api/shift4shop/products/route.ts
2import { NextRequest, NextResponse } from 'next/server';
3import { shift4shopFetch } from '@/lib/shift4shop';
4
5interface Shift4ShopProduct {
6  CatalogID: number;
7  SKU: string;
8  Name: string;
9  Price: number;
10  SalePrice: number;
11  Stock: number;
12  Hide: boolean;
13  Images: Array<{ Url: string; AltText: string }>;
14  CategoryID: number;
15}
16
17export async function GET(request: NextRequest) {
18  const { searchParams } = new URL(request.url);
19  const limit = Math.min(Number(searchParams.get('limit') ?? 20), 200);
20  const offset = Number(searchParams.get('offset') ?? 0);
21  const categoryId = searchParams.get('categoryId');
22  const inStockOnly = searchParams.get('inStockOnly') === 'true';
23
24  const params = new URLSearchParams({
25    limit: limit.toString(),
26    offset: offset.toString(),
27    hide: 'false',
28  });
29  if (categoryId) params.set('categoryid', categoryId);
30
31  const products = await shift4shopFetch<Shift4ShopProduct[]>(
32    `/Products?${params.toString()}`
33  );
34
35  const normalized = products
36    .filter(p => !inStockOnly || p.Stock > 0)
37    .map(p => ({
38      id: p.CatalogID,
39      sku: p.SKU,
40      name: p.Name,
41      price: p.Price,
42      salePrice: p.SalePrice > 0 && p.SalePrice < p.Price ? p.SalePrice : null,
43      stock: p.Stock,
44      isInStock: p.Stock > 0,
45      thumbnail: p.Images?.[0]?.Url ?? null,
46    }));
47
48  return NextResponse.json({ products: normalized, offset, limit });
49}

The Shift4Shop Orders endpoint (`GET /Orders`) returns all orders with full details including customer information, line items, shipping method, order status, and payment status. This is the data your fulfillment team needs to process and ship orders. Shift4Shop uses numeric status codes for order status. The key ones are: 1 (New), 2 (Processing), 3 (Awaiting Fulfillment), 4 (Shipped), 5 (Cancelled), 6 (Declined), 7 (Awaiting Payment), 8 (Backordered), 9 (Awaiting Shipment), 12 (Refunded). For a fulfillment dashboard, you typically filter to status 1 (New), 2 (Processing), and 9 (Awaiting Shipment). Orders include the `OrderItems` array with each line item's product name, SKU, quantity, unit price, and the order subtotal, shipping cost, tax amount, and total. The `ShipmentList` array shows any shipments created for the order with tracking numbers. Customer data is embedded in the order: `BillingFirstName`, `BillingLastName`, `BillingEmail`, and the `ShipFirstName`, `ShipLastName`, `ShipAddress` fields for the delivery address. All the information your team needs to print a packing slip or verify an address is in one API call. For the dashboard, a well-organized order table dramatically speeds up fulfillment workflows. Show order number, customer name, destination city/state, item count, order total, and status badge. Make the order number clickable to expand a drawer showing full line items and customer details. Add a status filter dropdown so the team can focus on orders needing attention.

1// app/api/shift4shop/orders/route.ts
2import { NextRequest, NextResponse } from 'next/server';
3import { shift4shopFetch } from '@/lib/shift4shop';
4
5const STATUS_LABELS: Record<number, string> = {
6  1: 'New',
7  2: 'Processing',
8  3: 'Awaiting Fulfillment',
9  4: 'Shipped',
10  5: 'Cancelled',
11  6: 'Declined',
12  7: 'Awaiting Payment',
13  8: 'Backordered',
14  9: 'Awaiting Shipment',
15  12: 'Refunded',
16};
17
18interface Shift4ShopOrder {
19  InvoiceNumber: number;
20  InvoiceDate: string;
21  BillingFirstName: string;
22  BillingLastName: string;
23  BillingEmail: string;
24  OrderStatus: number;
25  OrderItems: unknown[];
26  OrderAmount: number;
27  ShipCity: string;
28  ShipState: string;
29  ShipCountry: string;
30}
31
32export async function GET(request: NextRequest) {
33  const { searchParams } = new URL(request.url);
34  const status = searchParams.get('status');
35  const limit = searchParams.get('limit') ?? '50';
36  const offset = searchParams.get('offset') ?? '0';
37
38  const params = new URLSearchParams({ limit, offset });
39  if (status) params.set('StatusID', status);
40
41  const orders = await shift4shopFetch<Shift4ShopOrder[]>(
42    `/Orders?${params.toString()}`
43  );
44
45  const normalized = orders.map(o => ({
46    id: o.InvoiceNumber,
47    orderDate: o.InvoiceDate,
48    customerName: `${o.BillingFirstName} ${o.BillingLastName}`.trim(),
49    customerEmail: o.BillingEmail,
50    status: o.OrderStatus,
51    statusLabel: STATUS_LABELS[o.OrderStatus] ?? `Status ${o.OrderStatus}`,
52    itemCount: o.OrderItems?.length ?? 0,
53    total: o.OrderAmount,
54    shippingAddress: {
55      city: o.ShipCity,
56      state: o.ShipState,
57      country: o.ShipCountry,
58    },
59  }));
60
61  return NextResponse.json({ orders: normalized });
62}

Outbound Shift4Shop API calls work flawlessly during Bolt.new development in the WebContainer — fetching products, orders, and inventory all function correctly in the preview environment. The only functionality that requires deployment is Shift4Shop's real-time notification system, which uses webhooks to push order and shipment events to your app. Shift4Shop offers webhook notifications (called 'Callbacks' in their interface) for events including new orders, order status changes, and inventory updates. These are POST requests sent from Shift4Shop servers to your endpoint URL. Since Bolt.new's WebContainer has no persistent public URL and cannot receive incoming HTTP connections, these notifications cannot reach your app during development. To deploy and configure webhooks: click Deploy in Bolt.new and connect your Netlify account. After deployment succeeds, go to your Netlify dashboard → Site Configuration → Environment Variables and add all three Shift4Shop credentials: `SHIFT4SHOP_SECURE_URL`, `SHIFT4SHOP_PUBLIC_TOKEN`, and `SHIFT4SHOP_PRIVATE_KEY`. Trigger a redeploy to apply the variables. For Shift4Shop webhooks: log into your Shift4Shop admin, go to Settings → API → Webhooks (or Callbacks depending on your version). Add a new webhook pointing to `https://your-app.netlify.app/api/shift4shop/webhook` for Order events. Shift4Shop sends a POST with the order number when triggered — your handler then calls back to the Shift4Shop API using the order number to fetch full details. This two-step pattern (notification → fetch) is common in e-commerce platform webhooks. A practical use case for the webhook: send an order confirmation email via SendGrid when Shift4Shop posts a new order notification. The webhook receives the order ID, your handler fetches the full order details from Shift4Shop, and then sends a branded email to the customer.

1// app/api/shift4shop/webhook/route.ts
2import { NextRequest, NextResponse } from 'next/server';
3import { shift4shopFetch } from '@/lib/shift4shop';
4
5// IMPORTANT: Shift4Shop webhooks require a publicly deployed URL.
6// During Bolt.new WebContainer development, incoming webhook callbacks
7// cannot be received. Deploy to Netlify first, then configure your
8// webhook URL in Shift4Shop Admin → Settings → API → Webhooks.
9export async function POST(request: NextRequest) {
10  try {
11    const body = await request.json();
12    const orderId = body.InvoiceNumber ?? body.orderId;
13
14    if (orderId) {
15      // Fetch full order details using the order ID from the notification
16      const orders = await shift4shopFetch<unknown[]>(
17        `/Orders?InvoiceNumber=${orderId}`
18      );
19      const order = Array.isArray(orders) ? orders[0] : orders;
20
21      if (order) {
22        const o = order as Record<string, unknown>;
23        console.log(
24          `New Shift4Shop order #${orderId}: ` +
25          `${o.BillingFirstName} ${o.BillingLastName} — ` +
26          `$${o.OrderAmount}`
27        );
28        // TODO: Send order confirmation email, update internal database, etc.
29      }
30    }
31  } catch (error) {
32    // Log but don't expose — always return 200 to acknowledge receipt
33    console.error('Shift4Shop webhook error:', error);
34  }
35
36  // Always return 200 to prevent Shift4Shop from retrying
37  return NextResponse.json({ received: true });
38}