API Quickstart

Use the Bolt API to create orders, authorize payments, manage shopper accounts, and receive webhooks. Your server makes outbound REST calls to Bolt; Bolt makes inbound callbacks to your server for cart, shipping, and tax.

Prerequisites

A Bolt merchant account
Access to the sandbox Merchant Dashboard

Get credentials

Copy these values from Administration → API in your dashboard:

Key	Use
API key	Server-side outbound API calls (`X-API-Key` header)
Signing secret	Verify inbound webhooks and Merchant Callback requests
Publishable key	Client-side SDK initialization (checkout modal, Connect, embeddable components)

Sandbox and production each have separate keys. See API keys for dashboard screenshots and key rotation.

Configure your environment

Store credentials in environment variables. Never commit keys to source control. For production, set BOLT_ENV=production and BOLT_API_BASE_URL=https://api.boltapp.com with production keys.

BOLT_ENV=sandbox
BOLT_API_BASE_URL=https://api-sandbox.boltapp.com
BOLT_API_KEY=your_sandbox_api_key
BOLT_SIGNING_SECRET=your_sandbox_signing_secret
BOLT_PUBLISHABLE_KEY=your_sandbox_publishable_key

Never use sandbox keys against api.boltapp.com or production keys against api-sandbox.boltapp.com. A key from the other environment is rejected as invalid: 403 with error code 1005.

See Environments for CDN URLs, divisions, and approved domains.

Make your first request

List recent transactions in sandbox to confirm your API key and base URL are correct.

interface TransactionsResponse {
  transactions: Array<{ reference: string; status: string }>;
}

const response = await fetch(`${baseUrl}/v1/merchant/transactions`, {
  headers: {
    "X-API-Key": apiKey,
    "Content-Type": "application/json",
  },
});

if (!response.ok) throw new Error(`Request failed: ${response.status}`);

const data = (await response.json()) as TransactionsResponse;

Expected result: HTTP 200 with a JSON response.

If you receive 403 with error code 1005, a key reached Bolt and was rejected: confirm you are using the API key (not the publishable key) and the matching sandbox base URL. That code does not distinguish an invalid key from one whose merchant is no longer active.

If you receive 401 with error code 1015, no X-API-Key header reached Bolt, and this endpoint fell back to checking for a session instead. Check that your client is sending the header. Not every endpoint behaves this way: POST /v1/merchant/orders answers a missing key with 403 and 1005, the same as an invalid one.

See Authentication for inbound HMAC verification, OAuth, and required headers.

How the docs are organized

Section	What it covers
Integration guides	Use-case entry points: checkout, Connect, subscriptions, gaming
Merchant Callback	Endpoints Bolt calls on your server (cart, shipping, tax)
Endpoints	Outbound REST resources: orders, transactions, accounts, webhooks

Response codes

Status	Meaning
`200`	Success
`400`	Invalid parameters. `/v1/` endpoints return `422` for these instead
`401`	Authentication failed. Returned by `/v3/` endpoints, by `/v1/subscriptions/` endpoints as error code `63`, and by some `/v1/merchant/` endpoints as error code `1015`
`403`	`X-API-Key` was rejected on a `/v1/merchant/` endpoint (error code `1005`). On any version, an OAuth token without the required scope, or a resource you do not have permission for (error code `18`)
`404`	Resource not found
`422`	Validation error on a `/v1/` endpoint; `/v3/` returns `400`
`429`	Rate limited
`5xx`	Bolt server error

A rejected API key does not return the same status everywhere. /v1/merchant/ endpoints return 403 with error code 1005, /v1/subscriptions/ endpoints return 401 with error code 63, and /v3/ endpoints return 401. Read the error code rather than the status when you need to tell failures apart, because 403 covers two different things: a request that never authenticated, and one that authenticated and was refused on permissions. 1005 is the API key, 1012 is the publishable key, 1015 is a failed session check, 63 is an unspecified authentication failure, and 18 is a permission or scope problem. /v3/ responses carry no numeric code; read their .tag field instead.

See Errors for Bolt-specific error codes.