Tickets - Login

Set Up Bolt for BigCommerce

Prerequisite

You must have an approved Bolt account before installing Bolt Checkout to your store. Sign up for a free account.

1. Add a Bolt User to BigCommerce

  1. Log in to BigCommerce.
  2. Navigate to Settings or Account Settings > Users.
  3. Select Create a User Account.
  4. Add dev@bolt.com as a user by completing the following fields:
    • Email: dev@bolt.com
    • Status: Active
    • User Role: Sales Manager
    • System Admin Permissions: (enable the following)
      • Manage Settings
      • Manage Payments
      • Store Design
      • Design Mode
      • Store Logs
    • Enable WebDav: Yes
  5. Save.

BigCommerce automatically sends dev@bolt.me an email to activate the login.

2. Install Plugin

  1. Navigate to Bolt’s page in the BigCommerce eCommerce Apps Marketplace.
  2. Select Get This App.
  3. Select Install > Confirm.

3. Add Webhook Endpoints in Merchant Dashboard

  1. Login to the Bolt Production Merchant Dashboard and Sandbox Merchant Dashboard.
  2. Navigate to Developer > Webhooks.
  3. Scroll to Webhook Endpoints.
  4. Verify the Webhook URL has populated automatically.

Leave this tab open to refer back to in part 4.

4. Add Bolt as Payment Method in BigCommerce

  1. In your browser tab from part 3, navigate to Developer > API > Keys in the Bolt Merchant Dashboard.
  2. Copy the following keys:
    • API Key
    • Signing Secret
    • Publishable Key
  3. In a new tab, Log in to BigCommerce.
  4. Navigate to Store Setup > Payments.
  5. Scroll to Online Payment Methods > Bolt.
  6. Select Setup.
  7. Paste your keys into the required fields.
  8. Save.

For Legacy Migrations: Remember to check your theme files and remove/update any references to your previous API keys. For assistance with this step, reach out to your Customer Success Manager.

5. Choose a Bolt Product

There are two main product options available for merchant using Bolt’s BigCommerce plugin: Full Bolt Checkout with Fraud Protection and Bolt Fraud Protection.

  1. Log in to BigCommerce.
  2. Navigate to Store Setup > Payments.
  3. Scroll to Online Payment Methods > Bolt.
  4. Select Bolt Settings.
  5. Update Configuration Mode to your-product-choice.
  6. Save.

For manual captures, set the Manual Orders Transaction Type to Authorize Only.

6. Add Scripts & Buttons

For this step, you must add Bolt’s scripts and buttons to every page where the cart is displayed in your storefront. This requires a few theme updates. Typically, these updates happen to the following files:

  • templates > components > cart > preview.html
  • templates > components > common > cart-preview.html
  • templates > components > products > add-to-cart.html
  • templates > pages > cart.html

Navigate to Store Front > My Themes > Advanced > Edit Theme Files to view these files.

Add Scripts

  1. Log in to BigCommerce.
  2. Navigate to your theme files.
  3. Add the following scripts to both your sandbox and production environments:
    • Production Script:
      <script
      # Get your PUBLISHABLE_KEY from the Bolt Merchant Dashboard.
        id="bolt-connect"
        type="text/javascript"
        src="https://connect.bolt.com/connect-bigcommerce.js"
        data-publishable-key="{PUBLISHABLE_KEY}"
        data-storefront-api-token="{{settings.storefront_api.token}}"
        route-public-token="{ROUTE_PUBLIC_TOKEN}">
      </script>
      
      <script>
      # This script automatically updates the Bolt cart when an item is added in the cart page.
      var config = { childList: true, subtree: true };
      var totalClassName = "previewCartCheckout-price";
      var totalPrice = "";
      var callback = function(mutationsList) {
          var elms = document.getElementsByClassName(totalClassName);
          if (elms.length == 0) {
              return;
          }
          var newPrice = elms[0].innerHTML;
          if (newPrice !== totalPrice && window.BoltCheckout) {
              window.BoltCheckout.reloadBigCommerceCart();
          }
          totalPrice = newPrice;
      };
      new MutationObserver(callback).observe(document.body, config);
      </script>
      
    • Sandbox Script:
      <script
        # Get your PUBLISHABLE_KEY from the Bolt Merchant Dashboard.
        id="bolt-connect"
        type="text/javascript"
        src="https://connect-sandbox.bolt.com/connect-bigcommerce.js"
        data-publishable-key="{PUBLISHABLE_KEY}"
        data-storefront-api-token="{{settings.storefront_api.token}}"
        route-public-token="{ROUTE_PUBLIC_TOKEN}">
      </script>
      
      <script>
      # This script automatically updates the Bolt cart when an item is added in the cart page.
      var config = { childList: true, subtree: true };
      var totalClassName = "previewCartCheckout-price";
      var totalPrice = "";
      var callback = function(mutationsList) {
          var elms = document.getElementsByClassName(totalClassName);
          if (elms.length == 0) {
              return;
          }
          var newPrice = elms[0].innerHTML;
          if (newPrice !== totalPrice && window.BoltCheckout) {
              window.BoltCheckout.reloadBigCommerceCart();
          }
          totalPrice = newPrice;
      };
      new MutationObserver(callback).observe(document.body, config);
      </script>
      
  4. Replace the PUBLISHABLE_KEY.
  5. Optionally replace the ROUTE_PUBLIC_TOKEN if you plan on using Route shipping insurance.

