Bolt Developer

Welcome to the Bolt developer hub. You'll find comprehensive guides and documentation to help you start working with Bolt as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    Docs

2. Frontend Integration

There are two main components to integrating Bolt checkout.

  1. Inject track.js in all pages.
  2. Configure connect.js.

Inject track.js

Insert track.js in all the pages of your shopping cart. Use the code shown below.


Configure connect.js

There are 4 steps involved in this stage:

  1. Insert connect.js in only those pages which have a Bolt checkout button
  2. Add the bolt checkout button
  3. Define an onSuccess JavaScript method
  4. Call BoltCheckout.configure

Insert connect.js in pages that will have the Bolt checkout button. Use the code shown below.


Add the Bolt Checkout button

Add the Bolt checkout button as shown using the code below.

<div class="bolt-checkout-button bolt-multi-step-checkout"></div>

This will create a checkout button. The checkout button has a default width of 284px, is not responsive, and does not fill its parent container. For a responsive button, or other formatting options, please see the available styling classes below.

You can also specify with-cards class to show credit card logos below the button.

<div class="bolt-checkout-button with-cards"></div>

Styling options

To satisfy various design needs there are multiple possible configurations to further customize the Bolt Checkout button.

Large Width
Specifying .large-width will allow the button to fill its parent container up to a maximum width of 600px. This is useful for forms that have a wider profile or take up the whole page. .large-width can be used in conjunction with .with-cards. When used together, the card issuer logos will center themselves relative to the Checkout button.

<div class="bolt-checkout-button large-width"></div>
Large width button

Large width button

The .responsive option renders the button wider (filling the page) on mobile devices but keeps a fixed size of 264px for desktop browsers.

<div class="bolt-checkout-button responsive"></div> 

The .flexible layout makes the checkout button fill its parent container. This layout is fully responsive and will always fill the space available to it. When the .with-cards option is added in tandem with the .flexible option, the issuer logos are fully responsive and centered relative to the checkout button.

<div class="bolt-checkout-button flexible"></div> 
Flexible checkout button option with different size parent containers

Flexible checkout button option with different size parent containers

If you want to customize the color of the checkout button and the checkout modal there are a few options. Please see the code samples below for examples on how to customize the styles:

The required element is called "--bolt-primary-action-color". This must be followed by a 6 or 8 digit hexadecimal value (note 3, 4 digits are not supported).

You may additionally supply a color to be shown on hover. This optional element is "--bolt-button-hover-color" and must also have a 6 or 8 digit decimal value.

<div class="bolt-checkout-button" style="--bolt-primary-action-color:#339900;"></div>

<div class="bolt-checkout-button" style="--bolt-primary-action-color:#339900;

Bolt offers an additional select set of styling options for a merchant’s Bolt Checkout button. Email Bolt Support to have these custom options applied.

Create an onSuccess javascript method

The onSuccess method will be called when Bolt successfully processes a transaction. This can be used to redirect the user to an order confirmation page.

onSuccess callbacks can fail!

onSuccess can fail and is not guaranteed to be called on a successful payments. This can happen due to a lot of reasons: Internet outage, browser crashes in the middle of processing payments.

You should always rely on API hook notifications to securely create orders in your system.

Call BoltCheckout.configure

Call BoltCheckout.configure in your javascript on pages where we want to enable Bolt checkout. You need to use the token from order creation. We also provide callback hooks during the checkout process, these may be used to trigger analytic events (ex. Google Analytics).

var cart = {
  "orderToken": "<token>"
var hints = {};
var callbacks = {
  check: function() {
    // This function is called just before the checkout form loads.
    // This is a hook to determine whether Bolt can actually proceed
    // with checkout at this point. This function MUST return a boolean.
    return true;
  onCheckoutStart: function() {
    // This function is called after the checkout form is presented to the user.

  onEmailEnter: function(email) {
    // This function is called after the user enters their email address.

  onShippingDetailsComplete: function() {
    // This function is called when the user proceeds to the shipping options page.
    // This is applicable only to multi-step checkout.
  onShippingOptionsComplete: function() {
    // This function is called when the user proceeds to the payment details page.
    // This is applicable only to multi-step checkout.
  onPaymentSubmit: function() {
    // This function is called after the user clicks the pay button.
  success: function(transaction, callback) {
    // This function is called when the Bolt checkout transaction is successful.
    // ... Add your code here ...
    // **IMPORTANT** callback must be executed at the end of this function if `success`
    // is defined.
  close: function() {
    // This function is called when the Bolt checkout modal is closed.
    // This will not be called when create_order endpoint returns a valid URL 
    // and authorization is successful 
BoltCheckout.configure(cart, hints, callbacks);

Cart object can be a Promise. In this case Bolt checkout will wait for the promise to be fulfilled before opening Bolt checkout modal.


Ensure that all the following are true

  • track.js is present in all pages of your store.
  • On pages where Bolt checkout is enabled
    • Ensure that the Bolt checkout button is visible
    • Upon clicking it, it should load the Bolt checkout modal
    • The total shown at the top of the modal should match the actual cart total
  • Completing the checkout must take you to the order confirmation page. You can use the following test credit card number
    • Card number: 4111 1111 1111 3000
    • Expiration: Any future month/year
    • CVV: Any 3 digits

Prefilling user information

If you have access to user data, it is possible to prefill their information in the checkout form. This is done through the hints parameter when you call BoltCheckout.configure:

var cart = {};
var callbacks = {};

var hints = {
  "prefill": {
    "firstName": "Bolt",
    "lastName": "User",
    "email": "",
    "phone": "1112223333",
    "addressLine1": "1235 Howard St",
    "addressLine2": "Unit D",
    "city": "San Francisco",
    "state": "California",
    "zip": "94103",
    "country": "US" // ISO Alpha-2 format expected

BoltCheckout.configure(cart, hints, callbacks);


  • It's not required to provide all fields shown above, any subset will be accepted
  • Merchant scoped accounts and local accounts will take priority in prefilling form fields if present
  • like cart, hints object can be a Promise


No Bolt checkout button
Verify the following

  • The page has the checkout button <div>
  • The page has connect.js

Infinite spinner when I click the checkout button
Verify the following

  • You are using the PUBLISHABLE_KEY in the connect.js <script> tag
  • The domain you are working on has been whitelisted. Contact Bolt to verify this information
  • There are no javascript errors or console errors when you load your ecommerce page hosting the checkout button
  • There are no javascript errors or console errors when you click the button


FAQ: What is hints? Why is it empty?

hints are special values sent to checkout. Generally its an empty map and there is no need to send anything through hints. The only time hints is used is in Merchant Scoped Accounts

FAQ: What CDN_URL value should I use?

If you are still developing and testing, you would need to connect to our sandbox URL. If you are using this for production and real order processing, use our production URLs given below.

Refer to Integration Checklist in "Getting Started" for the actual URLs

2. Frontend Integration

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.