# Troubleshooting

> Diagnose a custom cart integration from the symptom you can actually see.

Source: https://help.boltapp.com/custom-cart/troubleshooting

## Start here [#start-here]

| What you see                                          | Check first                                                    |
| ----------------------------------------------------- | -------------------------------------------------------------- |
| Order-token request returns an error                  | HTTP status and response body from `POST /v1/merchant/orders`  |
| Checkout does not open                                | Hosted scripts, your order-token endpoint, and Trusted Domains |
| `cart_error` or `undefined_cart`                      | The token or cart passed to `BoltCheckout.configure`           |
| Checkout cannot calculate shipping, tax, or discounts | The corresponding Merchant Callback request and response       |
| Payment succeeds but your system has no order         | The `order.create` callback and transaction webhook logs       |
| Transaction webhooks do not arrive                    | Webhook registration, subscribed events, and response status   |

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 [#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](/custom-cart/create-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.

<span id="check-the-division-has-a-payment-processor" />

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 [#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](/custom-cart/prerequisites#division-and-processor-readiness).

## Checkout does not open [#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](/platforms/direct-api). 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 [#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](/dashboard/account/trusted-domains/).

## `cart_error` names no cause [#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 [#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 [#callbacks-never-arrive]

Confirm the callbacks registered for the division:

```bash title="Request"
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](/custom-cart/prerequisites#find-your-division-id) and [Merchant Callback conventions](/api-reference/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 [#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 [#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.

<Warning>
  Do not use the browser `success` callback as your only order record. Log Merchant Callback requests and responses, and reconcile orders with verified transaction webhooks.
</Warning>

See [browser callback behavior](/platforms/direct-api#browser-callback-behavior) and [Transaction webhooks](/custom-cart/transaction-webhooks).

## Webhooks never arrive [#webhooks-never-arrive]

Confirm the webhook subscriptions registered for the division:

```bash title="Request"
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](/custom-cart/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 [#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.

<span id="crash-during-the-delivery-step" />

## Contact support [#contact-support]

If the checks above do not identify the failure, [contact Bolt Support](/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.