How to Integrate Bolt.new with ShipStation

ShipStation uses HTTP Basic authentication — one of the simplest auth schemes in any REST API ecosystem. You need two values: an API key and an API secret, both available from your ShipStation account settings. To generate your credentials: log into ShipStation, click your account name in the top-right corner, then go to Account Settings → API Settings. You will see a section called API Keys. Click Generate API Keys. ShipStation immediately shows you both the API Key (a long alphanumeric string) and the API Secret. Copy both — the secret is shown once. Store them somewhere secure like a password manager before adding them to your project. HTTP Basic authentication requires you to Base64-encode the combination `apiKey:apiSecret` and include it in the Authorization header as `Basic <encoded-string>`. In Node.js, this is straightforward: `Buffer.from('key:secret').toString('base64')`. Alternatively, you can use the native `fetch` without manual encoding by passing the credentials directly in the URL as `https://key:secret@ssapi.shipstation.com/...` — but the explicit header approach is cleaner and easier to debug. The base URL for all ShipStation API calls is `https://ssapi.shipstation.com`. All endpoints use this domain with paths like `/orders`, `/shipments`, `/carriers`, etc. Add both credentials to your .env file as shown below — never commit them to Git or use NEXT_PUBLIC_ prefix.

1// lib/shipstation.ts
2const BASE_URL = 'https://ssapi.shipstation.com';
3
4function getAuthHeader(): string {
5  const key = process.env.SHIPSTATION_API_KEY;
6  const secret = process.env.SHIPSTATION_API_SECRET;
7  if (!key || !secret) {
8    throw new Error('SHIPSTATION_API_KEY and SHIPSTATION_API_SECRET must be set');
9  }
10  return 'Basic ' + Buffer.from(`${key}:${secret}`).toString('base64');
11}
12
13export async function shipstationFetch<T = unknown>(
14  endpoint: string,
15  init: RequestInit = {}
16): Promise<T> {
17  const url = `${BASE_URL}${endpoint.startsWith('/') ? endpoint : '/' + endpoint}`;
18  const response = await fetch(url, {
19    ...init,
20    headers: {
21      'Authorization': getAuthHeader(),
22      'Content-Type': 'application/json',
23      ...init.headers,
24    },
25  });
26
27  if (!response.ok) {
28    const errorText = await response.text();
29    throw new Error(`ShipStation API error ${response.status}: ${errorText}`);
30  }
31
32  return response.json() as Promise<T>;
33}

The ShipStation orders endpoint (`GET /orders`) returns paginated order data including recipient details, line items, weight, and current order status. You will build an API route that fetches orders filtered by status and passes them to a React dashboard component. ShipStation orders have several status values you will encounter: `awaiting_payment` (order received, payment not confirmed), `awaiting_shipment` (paid and ready to fulfill — this is the most important queue for fulfillment teams), `shipped` (label created and tracking number assigned), `on_hold`, and `cancelled`. Most fulfillment dashboards focus on `awaiting_shipment` orders. The endpoint supports extensive filtering via query parameters: `orderStatus`, `orderDateStart`, `orderDateEnd`, `storeId` (to filter by sales channel), `sortBy` (OrderDate, ModifyDate), and `sortDir` (ASC or DESC). For pagination, use `page` (1-indexed) and `pageSize` (max 500). A typical dashboard request fetches the first page of `awaiting_shipment` orders sorted by oldest first. The response JSON includes `orders` (array), `total` (total matching orders across all pages), `page`, and `pages`. Build your API route to pass through the full response so your frontend can show pagination controls when there are many orders. In the React component, display the key fields your team needs at a glance: order number, customer name, shipping destination state/country, order total, and item count. A well-organized fulfillment table dramatically speeds up pick-and-pack workflows compared to the default ShipStation interface.

1// app/api/shipstation/orders/route.ts
2import { NextRequest, NextResponse } from 'next/server';
3import { shipstationFetch } from '@/lib/shipstation';
4
5interface ShipStationOrdersResponse {
6  orders: unknown[];
7  total: number;
8  page: number;
9  pages: number;
10}
11
12export async function GET(request: NextRequest) {
13  const { searchParams } = new URL(request.url);
14  const status = searchParams.get('status') ?? 'awaiting_shipment';
15  const page = searchParams.get('page') ?? '1';
16  const pageSize = searchParams.get('pageSize') ?? '50';
17
18  const params = new URLSearchParams({
19    orderStatus: status,
20    page,
21    pageSize,
22    sortBy: 'OrderDate',
23    sortDir: 'ASC',
24  });
25
26  const data = await shipstationFetch<ShipStationOrdersResponse>(
27    `/orders?${params.toString()}`
28  );
29
30  return NextResponse.json(data);
31}

Rate shopping and label creation are the two most valuable ShipStation API capabilities. Instead of logging into ShipStation and manually comparing carrier options, your app can present rates automatically and let users select one to instantly generate a label. For rate shopping, the endpoint is `POST /carriers/listrates`. The request body requires `carrierCode` (or use the special value `stamps_com` for USPS), `serviceCode` (optional — omit to get all services), `fromPostalCode`, `toPostalCode`, `toCountry` (ISO 2-letter code), `weight` (object with `value` and `units` — use `ounces`), and optionally `dimensions` (length, width, height in inches). The response is an array of rate objects, each with `carrierCode`, `serviceCode`, `serviceName`, `shipDate`, `deliveryDays`, and `shipmentCost`. Sort by `shipmentCost` ascending to show cheapest first. For label creation, use `POST /orders/createlabelfororder`. You pass the `orderId` (from the orders list), `carrierCode`, `serviceCode`, and `confirmation` (e.g., `none`, `delivery`, `signature`). ShipStation creates the label in your connected carrier account and returns `shipmentId`, `trackingNumber`, `labelData` (Base64-encoded PDF), and `labelFileToken`. Save the tracking number to your database so you can surface it in order confirmations. Important: calling `createlabelfororder` deducts from your connected carrier account (e.g., Stamps.com credits or UPS account balance) immediately. Use a test carrier or sandbox account during development — ShipStation does not have a separate sandbox environment, so label creation is always live. For rate-only requests (no purchase), ShipStation's rates API does not charge anything — it is a pure quote API.

