How to Integrate Bolt.new with ShipBob

ShipBob uses OAuth 2.0 for all API authentication. For integrating your own ShipBob account, the simplest approach is a Personal Access Token (PAT). Log into your ShipBob account, navigate to the Integrations section, then Developer Tools (or go directly to developer.shipbob.com). Under 'Personal Access Tokens', generate a new token with the scopes you need: read:inventory, write:inventory, read:order, write:order, read:shipment are the core scopes for most integrations. Personal Access Tokens are long-lived and do not expire automatically (you can revoke them). They authenticate as you with your account permissions. This is the right approach for connecting your own ShipBob account to your app. If you are building an app that other ShipBob merchants will connect to (a multi-tenant integration), you need the full OAuth 2.0 authorization code flow — ShipBob has a developer program at developer.shipbob.com where you register an application and get a client ID and client secret for the standard OAuth 2.0 flow. ShipBob's API base URL is https://api.shipbob.com and the current API version is v2.0 (2.0). All endpoints follow the pattern https://api.shipbob.com/2.0/{resource}. Authentication uses the Authorization: Bearer {token} header. The API returns JSON for all responses and uses standard HTTP status codes.

1# ShipBob API base URL and authentication pattern:
2# Base URL: https://api.shipbob.com/2.0/
3# Authentication: Authorization: Bearer {YOUR_ACCESS_TOKEN}
4
5# Key endpoints:
6# GET  /2.0/inventory           — list all inventory (paginated)
7# GET  /2.0/inventory/{id}      — single inventory item
8# GET  /2.0/product             — list products
9# POST /2.0/order               — create fulfillment order
10# GET  /2.0/order/{id}          — get order status
11# GET  /2.0/shipment            — list shipments (filterable by orderId)
12# GET  /2.0/shipment/{id}       — single shipment with tracking

Create a ShipBob API client utility that centralizes authentication and request handling. All ShipBob API calls are server-side — the access token must never be exposed in client-side JavaScript. In Next.js, server-only environment variables (no NEXT_PUBLIC_ prefix) are only accessible in API routes and server components, which is exactly where ShipBob calls should live. The ShipBob API client wraps fetch with the Authorization header and base URL, handles pagination for list endpoints (ShipBob uses page and limit query parameters), and provides consistent error handling. ShipBob returns error details in the response body as a JSON object with a message field — parse these to surface helpful error messages rather than generic 500 errors. Pagination is important for inventory and order endpoints if you have many SKUs or orders. ShipBob's default page size is 250 items, and you can request up to 250 per page (the maximum). For large catalogs, implement pagination in your API routes to avoid fetching thousands of records on every request — instead, pass page and limit parameters from the frontend to your API route and forward them to ShipBob.

1// lib/shipbob.ts
2const BASE_URL = 'https://api.shipbob.com/2.0';
3
4async function shipbobFetch<T>(path: string, options: RequestInit = {}): Promise<T> {
5  const token = process.env.SHIPBOB_ACCESS_TOKEN;
6  if (!token) throw new Error('SHIPBOB_ACCESS_TOKEN is not configured');
7
8  const response = await fetch(`${BASE_URL}${path}`, {
9    ...options,
10    headers: {
11      Authorization: `Bearer ${token}`,
12      'Content-Type': 'application/json',
13      ...options.headers,
14    },
15  });
16
17  if (!response.ok) {
18    const error = await response.json().catch(() => ({ message: response.statusText }));
19    throw new Error(`ShipBob API ${response.status}: ${error.message || JSON.stringify(error)}`);
20  }
21
22  return response.json() as Promise<T>;
23}
24
25export interface ShipBobInventoryItem {
26  id: number;
27  name: string;
28  is_active: boolean;
29  total_fulfillable_quantity: number;
30  total_onhand_quantity: number;
31  total_committed_quantity: number;
32  fulfillable_quantity_by_fulfillment_center: Array<{
33    id: number;
34    name: string;
35    fulfillable_quantity: number;
36  }>;
37}
38
39export const shipbob = {
40  getInventory: (page = 1, limit = 100) =>
41    shipbobFetch<ShipBobInventoryItem[]>(`/inventory?Page=${page}&Limit=${limit}`),
42
43  createOrder: (orderData: object) =>
44    shipbobFetch('/order', { method: 'POST', body: JSON.stringify(orderData) }),
45
46  getOrder: (id: string) => shipbobFetch(`/order/${id}`),
47
48  listShipments: (orderId?: string) =>
49    shipbobFetch(`/shipment${orderId ? `?OrderId=${orderId}` : ''}`),
50};

