Quick Start

To initiate the Bolt Checkout experience, retrieve the seller information and install the Checkout Button. Refer to the instructions in the article below.

Step 1: Get Seller Information

Use the CheckoutHelpers module to fetch seller details.

API Reference

Function: getSellerInfo

Parameters

Name	Type	Required	Description
`publishableKey`	string	✅	Your Bolt publishable key. You can find this value in the Merchant Dashboard.
`marketplaceSubMerchantID`	string	✅	The identifier of the seller in your marketplace.
`isTestEnv`	boolean	❌	`true` for sandbox; `false` for production (default: `false`).

Returns

Name	Type	Description
`publishableKey`	string	The publishable key of the seller, to be used to initiate checkout.
`onboardingStatus`	string	The current onboarding status: `completed`, `unconfigured`, `under_review`.

Example

import { CheckoutHelpers } from '@boltpay/bolt-connect-sdk';

// Get seller information
const sellerInfo = await CheckoutHelpers.getSellerInfo({
  publishableKey: 'parent_merchant_publishable_key',
  marketplaceSubMerchantID: 'seller_12345',
  isTestEnv: true      // Set to false for production
});

Step 2: Update Storefront Header

To enable the Bolt Checkout experience, add the following two JavaScript tags to your storefront’s head section:

track.js - Gathers essential fraud signals.
connect.js - Displays the Bolt Checkout button and initiates the checkout experience.

Instructions:

Log in to your Storefront Admin Console.
Navigate to your storefront’s header file.
Add the following scripts, replacing the placeholders:

Placeholder	Description
`{PUBLISHABLE_KEY}`	The key retrieved in Step 1.
`{CDN_URL}`	Base URL for loading Bolt scripts based on your environment: Production: `https://connect.bolt.com`, Sandbox: `https://connect-sandbox.bolt.com`

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

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

Step 3: Add Checkout Button Element to Pages

Use the following HTML snippet to display the Bolt Checkout Button on your seller pages. Replace the placeholders as follows:

Placeholder	Description
`{PUBLISHABLE_KEY}`	The key retrieved in Step 1.
`buttonUrlBase`	Base URL for the checkout button based on your environment: Production: `https://connect.bolt.com/v1/checkout_button`, Sandbox: `https://connect-sandbox.bolt.com/v1/checkout_button`

<div data-tid="instant-bolt-checkout-button">
  <object data={`${buttonUrlBase}?publishable_key=${props.publishableKey}`} />
</div>

TIP

This setup is intended for custom cart implementations. To learn more about plugin-based cart setups, refer to the documentation here.

Step 4: Call BoltCheckout.configure

On pages with Bolt Checkout enabled, call BoltCheckout.configure using the order creation Token. To implement product page checkout, call BoltCheckout.configureProductCheckout. See the Custom Cart Installation for more information.

Callbacks

Callbacks run on your storefront domain, not Bolt’s iFrame
The only required callback is success, which must invoke the provided callback() function
Consider adding logic in the close callback to handle order completion or cancellation

Example

var cart = {
  orderToken: '',
}
var hints = {
  prefill: {
    firstName: 'Bolt',
    lastName: 'User',
    email: 'email@example.com',
    phone: '1112223333',
    addressLine1: '1235 Howard St',
    addressLine2: 'Unit D',
    city: 'San Francisco',
    state: 'California',
    zip: '94103',
    country: 'US',
    // ISO Alpha-2 format expected
  },
}
var callbacks = {
  check: function () {
    // This function is called just before the checkout form loads.

    // This is a hook to determine whether Bolt can 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

    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)

Get Frontend Analytics

Bolt also provides JavaScript callbacks during the checkout process that can be used to trigger any frontend analytics events.

TIP

Use the hints object to pre-populate user information when a shopper begins checkout. Hints can also be a Promise; these fields are not required, and any combination may be used.

Passing configure a cart promise

To avoid a situation where the storefront attempts to call Bolt Checkout before it generates an orderToken, Bolt sometimes recommends passing configure a cart promise.

boltCart = new Promise(function (resolve, reject) {
  $.ajax({
    url: '/getOrderToken',
    type: 'POST',
    dataType: 'json',
    contentType: 'application/json;charset=utf-8',
    success: function (data) {
      BoltReturnJSON = JSON.parse(data.d)
      if (BoltReturnJSON.token !== 'none') {
        resolve({
          orderToken: BoltReturnJSON.token,
        })
      }
    },
    error: function (e) {
      reject(e)
    },
  })
})
BoltCheckout.configure(boltCart, hints, callback)

Step 5: Test Checkout

After you have completed the previous sections, conduct a quick test to ensure the Bolt Checkout Button has been successfully implemented.

Confirm track.js is present across all pages where Bolt Checkout is enabled.
Confirm that the Bolt Checkout button is visible.
Confirm the Bolt Checkout modal loads upon selecting checkout.
Confirm Total in Bolt Checkout modal matches the actual cart total.

Styling Options

Refer to our Checkout Button Style Guide for UX best practices when displaying or customizing the Checkout button for your storefront.