Merchant Callback conventions

Every Merchant Callback event follows the same rules for how requests arrive, how responses must be shaped, what happens when your endpoint fails, and how to prove a request came from Bolt. Those rules are on this page. The individual event pages cover only the fields specific to each event.

The request envelope

Bolt sends every event as an envelope of event and data, and the payload for that event sits inside data:

{
  "event": "order.shipping",
  "data": {
    "shipping_address": { "postal_code": "94105", "country_code": "US" },
    "cart": { "total_amount": 41200, "currency": "USD" }
  }
}

This is the same whether you registered one Universal Merchant API URL or individual endpoints per event. There is no unwrapped variant. The event names are exact. A common mistake is discount.code.apply, which is not a real event:

Event	Called when	Reference
`order.create`	The shopper submits payment, before authorization	order.create
`order.shipping`	The shopper reaches the delivery step	order.shipping
`order.tax`	The shopper selects a shipping option	order.tax
`order.shipping_and_tax`	Both of the above, combined into one call	order.shipping_and_tax
`discounts.code.apply`	The shopper applies a discount code	discounts.code.apply

The response envelope

Your response uses the same envelope. Echo the event you are answering, set a status, and put the body inside data:

{
  "event": "order.shipping",
  "status": "success",
  "data": {
    "shipping_options": [
      { "service": "Standard", "cost": 500, "reference": "std", "signature": "std-v1" }
    ]
  }
}

Three rules govern whether Bolt accepts it:

Field	Rule
`data`	Required. Bolt reads the response body from `data`, so a response without it is rejected even when you return HTTP 200.
`event`	Must match the event you were sent. A mismatch is treated as a failed call.
`status`	Either `success` or `failure`. Set it accurately: some events, `discounts.code.apply` among them, reject a `failure` payload even when the HTTP status is 200.

A flat response such as {"status": "success", "display_id": "..."} is rejected. HTTP 200 does not make it succeed, because Bolt looks for the body inside data and finds nothing there.

When your endpoint fails

A rejected or failing response does not always stop the checkout. What happens depends on your division, and the custom cart default is the quiet one:

Division	Result
Custom cart, the default	Bolt records the failure and lets checkout continue. The shopper is charged and no order is created on your server.
Divisions configured to fail on abnormal callback errors	Bolt fails the payment.

For a custom cart this means a broken callback produces successful payments with no matching orders, and nothing in the shopper’s experience indicates a problem. Alert on your own callback error rate rather than expecting checkout to surface it. To fail on purpose, set status to failure and return a code. The field differs by event, so check the event’s reference page:

Event	Failure field	Shape
`order.create`	`errors`	An array, read as a deliberate decline. Stops the payment regardless of the division setting above
All other events	`error`	A single object of `code` and `message`

{
  "event": "order.create",
  "status": "failure",
  "errors": [
    { "code": 2001, "data": [{ "reason": "Item out of stock" }] }
  ]
}

{
  "event": "discounts.code.apply",
  "status": "failure",
  "error": {
    "code": 2319,
    "message": "Order total must be more than $100 to apply this discount."
  }
}

See error codes for the codes to use.

Amounts and currency

The same field name can be a number or an object depending on which event you are handling. The rule is that events carrying a full cart snapshot use the expanded form, and events carrying a working cart use plain integers:

Event	`total_amount`	`currency`
`order.shipping`, `order.tax`	`41200`	`"USD"`
`order.create`, `discounts.code.apply`	`{"amount": 41200, "currency": "USD", "currency_symbol": "$"}`	`{"currency": "USD", "currency_symbol": "$"}`

Amounts are always in the currency’s minor units, so 41200 is $412.00.

Type your inbound carts per event rather than sharing one cart model across all of them. Reusing a single strict model is the most common cause of a callback returning an error on one event while working on the others.

Delivery option signatures

Shipping options, pickup options, and ship to store options all carry a signature field. Despite the name it is not a cryptographic value and Bolt does not verify it. It forms part of the cache key for the tax result attached to an option. Give each option a value that is stable for as long as the option means the same thing, and change it whenever the option changes in a way that should invalidate its tax. Omitting it disables tax caching for that option rather than failing the request.

Verifying the request came from Bolt

Every callback is signed. Compute the base64 encoded HMAC SHA-256 of the raw request body using your signing secret, then compare it to the X-Bolt-Hmac-Sha256 header:

TypeScript

import { createHmac, timingSafeEqual } from "node:crypto";

export function isFromBolt(
  rawBody: Buffer,
  headerValue: string,
  signingSecret: string,
): boolean {
  const expected = createHmac("sha256", signingSecret).update(rawBody).digest("base64");
  const a = Buffer.from(expected);
  const b = Buffer.from(headerValue);
  // timingSafeEqual throws unless both buffers are the same length.
  return a.length === b.length && timingSafeEqual(a, b);
}

const { createHmac, timingSafeEqual } = require("node:crypto");

function isFromBolt(rawBody, headerValue, signingSecret) {
  const expected = createHmac("sha256", signingSecret).update(rawBody).digest("base64");
  const a = Buffer.from(expected);
  const b = Buffer.from(headerValue);
  // timingSafeEqual throws unless both buffers are the same length.
  return a.length === b.length && timingSafeEqual(a, b);
}

import base64, hashlib, hmac

def is_from_bolt(raw_body: bytes, header_value: str, signing_secret: str) -> bool:
    digest = hmac.new(signing_secret.encode(), raw_body, hashlib.sha256).digest()
    expected = base64.b64encode(digest).decode()
    return hmac.compare_digest(expected, header_value)

<?php
function isFromBolt(string $rawBody, string $headerValue, string $signingSecret): bool
{
    $expected = base64_encode(hash_hmac('sha256', $rawBody, $signingSecret, true));
    return hash_equals($expected, $headerValue);
}

Sign the raw body exactly as received. Parsing and re-serializing the JSON first changes the bytes and the signature will not match. Two cases differ:

GET endpoints, such as the OAuth login callback, sign the query string rather than a body.
While a signing secret is being rotated, Bolt also sends X-Bolt-Hmac-Sha256-Pending, holding the same body signed with the incoming secret. Accept the request if either header matches, so that verification keeps working across the rotation.

Getting started

Products

SDKs

Custom cart (Direct API)

Platforms

Integration guides

Gaming

Merchant dashboard

Shoppers

Merchant Callback conventions

The request envelope

The response envelope

When your endpoint fails

Amounts and currency

Delivery option signatures

Verifying the request came from Bolt

​The request envelope

​The response envelope

​When your endpoint fails

​Amounts and currency

​Delivery option signatures

​Verifying the request came from Bolt

The request envelope

The response envelope

When your endpoint fails

Amounts and currency

Delivery option signatures

Verifying the request came from Bolt