Most custom cart integrations that fail at the first attempt fail for one of the reasons on this page, and all of them are settled before a shopper ever reaches checkout. Work through this list before wiring up a storefront.

​
The checklist

The first five are yours to complete. The last one is not, and it is the one that produces the most confusing failures, so it is worth confirming explicitly with Bolt rather than assuming. A connected processor is not the same as a processor configured for the currency you charge in. If order creation fails with currency_not_supported for a currency Bolt does support, the currency in your cart is not the problem: the processor has no configuration for it as a purchase currency. Ask Bolt to add it rather than changing your cart.

​
Trusted Domains

Bolt Checkout only runs on domains registered under Administration > Trusted Domains in the Merchant Dashboard. Register every host that will open checkout, including CNAMEs, regional domains, and any staging host.
Sandbox does not appear to enforce this the way production does. A sandbox integration can complete checkouts from an unregistered host, including a temporary tunnel domain, and the requirement then surfaces in production as “the modal does not open” with nothing pointing at the cause. Register your production domains before you ship, not when checkout breaks.
See Trusted Domains for the dashboard steps.

​
Why the division matters

A Bolt division carries a platform value. A custom cart integration needs a division whose platform is set to custom cart rather than to a commerce platform or left unset. That single setting determines several defaults you depend on:
  • The Universal Merchant API, which lets one URL serve every callback event
  • Transaction webhooks that actually deliver to the endpoints you register
  • Split shipping and tax
  • Pre-authorization order creation
You do not request these individually. A division set up as a custom cart has them, and a division that is not will appear to accept your configuration while silently doing nothing with it. If callbacks never arrive, or a webhook endpoint saves and lists back but never fires, this is the first thing to check with Bolt.

​
Verify what you can

​
Find your division ID

Both checks below need a division_id. It is the second dot-separated segment of your publishable key:
The first segment is not it. Passing it produces the same error as passing nothing.

​
Run the checks

Both require the division_id above. If it is missing or wrong, both return the same response, so the error does not tell you which mistake you made:
It does not mean your API key is wrong. Confirm your callback URLs are registered:
cURL
Confirm your webhook subscriptions:
cURL
On a new account, expect the callbacks check to return a single base_domain entry, which Bolt sets, and the webhooks check to return an empty list. Both are correct at this stage: they mean nothing is configured yet, not that something is broken.
There is no API that reports your division’s platform value or its enabled features. The endpoint that returns division details is authenticated by dashboard session rather than by API key, so it is not available to an integration. Ask Bolt to confirm your division is set up as a custom cart; you cannot check it yourself.

​
Environments and hostnames

Both api-sandbox.boltapp.com and api-sandbox.bolt.com currently serve the sandbox API, and CDN error messages sometimes reference connect-sandbox.bolt.com. These are the same systems under two domains. Prefer the boltapp.com hostnames, and do not treat a bolt.com hostname in an error message as a sign that you are calling the wrong endpoint.

​
Next

With the checklist complete, create an order token.