Custom cart failures are hard to diagnose because several unrelated causes produce the same message in the browser. This page is organized by what you see, not by what went wrong.

​
Start here

​
cart_error names no cause

cart_error is reported whenever the cart cannot be resolved. The underlying cause is attached internally but is not part of the message, so the same string covers invalid cart contents, a rejected request, a division misconfiguration, and internal errors alike. Treat it as “something about the cart failed” and work through the causes below in order. A related reason, undefined_cart, is distinct and means no cart was supplied at all. If you see that one, the problem is in how you call BoltCheckout.configure.

​
Check that every URL in the cart is publicly reachable

This is the most common cause during local development and the least obvious. If any URL in the cart, image_url in particular, points at localhost or another host that is not resolvable from the internet, the request is rejected at the edge before the API sees it. The rejection is an HTML error page, not JSON, so a client that expects JSON fails with a parse error and never sees a Bolt error code. Confirm it by sending the same cart with image_url omitted. If the call then succeeds, the URL was the cause. For ongoing local work, either omit image_url or serve images through a tunnel.

​
Check the division has a payment processor

Without one, POST /v1/merchant/orders returns 404 with Merchant Primary Processor not found. The browser reports only cart_error. Confirm it by calling the endpoint directly and reading the response body rather than relying on the browser. See prerequisites and readiness.

​
Check your callbacks are succeeding

A failing callback can surface as cart_error. The most common cause is a response Bolt cannot read, usually one missing the required data object. See Merchant Callback conventions.

​
Order creation fails with an unsupported currency

POST /v1/merchant/orders returns 422:
Check the processor before you check your cart. Bolt resolves a maximum transaction amount for the currency, and that lookup needs your processor to be configured for it as a purchase currency. A processor can be connected and still have no configuration for the currency you charge in, which is a different state from having no processor at all. So this error can appear for a currency Bolt fully supports, including USD. If the code in your cart is a valid three letter ISO code, ask Bolt to configure the processor for it rather than changing the cart.

​
Payment succeeded and no order was created

This is the most dangerous failure mode on this page, because nothing in the shopper’s experience indicates a problem. Two distinct causes:
  • Your order.create callback is failing. For a custom cart, Bolt records the failure and allows checkout to continue rather than failing the payment. The shopper is charged and no order reaches your server. Log every callback request and response, and alert on your own error rate, because checkout will not surface this for you.
  • order_received_url is suppressing your success callback. If your order.create response includes order_received_url, Bolt redirects the shopper and the frontend success and close callbacks do not run. A storefront that settles orders in success will never hear about any order. See the checkout button callbacks.
Both causes produce successful payments with no matching orders, and both are invisible from the browser. If you take one action from this page, add logging of your callback responses before you go to production.

​
Callbacks never arrive

Confirm what Bolt has registered:
cURL
The division_id is the second segment of your publishable key; see prerequisites. If your URL is listed and nothing arrives, the division is most likely not set up as a custom cart, which is what grants the Universal Merchant API. If you configured a Universal API URL and the type was unavailable, register the individual create_order, shipping, and tax types instead, which need no capability. See prerequisites and readiness.

​
Webhooks never arrive

A webhook endpoint can save successfully, list back from the API, and never deliver, if the division lacks v2 webhooks. Custom cart divisions have it by default. Check that you registered the endpoint under Administration > Developers > Webhooks and not under Merchant Callbacks, which is a separate system. See transaction webhooks.

​
Crash during the delivery step

An error such as Cannot read properties of undefined (reading 'frontEndShipping') from Bolt’s own bundle means the division’s platform value is one checkout does not recognize. This is not something you can fix from your integration; ask Bolt to confirm the division is set up as a custom cart. Bolt Checkout only runs on registered Trusted Domains, and sandbox does not appear to enforce this the way production does. An integration developed against a tunnel host or an unregistered domain will work in sandbox and stop working on your production domain, with no message pointing at the cause. Register every host that opens checkout under Administration > Trusted Domains. See Trusted Domains.

​
Sandbox hostnames look inconsistent

Both api-sandbox.boltapp.com and api-sandbox.bolt.com serve the sandbox API, and CDN messages sometimes reference connect-sandbox.bolt.com. These are the same systems under two domains. A bolt.com hostname appearing in an error is not a sign you are calling the wrong endpoint.