Bolt

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

Suggest Edits

There are three main components to integrating Bolt checkout:

  1. Add track.js.
  2. Configure connect.js.
  3. Add the Bolt Checkout button.

Add track.js

Add track.js to all the pages of your shopping cart. Use the code shown below.

<script
  id="bolt-track"
  type="text/javascript"
  src="{CDN_URL}/track.js"
  data-publishable-key="{PUBLISHABLE_KEY}">
</script>

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.

Then Add connect.js to all pages that will have the Bolt Checkout button. Use the code shown below.

<script
  id="bolt-connect"
  type="text/javascript"
  src="{CDN_URL}/connect.js"
  data-publishable-key="{PUBLISHABLE_KEY}">
</script>

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

Responsive
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>

Flexible
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

Color
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-button-hover-color:#1a9900;"></div>

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(address) {
    // This function is called when the user proceeds to the shipping options page.
    // This is applicable only to multi-step checkout.
    // When available the first parameter will contain a user's name and address info.
  },
  
  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.
    callback();
  },
  
  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);

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

onShippingDetailsComplete address

We pass an address object as the first argument to the onShippingDetails callback when a user has entered their shipping information. This object will contain the name and address of a user as entered (not validated) on a best effort basis and may not always be present. Please also note onShippingDetails callback may execute multiple times depending on how a user navigates the checkout flow. The address object will take the following form:

{
  street_address: "4900 Marie P DeBartolo Way",
  street_address2: "",
  locality: "Santa Clara",
  region: "California",
  postal_code: "95054",
  company: "",
  country: "United States",
  country_code: "US",
  first_name: "John",
  last_name: "Smith",
  phone: "4085551212",
  email: "[email protected]"
}

Checkpoint

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

Pre-filling 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 hints = {
  "prefill": {
    "firstName": "Bolt",
    "lastName": "User",
    "email": "[email protected]",
    "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);

Notes:

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

Debugging

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 the CDN_URL?

Sandbox: https://connect-sandbox.bolt.com
Production: https://connect.bolt.com

FAQ: What is hints? Why is it empty?

Hints are special values sent to checkout. Generally it is 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: Which 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 provided by your Bolt Implementation Engineer or Customer Success Manager.

Facebook Pixel Integration

With Facebook Pixel, you can configure to track revenue details, checkout funnels, and any passive data that the Pixel can collect. However, Bolt replaces the standard checkout and this interferes with the usual triggers for Facebook Pixel. To ensure Bolt does not impact your Pixel analytics, Bolt provides javascript code that can be injected your site.

Creating a Facebook Pixel

If you need to create a Facebook Pixel you can go Here. Use the Manual installation instructions. This will provide you with a pixel base code to add to you website.

Follow these steps to inject the code:

  1. Find the header of your website, or locate the header template in your CMS or ecommerce platform.
  2. Paste the pixel base code at the bottom of the header section, just above the closing head tag.
  3. On you cart page inject the code below.

The Facebook Pixel events correspond to Bolt's onCheckoutStart, Success, and onPaymentSubmit.

// Paste this snippet in the success callback for revenue tracking
fbq('track', 'Purchase', {
  value: transaction.amount.amount / 100,
  currency: 'USD',
});

// Paste this snippet in onPaymentSubmit callback to track payment info
fbq('track', 'AddPaymentInfo');

// Paste this snippet in onCheckoutStart callback to track checkout initiations
fbq('track', 'InitiateCheckout');

// FOR EXAMPLE

var callbacks = {
  onCheckoutStart: function() {
    fbq('track', 'InitiateCheckout');
  },
  success: function(transaction, callback) {
    fbq('track', 'Purchase', {
      value: transaction.amount.amount / 100,
      currency: 'USD',
    });
    callback();
  }
}

Verifying if events are tracked

To help you verify if your events are being tracked we recommend installing Facebook Pixel Helper .

When installed you'll have a plugin like this that will tell you when events are fired:

Remember to pause your AdBlocker to have this plugin to work.

Updated about a month ago

What's Next

3. Shipping and Tax API

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.