1// app/api/shipstation/rates/route.ts
2import { NextRequest, NextResponse } from 'next/server';
3import { shipstationFetch } from '@/lib/shipstation';
4
5interface RateResponse {
6  carrierCode: string;
7  serviceCode: string;
8  serviceName: string;
9  shipDate: string;
10  deliveryDays: number;
11  shipmentCost: number;
12  otherCost: number;
13}
14
15export async function POST(request: NextRequest) {
16  const { fromPostalCode, toPostalCode, toCountry, weightOz, dimensions } =
17    await request.json();
18
19  if (!fromPostalCode || !toPostalCode || !weightOz) {
20    return NextResponse.json(
21      { error: 'fromPostalCode, toPostalCode, and weightOz are required' },
22      { status: 400 }
23    );
24  }
25
26  const body: Record<string, unknown> = {
27    carrierCode: 'stamps_com',
28    fromPostalCode,
29    toPostalCode,
30    toCountry: toCountry ?? 'US',
31    weight: { value: weightOz, units: 'ounces' },
32  };
33
34  if (dimensions) {
35    body.dimensions = {
36      length: dimensions.length,
37      width: dimensions.width,
38      height: dimensions.height,
39      units: 'inches',
40    };
41  }
42
43  const rates = await shipstationFetch<RateResponse[]>('/carriers/listrates', {
44    method: 'POST',
45    body: JSON.stringify(body),
46  });
47
48  const sorted = [...rates].sort((a, b) => a.shipmentCost - b.shipmentCost);
49  return NextResponse.json({ rates: sorted });
50}

During development in Bolt.new's WebContainer, all outbound calls to ShipStation work perfectly — you can fetch orders, shop rates, and create labels without any issues. The WebContainer limitation only applies to incoming connections, which affects ShipStation's webhook system. ShipStation webhooks send POST requests to your registered URL when events occur: `ORDER_NOTIFY` (new order arrives), `SHIP_NOTIFY` (shipment created with tracking), `ITEM_ORDER_NOTIFY`, and several others. These real-time notifications are what allow your app to react to fulfillment events — updating order status in your database, sending shipping confirmation emails to customers, or updating inventory levels — without polling the ShipStation API every few minutes. To deploy: click Deploy in Bolt.new and connect to Netlify. After deployment, go to your Netlify dashboard → Site Configuration → Environment Variables and add `SHIPSTATION_API_KEY`, `SHIPSTATION_API_SECRET`, and any other variables you have in .env. Trigger a redeploy. To configure webhooks in ShipStation: go to Account → Account Settings → Webhooks → Add Webhook. Enter your Netlify URL for the webhook endpoint (e.g., `https://your-app.netlify.app/api/shipstation/webhook`), select the event type (`SHIP_NOTIFY` is most commonly needed), choose the store to monitor, and save. ShipStation sends a test POST immediately — your handler should return 200. Webhook payloads from ShipStation include a `resource_url` field rather than the full event data — you must make a second API call to that URL to get the actual shipment or order details. This two-step pattern is intentional and reduces payload size for high-volume accounts.

1// app/api/shipstation/webhook/route.ts
2import { NextRequest, NextResponse } from 'next/server';
3import { shipstationFetch } from '@/lib/shipstation';
4
5interface ShipStationWebhookBody {
6  resource_url: string;
7  resource_type: string;
8}
9
10interface ShipmentResource {
11  shipments: Array<{
12    shipmentId: number;
13    orderId: number;
14    orderKey: string;
15    trackingNumber: string;
16    carrierCode: string;
17    serviceCode: string;
18    shipDate: string;
19    shipmentCost: number;
20  }>;
21}
22
23// NOTE: ShipStation webhooks require a publicly deployed URL.
24// During Bolt.new WebContainer development, incoming webhooks cannot
25// be received. Deploy to Netlify first, then register the webhook URL
26// in ShipStation Account Settings → Webhooks.
27export async function POST(request: NextRequest) {
28  const body: ShipStationWebhookBody = await request.json();
29  const { resource_type, resource_url } = body;
30
31  if (resource_type === 'SHIP_NOTIFY' && resource_url) {
32    // ShipStation sends resource_url — we must fetch the actual data
33    const endpoint = resource_url.replace('https://ssapi.shipstation.com', '');
34    const data = await shipstationFetch<ShipmentResource>(endpoint);
35
36    for (const shipment of data.shipments ?? []) {
37      console.log(
38        `Shipment created: order ${shipment.orderKey}, ` +
39        `tracking ${shipment.trackingNumber} via ${shipment.carrierCode}`
40      );
41      // TODO: Update your database and send tracking email to customer
42    }
43  }
44
45  // Always return 200 — ShipStation retries on non-200 responses
46  return NextResponse.json({ received: true });
47}