Create an order token

Bolt Checkout will not open without an order token. You create one by sending your cart to POST /v1/merchant/orders, then hand the returned token to the checkout modal. This is the first piece of a custom cart integration and the only one that runs before the shopper sees anything.

Request

Authenticate with your API key in the X-API-Key header. Amounts are integers in the currency’s minor units, so 41200 is $412.00.

TypeScript

type OrderTokenResponse = { token: string };

const response = await fetch(`${baseUrl}/v1/merchant/orders`, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-API-Key": apiKey,
  },
  body: JSON.stringify({
    cart: {
      order_reference: "order_100",
      display_id: "displayid_100",
      currency: "USD",
      total_amount: 41200,
      tax_amount: 900,
      items: [
        {
          name: "Bolt Coffee Mug",
          reference: "sku-mug-01",
          sku: "MUG-01",
          unit_price: 20150,
          total_amount: 40300,
          quantity: 2,
          image_url: "https://example.com/img/mug.png",
        },
      ],
    },
    channel: "browser",
  }),
});

if (!response.ok) {
  throw new Error(`Order token request failed: ${response.status} ${await response.text()}`);
}

const { token } = (await response.json()) as OrderTokenResponse;

const response = await fetch(`${baseUrl}/v1/merchant/orders`, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-API-Key": apiKey,
  },
  body: JSON.stringify({
    cart: {
      order_reference: "order_100",
      display_id: "displayid_100",
      currency: "USD",
      total_amount: 41200,
      tax_amount: 900,
      items: [
        {
          name: "Bolt Coffee Mug",
          reference: "sku-mug-01",
          sku: "MUG-01",
          unit_price: 20150,
          total_amount: 40300,
          quantity: 2,
          image_url: "https://example.com/img/mug.png",
        },
      ],
    },
    channel: "browser",
  }),
});

if (!response.ok) {
  throw new Error(`Order token request failed: ${response.status} ${await response.text()}`);
}

const { token } = await response.json();

curl -X POST https://api-sandbox.boltapp.com/v1/merchant/orders \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $BOLT_API_KEY" \
  -d '{
    "cart": {
      "order_reference": "order_100",
      "display_id": "displayid_100",
      "currency": "USD",
      "total_amount": 41200,
      "tax_amount": 900,
      "items": [
        {
          "name": "Bolt Coffee Mug",
          "reference": "sku-mug-01",
          "sku": "MUG-01",
          "unit_price": 20150,
          "total_amount": 40300,
          "quantity": 2,
          "image_url": "https://example.com/img/mug.png"
        }
      ]
    },
    "channel": "browser"
  }'

total_amount on the cart is the amount the shopper will be charged, including tax and shipping. Bolt does not derive it from the items, so it must already account for tax_amount and any shipment costs you send.

Required fields

Everything not listed here is optional.

Field	Notes
`cart.order_reference`	Your identifier for the order. Must be unique per successful transaction
`cart.currency`	Three letter ISO code, for example `USD`
`cart.total_amount`	Total to charge, in minor units
`cart.items[].name`	The only item field Bolt requires
`cart.items[].unit_price`, `total_amount`, `quantity`	Needed for the modal to display a line item correctly

Two fields are commonly described as required but are not: description and image_url. Omitting them is valid, and omitting image_url is the simplest way to work around the restriction below during local development. channel records where the order originated, either browser or mobile_app. Send it on every request so your transaction reporting attributes orders correctly.

Every URL in the cart, including image_url, must be resolvable from the public internet. A cart pointing at localhost is rejected at the edge before it reaches the API, and the response is an HTML error page rather than JSON, so clients that expect JSON fail with a parse error instead of a Bolt error code. In local development, either omit image_url or serve images through a tunnel.

Response

The token is what you need. cart echoes back what Bolt stored.

{
  "token": "9c8e1f3a2b7d4e5f6a0b1c2d3e4f5a6b",
  "cart": {
    "order_reference": "order_100",
    "display_id": "displayid_100",
    "currency": { "currency": "USD", "currency_symbol": "$" },
    "total_amount": { "amount": 41200, "currency": "USD", "currency_symbol": "$" },
    "tax_amount": { "amount": 900, "currency": "USD", "currency_symbol": "$" },
    "items": [
      {
        "name": "Bolt Coffee Mug",
        "reference": "sku-mug-01",
        "sku": "MUG-01",
        "unit_price": { "amount": 20150, "currency": "USD", "currency_symbol": "$" },
        "total_amount": { "amount": 40300, "currency": "USD", "currency_symbol": "$" },
        "quantity": 2
      }
    ]
  }
}

The response is not the request. Amounts you sent as integers come back as objects of amount, currency, and currency_symbol, and the currency string comes back as an object too. A single type reused for both directions will fail to deserialize the response.

The same split applies to the Merchant Callback events, where which form you receive depends on the event. See Merchant Callback conventions.

Pass token to the checkout modal, then build the Merchant Callback API that Bolt calls during checkout for shipping, tax, discounts, and order creation. Start with Merchant Callback conventions, which covers the rules shared by every event.

Getting started

Products

SDKs

Custom cart (Direct API)

Platforms

Integration guides

Gaming

Merchant dashboard

Shoppers

Create an order token

Request

Required fields

Response

Next

​Request

​Required fields

​Response

​Next

Request

Required fields

Response

Next