Web checkout

Your storefront loads Bolt's hosted browser runtime and requests a fresh order token from your backend when a shopper opens checkout.

Before you add the client

You need:

Complete prerequisites and readiness and create an order token before connecting a real cart.

Load the hosted scripts

Add both scripts to pages that can open checkout. Use the hosts for the same environment as your publishable key.

<script
  async
  id="bolt-track"
  src="https://connect-sandbox.boltapp.com/track.js"
  data-publishable-key="YOUR_SANDBOX_PUBLISHABLE_KEY"
></script>
<script
  id="bolt-connect"
  src="https://connect-sandbox.boltapp.com/connect.js"
  data-publishable-key="YOUR_SANDBOX_PUBLISHABLE_KEY"
></script>

Keep async and defer off the connect.js tag and load it before the application code that calls Bolt. The script creates window.BoltCheckout before the browser continues to the next script. track.js can remain asynchronous because checkout does not call it directly.

Open checkout from your button

Add a button that your application owns:

<button id="bolt-checkout-button" type="button" disabled>
  Checkout with Bolt
</button>

The example below verifies that the hosted script initialized, requests a token from your backend, configures checkout once for that attempt, and opens the modal.

async function initializeBoltButton() {
  const checkoutButton = document.querySelector("#bolt-checkout-button");
  const BoltCheckout = window.BoltCheckout;

  if (!BoltCheckout?.configure) {
    throw new Error("Bolt Checkout did not load");
  }

  checkoutButton.disabled = false;

  checkoutButton.addEventListener("click", async () => {
    checkoutButton.disabled = true;

    try {
      const response = await fetch("/api/checkout/order-token", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({ cartId: "CURRENT_CART_ID" }),
      });

      if (!response.ok) {
        throw new Error(`Order token request failed: ${response.status}`);
      }

      const { token } = await response.json();
      const configuredCheckout = BoltCheckout.configure(
        { orderToken: token },
        {},
        {
          success: (_transaction, complete) => complete(),
        },
      );

      if (!configuredCheckout?.open) {
        throw new Error("Bolt Checkout could not be configured");
      }

      configuredCheckout.open();
    } finally {
      checkoutButton.disabled = false;
    }
  });
}

initializeBoltButton().catch(console.error);

/api/checkout/order-token is an endpoint in your application, not a Bolt URL. It should build the current cart and call POST /v1/merchant/orders from your server as shown in Create an order token.

Browser callback behavior

The callback object passed to configure is optional. If you provide success, call its completion function after your client-side work finishes so checkout can continue. Frontend events lists every callback, when Bolt calls it, and the onNotify events checkout sends.

Do not make the browser callback your only record of an order. When an order.create Merchant Callback response contains order_received_url, Bolt redirects the shopper there and the browser success and close callbacks do not run. Use server-side callbacks and webhooks for durable processing.

Verify the web client

In sandbox:

1. Load the page and confirm track.js and connect.js return successfully.
2. Select your checkout button and confirm your backend returns an order token.
3. Confirm the Bolt modal opens and its total matches the cart sent by your backend.
4. Complete a checkout with a sandbox test card, then confirm your Merchant Callback handlers receive the expected events.

If the modal does not open or reports cart_error, continue to Custom cart troubleshooting.

SDK boundaries

The web client does not install an npm package. In particular:

• @boltpay/bolt-js supports Bolt Gaming payment-link flows, not this Custom Cart integration.
• @boltpay/bolt-typescript-sdk is a server-side generated API client. Its Orders API is not the Custom Cart POST /v1/merchant/orders order-token contract.

Use the hosted scripts above for the browser and keep the Custom Cart REST call on your backend.