Add Buttons

  1. Log in to BigCommerce.
  2. Navigate to your theme files.
  3. Add the following to both your production and sandbox environments in the same places where your original checkout button can be found.
    • Production:
      <div data-tid="instant-bolt-checkout-button" style="display:none">
        <object data="https://connect.bolt.com/v1/checkout_button?publishable_key=PUBLISHABLE_KEY">
        </object>
      </div>
      
    • Sandbox:
      <div data-tid="instant-bolt-checkout-button" style="display:none">
        <object data="https://connect-sandbox.bolt.com/v1/checkout_button?publishable_key=PUBLISHABLE_KEY">
        </object>
      </div>
      
  4. Add the following script to hide the original checkout button to prevent it from displaying.
    <script>
            var originalCheckoutButton = document.querySelector(".cart-actions .button--primary");
            var boltButtons = document.getElementsByClassName("bolt-button-wrapper");
            for (var i = 0; i < boltButtons.length; i++) {
                boltButtons[i].style.display = 'block';
            }
            originalCheckoutButton.style.display = 'none';
        </script>
    

The original checkout button’s name may vary depending on your existing theme. Make sure the correct button is named in the querySelector to properly hide it.

Order Statuses & Operations

You can review BigCommerce order statuses and platform operations in our Platform Operations guide.


Optional Checkout Callbacks

Bolt provides optional callbacks during the checkout process that can be used to trigger frontend analytics events. In our BigCommerce integration, callbacks should be defined in the same template file in which Bolt’s connect script is added.

How it Works

After connect-bigcommerce.js executes, a BoltCheckout object is available in global scope. window.BoltCheckout.setClientCustomCallbacks(callbacks) is a function with a single object argument with the following properties: check, onCheckoutStart, onEmailEnter, onShippingDetailsComplete, onShippingOptionsComplete, onPaymentSubmit, success, and close.

setClientCustomCallbacks() cannot be called until BoltCheckout is initialized during the execution of Bolt’s connect script. You should delay the execution using a setInterval method below:

var callbacks = {
    check : function () {
        // Executes just before the checkout form loads.
        // Must return a boolean that will determine if Bolt should proceed with checkout.
        return true;
    },
    onCheckoutStart : function () {
        // Executes after the checkout form is presented to the user
    },
    onEmailEnter: function (email) {
        // Executes after the user enters their email address.
    },
    onShippingDetailsComplete: function (address) {
        // Executes 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 () {
        // Executes when the user proceeds to the payment details page.
        // This is applicable only to multi-step checkout.
    },
    onPaymentSubmit: function () {
        // Executes after the user clicks the pay button.
    },
    success: function (transaction, callback) {
        // Executes when the Bolt checkout transaction is successful.
        // **IMPORTANT** callback() must be executed at the end of the success function
        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
    }
}
var setupCallbacks = setInterval(function() {
    if (typeof(BoltCheckout) != 'undefined') {
        clearInterval(setupCallbacks);
        window.BoltCheckout.setClientCustomCallbacks(callbacks)
    }
}, 100);

Considerations

  • Callbacks are executed from your storefront domain, not Bolt’s IFrame
  • success() is the only required function; it must invoke the callback() method after completing custom code.
  • If redirecting to an order confirmation page, consider adding code to the close function, which checks if an order was completed.

Disable Bolt Plugin

  1. Log in to Bigcommerce. 
  2. Navigate to Store Front > Payments > Online Payment Methods.
  3. Toggle off the Bolt radio button.
  4. Navigate to Store Front > My Themes > Advanced > Edit Theme Files
  5. Comment out the following scripts for each page.html:
    • templates > components > cart > preview.html
    • templates > components > common > cart-preview.html
    • templates > components > products > add-to-cart.html
    • templates > pages > cart.html

Scripts

<!--<script
  id="bolt-connect"
  type="text/javascript"
  src="https://connect.bolt.com/connect-bigcommerce.js"
  data-publishable-key="gQ8isqpsUR6A.Wr413Y6dCpc5.14736a46de3aa31b19c2e603317d68cd340698e21469e452fda30444094c39b9"
  data-shopping-cart-id="BigCommerce">
</script>-->
<!--<script>
    var originalCheckoutButton = document.querySelector(".previewCartCheckout .button.button--primary");
    var boltButtons = document.getElementsByClassName("bolt-button-wrapper");
        for (var i = 0; i < boltButtons.length; i++) {
            boltButtons[i].style.display = 'block';
        }
        originalCheckoutButton.style.display = 'none';
</script>-->
<!--<script>
    var config = { childList: true, subtree: true };
    var totalClassName = "previewCartCheckout-price";
    var totalPrice = "";
    var callback = function(mutationsList) {
        var elms = document.getElementsByClassName(totalClassName);
        if (elms.length == 0) {
            return;
        }
        var newPrice = elms[0].innerHTML;
        if (newPrice !== totalPrice && window.BoltCheckout) {
            window.BoltCheckout.reloadBigCommerceCart();
        }
        totalPrice = newPrice;
    };
    new MutationObserver(callback).observe(document.body, config);
</script>-->

Finally, save and apply all files and Bolt is temporarily disabled. To reenable Bolt, simply uncomment everything.

Related Articles