Set Up SFCC for Bolt

Before You Start

  • Set up a store with a base SFCC storefront cartridge.
  • Download the Bolt cartridge from Github.
  • Obtain your Bolt API credentials.
  • Ensure your store is using SFRA v6.0.

Install Cartridge

  • Login to Business Manager.
  • Navigate to Administration > Sites > Manage Sites and select the Settings tab.
  • Add int_bolt_embedded_sfra to the cartridge path.
  • Unzip the Bolt cartridge and upload it. For detailed instructions on doing this, see Upload Code for SFRA.

Configure Business Manager

The next step is configuring metadata, site preferences, service, payment methods and OCAPI.

Import Metadata

  1. Navigate to Business Manager > Administration > Site Development > Site Import & Export.
  2. Upload the metadata zipfile contained in the cartridge by running the following:
    • npm run zipMetadata
    • npm run uploadMetadata
  3. Navigate to Business Manager > Administration > Open Commerce API Settings.
  4. Copy the metadata under metadata/ocapi/OCAPIshop_embedded.json to the SHOP API section and replace «client_id» with your own client ID, then save.
  5. Copy the metadata under metadata/ocapi/OCAPIdata_embedded.json to the DATA API section and replace «client_id» with your own client ID, then save.

Site Preferences

  1. In Business Manager, navigate to Merchant Tools > Site Preferences > Custom Preferences.
  2. Set the following values in preference group Bolt Payment Setting - Embedded:
    • API Key: Your Bolt API key.
    • Bolt Merchant Division ID: The unique ID associated with the merchant Bolt Account division.
    • Publishable Key: Your Bolt merchant division specific value. The publishable key is a long string of lower and upper case letters and numbers that consists of three sections. publishable key
    • Bolt Environment: String Enum used to switch between different Bolt environment endpoint hostnames. Select either Sandbox, Staging or Production.
    • Enable Bolt Pay: Enable or disable Bolt Pay.
    • Enable Auto Capture: Enable or disable auto-capture.

Payment Method

Ensure Bolt Payments is enabled by navigating to Merchant Tools > Ordering > Payment Methods. BOLT_PAY should be enabled and the payment processor should appear configured.

HTTP Service

Navigate to Administration > Operations > Services and ensure bolt.http is selected.

Authentication Flow

Review the Embedded Checkout diagram to gain insight into how Bolt and your backend work to authenticate customers, populate the Bolt modal, and authorize checkout.

Add Bolt to Template

To include Bolt in your template take the following steps.


  1. In /templates/default/checkout/checkout.isml add the following code snippet before the first <isscript> tag:
<isinclude template="checkout/boltEmbed" />
  1. Add a check for which type of Bolt shopper is checking out:
<div id="checkout-main" class="container data-checkout-stage <isif condition=" ${pdict.order.usingMultiShipping && pdict.order.shipping.length > 1}">multi-ship</isif>" data-customer-type="${pdict.isBoltShopperLoggedIn ? 'boltShopper' : (pdict.customer.registeredUser ? 'registered' : 'guest')}" data-checkout-stage="${pdict.currentStage}"


  1. In /templates/default/checkout/shipping/shipmentCard.isml add the following snippets to the file in the places illustrated by the example below:
<div class="card-body shipping-content">

<form class="shipping-form" autocomplete="on" novalidate
? URLUtils.url('CheckoutAddressServices-AddNewAddress')
: URLUtils.url('CheckoutShippingServices-SubmitShipping')}"
data-address-mode="${((pdict.isBoltShopperLoggedIn && pdict.boltAddressId && !pdict.shippingAddressDataMissing) || shippingModel.matchingAddressId) ? 'edit' : 'new'}"  // This line


<div class="shipping-address ${pdict.order.usingMulitShipping ? 'd-none' : ''}">
    <fieldset class="shipment-selector-block ${(pdict.order.usingMultiShipping || shipmentLoopState) || (pdict.customer.addresses && pdict.customer

|| (pdict.isBoltShopperLoggedIn && pdict.boltStoredShippingAddress) ? '' : 'd-none'} "> // This line

  1. In /templates/default/checkout/shipping/shipmentSelectorOptions.isml before this line
<iselseif condition="${pdict.customer.addresses && pdict.customer.addresses.length > 0}">

…add the following statement:

