Troubleshooting

Start here

Work from the first failing stage. A browser error can hide a more specific response from your backend or a Bolt API.

Order-token request fails

Call POST /v1/merchant/orders from your backend and record its HTTP status and response body. Do not diagnose this request only from the browser.

Check these items in order:

1. Confirm the request uses the sandbox API key with api-sandbox.boltapp.com, or the production API key with api.boltapp.com.
2. Confirm the request includes X-API-Key and that the key belongs to the intended merchant account.
3. Compare the payload with Create an order token, including cart totals, item totals, currency, and required fields.
4. Confirm every URL in the cart is reachable from the public internet. During local development, omit optional image URLs or serve them from a public host.

A successful request returns HTTP 200 and an order token.

If the response says Merchant Primary Processor not found, ask Bolt to confirm that a payment processor is connected to the division.

Order creation fails with an unsupported currency

If the response contains currency_not_supported, confirm that cart.currency is a three-letter ISO currency code. If it is valid, ask Bolt to confirm that the division's processor accepts that purchase currency. A connected processor might not support every currency.

See prerequisites and readiness.

Checkout does not open

Use your browser's developer tools to check the client in this order:

1. Confirm track.js and connect.js load successfully from the same environment as the publishable key.
2. Confirm your application's order-token endpoint returns a fresh token without exposing the Bolt API key to the browser.
3. Confirm the storefront host is registered under Administration > Trusted Domains.
4. Confirm your code calls BoltCheckout.configure with the returned token before calling open().

Compare the implementation with Web checkout. For iOS or Android, confirm the app uses the same environment for SDK initialization and order creation.

Modal does not open in production but worked in sandbox

Confirm every production host is registered under Administration > Trusted Domains, including CNAMEs, regional domains, and alternate storefront hosts. Then confirm the production page uses production scripts and a production publishable key. See Register Trusted Domains.

cart_error names no cause

cart_error means checkout could not load the configured cart. Inspect your application's order-token request and the underlying Bolt API response before changing the browser integration.

undefined_cart means checkout did not receive a cart. Confirm that the token returned by your backend reaches BoltCheckout.configure and that you configure checkout after the token request succeeds.

Check that every URL in the cart is publicly reachable

If an optional image_url points to localhost or a private host, remove it and create a new token. If checkout then opens, host the image at a public URL before restoring the field.

Callbacks never arrive

Confirm the callbacks registered for the division:

curl -G https://api-sandbox.boltapp.com/v1/merchant/callbacks \
  -H "X-API-Key: $BOLT_API_KEY" \
  --data-urlencode "division_id=$BOLT_DIVISION_ID"

Then check that:

1. The expected callback type points to the correct public HTTPS endpoint.
2. Your application logs the incoming request and its response.
3. The handler returns a 2xx response with the required response envelope.
4. The handler verifies the Bolt signature before processing the request.

The division ID is the second segment of your publishable key. See Find your division ID and Merchant Callback conventions.

If the URL is registered but Bolt never sends the expected event, ask Bolt to confirm the callback capabilities enabled for the division.

Check your callbacks are succeeding

For shipping, tax, and discount failures, find the request in your server logs and inspect the exact response your handler returned. Confirm the event name, HTTP status, JSON syntax, and required data object against the event's API reference.

Payment succeeded and no order was created

Check whether your server received order.create, what it returned, and whether a transaction webhook arrived for the same order reference. Fix any non-2xx response or invalid response envelope from the callback.

See browser callback behavior and Transaction webhooks.

Webhooks never arrive

Confirm the webhook subscriptions registered for the division:

curl -G https://api-sandbox.boltapp.com/v1/webhooks \
  -H "X-API-Key: $BOLT_API_KEY" \
  --data-urlencode "division_id=$BOLT_DIVISION_ID"

Confirm that the returned subscription has the expected URL and includes the event you are testing. Then check that your handler logs the delivery, verifies its signature, and returns HTTP 200 after accepting it.

Check that you registered the endpoint under Administration > Developers > Webhooks and not under Merchant Callbacks, which is a separate system. See transaction webhooks.

If the subscription is correct and no delivery appears in your logs, ask Bolt to confirm webhook access for the division.

Sandbox hostnames look inconsistent

Use api-sandbox.boltapp.com for API requests and connect-sandbox.boltapp.com for checkout scripts, as shown throughout this guide. Bolt client resources can report a corresponding bolt.com hostname in browser messages; this alone does not indicate an environment mismatch.

Contact support

If the checks above do not identify the failure, contact Bolt Support with:

• Sandbox or production environment
• Division ID and your order reference
• Approximate timestamp and time zone
• Failing stage and steps to reproduce it
• HTTP status and sanitized response body
• Relevant browser, callback, or webhook logs

Remove API keys, signing secrets, payment details, and shopper personal information before sharing logs.