With the ShipBob client ready, create the API routes your frontend dashboard will call. The inventory endpoint is the most commonly needed — it returns all your products in ShipBob with their current stock levels across fulfillment centers. The order creation endpoint converts your app's order data into ShipBob's expected format and submits the fulfillment request. The ShipBob order creation API requires specific formatting: recipient (shipping address), products (array with ShipBob's internal product ID and quantity), and optional fields like reference_id (your order number), shipping_method, and order_date. Getting the ShipBob product IDs right is critical — they are ShipBob's internal integer IDs, not your own SKUs. Fetch your product list first and maintain a mapping from your SKUs to ShipBob product IDs. For the inventory dashboard, ShipBob's response includes total_fulfillable_quantity (what can be shipped now) and fulfillable_quantity_by_fulfillment_center (breakdown per warehouse). Display both — total tells you if you can fulfill an order, the per-center breakdown helps with restock planning.

1// app/api/shipbob/orders/route.ts
2import { NextResponse } from 'next/server';
3import { shipbob } from '@/lib/shipbob';
4
5export async function POST(request: Request) {
6  try {
7    const body = await request.json();
8    const { referenceId, recipient, products } = body;
9
10    if (!recipient || !products || products.length === 0) {
11      return NextResponse.json(
12        { error: 'recipient and products are required' },
13        { status: 400 }
14      );
15    }
16
17    const shipbobOrder = await shipbob.createOrder({
18      reference_id: referenceId,
19      order_date: new Date().toISOString(),
20      shipping_method: 'Standard',
21      recipient: {
22        name: recipient.name,
23        address: {
24          address1: recipient.address1,
25          city: recipient.city,
26          state: recipient.state,
27          zip_code: recipient.zipCode,
28          country: recipient.country || 'US',
29        },
30      },
31      products: products.map((p: { productId: number; quantity: number }) => ({
32        id: p.productId,
33        quantity: p.quantity,
34        reference_id: referenceId,
35      })),
36    });
37
38    return NextResponse.json(shipbobOrder, { status: 201 });
39  } catch (error: unknown) {
40    const e = error as { message: string };
41    return NextResponse.json({ error: e.message }, { status: 500 });
42  }
43}

The fulfillment dashboard brings the inventory and order data together in a visual interface. The core views are: an inventory table showing all products with their stock levels, highlighted low-stock items, and a per-fulfillment-center breakdown; an orders table showing recent orders with their status; and a shipment detail view for tracking. For the inventory table, display the fulfillable quantity (available to ship immediately) prominently — this is the most actionable number. Show committed quantity (reserved for open orders) and total on-hand quantity as secondary data. Highlight rows where fulfillable quantity falls below a configurable threshold (10-20 units is a common alert level). For the orders view, ShipBob orders have statuses like Processing, Partially Fulfilled, Fulfilled, Exception, Cancelled. Show status badges with appropriate colors. The transition from Processing to Fulfilled is the key event — at this point, a shipment is created and tracking information becomes available. Refresh strategies: inventory data changes throughout the day as orders are fulfilled. Polling every 5 minutes is reasonable for a dashboard. For more real-time updates, ShipBob webhooks push status changes to your app, but webhooks require a deployed URL (not available in the Bolt preview).

All the API routes built so far use outbound calls from your app to ShipBob's API — these work fully in Bolt's WebContainer preview. ShipBob webhooks work in the opposite direction: ShipBob sends HTTP POST requests to your app when events occur (order created, shipment created, order cancelled, inventory updated). Since Bolt's WebContainer has no public URL, you cannot receive ShipBob webhooks during development. Deploy first, then configure webhooks. Deploy to Netlify via Settings → Applications → Netlify in your Bolt project. After deploying, add SHIPBOB_ACCESS_TOKEN to Netlify's environment variables (Site Settings → Environment Variables) and trigger a redeploy. Your deployed app URL will be something like https://your-app-name.netlify.app. To configure ShipBob webhooks: go to the ShipBob Developer Portal, navigate to Webhooks, and create a new webhook subscription. Enter your deployed URL as the endpoint (e.g., https://your-app-name.netlify.app/api/shipbob/webhook), select the event types you want to receive (order_shipped, shipment_delivered, inventory_quantity_changed are the most useful), and save. ShipBob will send a test event to verify the endpoint is reachable. Create the webhook handler route in Bolt, deploy again, and you're receiving real-time fulfillment events.

1// app/api/shipbob/webhook/route.ts
2import { NextResponse } from 'next/server';
3
4interface ShipBobWebhookPayload {
5  topic: string;
6  data: Record<string, unknown>;
7}
8
9export async function POST(request: Request) {
10  try {
11    const payload = await request.json() as ShipBobWebhookPayload;
12    const { topic, data } = payload;
13
14    console.log(`ShipBob webhook received: ${topic}`, JSON.stringify(data).slice(0, 200));
15
16    switch (topic) {
17      case 'order_shipped':
18        // Update order status and store tracking number
19        // await updateOrderStatus(data.order_id, 'shipped', data.tracking_number);
20        break;
21      case 'shipment_delivered':
22        // Mark order as delivered
23        // await updateOrderStatus(data.order_id, 'delivered');
24        break;
25      case 'inventory_quantity_changed':
26        // Log inventory change for dashboard refresh
27        console.log('Inventory change for product:', data.product_id);
28        break;
29      default:
30        console.log(`Unhandled ShipBob event: ${topic}`);
31    }
32
33    // Always return 200 quickly — ShipBob retries if it doesn't receive 200
34    return NextResponse.json({ received: true });
35  } catch (error: unknown) {
36    const e = error as { message: string };
37    console.error('Webhook processing error:', e.message);
38    // Still return 200 to prevent ShipBob retries for parse errors
39    return NextResponse.json({ received: true });
40  }
41}