<isif condition="${pdict.isBoltShopperLoggedIn && pdict.boltStoredShippingAddress}">
   <option disabled>${Resource.msg('msg.account.addresses', 'checkout', null)}</option>
   <isloop items="${pdict.boltStoredShippingAddress}" var="address">
       <option value="${'ab_'}" ${ ? 'selected="selected"' : '' }
       data-first-name="${address.first_name||''}" data-last-name="${address.last_name||''}"
       data-address1="${address.street_address1||''}" data-address2="${address.street_address2||''}"
       data-city="${address.locality||''}" data-state-code="${address.region_code||''}"
       data-country-code="${address.country_code||''}" data-postal-code="${address.postal_code||''}"
       data-phone="${address.phone_number||''}" data-is-gift="${''}" data-gift-message="${''}"
       ${address.first_name || ''} ${address.last_name || ''} ${address.street_address1 || ''} ${address.street_address2 || ''} ${address.locality || ''}${!address.locality || ','} ${address.region_code||''} ${address.postal_code||''}

  1. In /templates/default/checkout/shipping/shippingAddress.isml on line 8, add the following snippet:
<input type="hidden" name="${addressFields.boltAddressId.htmlName}" value="${pdict.boltAddressId}">


  1. In /templates/default/checkout/billing/paymentOptions/paymentOptionsTabs.isml add the following line of code as illustrated by the example below:

<isloop items="${pdict.order.billing.payment.applicablePaymentMethods}" var="paymentOption">
    <isif condition="${paymentOption.ID === 'BOLT_PAY'}"> // This statement
        <isinclude template="checkout/billing/paymentOptions/bolt/paymentTab" />

  1. In /templates/default/checkout/billing/paymentOptions/paymentOptionsContent.isml add following code snippet as illustrated by the example below:
<isloop items="${pdict.order.billing.payment.applicablePaymentMethods}" var="paymentOption">
    <isif condition="${paymentOption.ID === 'BOLT_PAY'}"> // This statement
        <isinclude template="checkout/billing/paymentOptions/bolt/paymentContent" />
  1. In /templates/default/checkout/billing/paymentOptions/paymentOptionsSummary.isml add following code snippet as illustrated by the example below:
<div class="payment-details">
    <isloop items="${pdict.order.billing.payment.selectedPaymentInstruments}" var="payment">
        <isif condition="${payment.paymentMethod === 'BOLT_PAY'}" /> // this statement
	        <isinclude template="checkout/billing/paymentOptions/bolt/paymentSummary" />    


  1. In /forms/default/address.xml add following code snippet on line 6
<field formid="boltAddressId" label="label.input.boltAddressid" type="string" binding="boltAddressId" mandatory="false" />
  1. In /forms/default/billing.xml add following code snippet within the <form></form> tag at the top of the file:
<include formid="boltCreditCard" name="boltCreditCard"/>

Customize Frontend

The Bolt modal relies on the $('#email-guest') SFCC native front end component to trigger a check for the customer’s email and whether they have an existing account.

Bolt also uses the focusout callback on line in the account.js file on line 91 to trigger the call to render the one-time-password modal, and unbinds the event listener after one try. Modify this behavior if needed within account.js.

Edit lines 58 and 84 of /account.js in the cartridge code if you make changes to the $('#email-guest') field.

Data Storage

This integration requires the following system object extensions.

  • OrderPaymentInstrument custom attribute:
    • boltCardBin(String): Store the credit card bin
    • boltPaymentMethodId(String): Bolt Payment Method ID
    • boltCreateAccount(Boolean): Indicates whether the user has chosen to create a Bolt account
    • boltTokenType(String): Bolt token type
  • SitePreferences custom attributes:
    • boltAPIKey(String): Bolt-provided merchant account identifier
    • boltMultiPublishableKey(String): Used to retrieve your Bolt merchant division key
    • boltEnvironment(String): String Enum (Sandbox, Staging, Production); used to switch different Bolt environment endpoint hostnames
    • BoltEnable(Boolean): Indicates whether Bolt is enabled
    • boltMerchantDivisionID(String): Bolt merchant division ID
    • boltEnableAutoCapture(Boolean): Indicate if funds are captured


Bolt embedded adds several new custom logs.

  • Bolt Custom Log: Similar to This log file contains all logs from the int_bolt_embedded_sfra cartridge.
  • Service Communication Logs: These logs contain every request and response to the Bolt API endpoint. To enable these logs, navigate to Administration > Operations > Services > bolt.http and check Communication Log Enabled.
📖On This Page
Filter by Section
Filter by Topic