Installing Bread on Product and Cart Pages

The Bread Shopify App

The Bread Shopify app allows you to place Bread checkout buttons throughout your site, increasing awareness of your financing option and ultimately driving conversions. By placing Bread buttons strategically on your product, cart, and dedicating financing pages, customers are able to pre-qualify and complete a checkout with financing.

Bread button features:

  • Advertise your product in dollars per month in addition to absolute prices
  • Inform customers of additional purchasing power by allowing them to pre-qualify for financing before they even add to cart
  • For pre-qualified customers, immediately convert them into orders with Bread without having to go through a full checkout funnel

Install the Bread App

  1. Install the Bread app by copying the link and replacing YOUR-STORE-NAME with your actual Shopify store name. You can find your Shopify store name in your Shopify admin under SettingsGeneral.
    Note: You will have to replace any spaces in your store name with dashes.
    Example: “Irwins Industries” would result in the link:
  2. You may be prompted to sign into your Shopify admin console.
  3. Click Install unlisted app when prompted to confirm installation of the Bread app.

Once the Bread app is installed you will be redirected to the Bread app configuration page.

Add your Bread API and Secret Keys

You can find the Bread App settings page within your Shopify Admin. Just click on Bread within Apps to find the settings page.


  1. Enter your Bread sandbox API and Secret keys into the fields labeled Sandbox API Key and Sandbox Secret Key. Your sandbox API and Secret keys can be found within your sandbox merchant portal.
  2. Make sure Use sandbox mode is checked.
  3. Later, when you are ready to go live with Bread, you will have to enter your live Bread API and Secret keys in addition to disabling Use sandbox mode.

Note that there are additional important settings to configure, but first we’ll walk through the process of adding Bread buttons to your Shopify product and cart templates. We’ll come back to Bread App Configuration later.

Add Bread Buttons to your Shopify Theme

Placing the Bread button on product and cart pages requires making changes to your product and cart liquid templates in Shopify. To get started, open your Shopify Admin and click Online Store, choose your theme, and then select Edit code from the Action drop down menu.

Find the Right Liquid Template

This process is completely dependent on how your Shopify store theme is organized. Each theme is different which means the right liquid file could be found anywhere including within TemplatesSections, or Snippets.

Bread Button on Product Detail Pages

To find the right the liquid template for your product page, start by looking for the product template containing an “Add to Cart” button. Start with product.liquid and work backwards by looking into the included sections and snippets. Keep looking in sub-files until you find the “Add to Cart” button.

Note that this is general guidance. If your Shopify theme follows a non-standard pattern, you may have to expand your search to other templates.

Once you have located the right product template, insert the following element under your “Add to Cart” button.

{% if product.available %}
<div id="bread-checkout-btn-product" style="width:250px; height:50px; margin:20px 0px;"></div>
{% endif %}

We recommend including Shopify’s product available logic to hide the Bread button when the item is out of stock. Additionally, the heightwidth, and margin of #bread-checkout-btn-product will determine the size and spacing of the Bread button. Modify the example height, width, and margin to fit your product page layout.

Bread Button on Cart Page

For the cart page Bread button, locate the cart template containing a “Checkout” button. Start with cart.liquid – if you can’t find the “Checkout” button there, then work backwards by inspecting the included sections and snippets. Once you have found the right template, insert the following element under your “Checkout” button.

{% if cart.item_count > 0 %}
<div id="bread-checkout-btn" style="height:50px; margin:20px 0px;"></div>
{% endif %}

Fallback Element (Optional)

For a better user experience, we recommend styling the above product and cart elements to appear as buttons. By configuring a fallback element, your customers will still see a complete and coherent page while the Bread button loads, or if it is unavailable.


// Bread button for product pages with fallback element
<div id="bread-checkout-btn-product" style="width:250px; height:50px; background-color:#000; color:#FFF; text-align:center; line-height:50px;">
  Pay Over Time

Check for Responsiveness

Every Shopify theme handles browser width and device (desktop vs mobile) size differently. Open one of your product pages in a desktop browser and shrink/expand the browser horizontally. Similarly, try opening a product page on a mobile phone. Pay attention to how your “Add to Cart” buttons adapt to different widths and devices and make sure your Bread button responds similarly. You may have to use CSS media queries to ensure a consistent style between your Add to Cart and Bread buttons.

Style your Bread buttons

Refer to Customize the Bread Experience for more help on styling your Bread buttons.

Additional Requirements

Additional details to consider for product and cart page integration with Bread.

Products should have unique SKUs in Shopify

This is particularly important for products with variations. Each product variant should have a unique SKU. Without unique SKUs, the Bread app will fail to process checkouts completed from the product and cart page.

With requirements out of the way, we’ll resume configuring the Bread app.

Bread App Settings

There are several additional settings available for fine-tuning the Bread App. Open Bread App settings by logging into your Shopify Admin, navigating to Apps, and clicking Bread.

For reference, we included detailed explanations of each setting below.

General & Button Settings

  • Auto-settle payments made via the Bread button: Enable this setting to request for the immediate capture of funds upon checkout. Please speak with your Success account manager before enabling Auto-Settle. Note: Changing this setting will not affect the Shopify gateway, described in Installing Bread on Checkout, which must be configured separately.
  • Save new customers (recommended): New customers that check out with Bread will be automatically saved as customers to your shop.
  • Enable Shopify webhooks for updating orders (recommended): Enable this setting to ensure changes to orders in Shopify for example, capturing payments or refunding orders in the Shopify orders view – will update transactions in your Bread Merchant Portal.
    Disabling this setting means orders will not be automatically updated in the Bread merchant portal.
  • Allow checkout directly from product detail pages: Disable this setting to prevent customers from checking out with Bread directly from product detail pages. Customers will instead be directed to add the product to cart and select “Pay over time” on the checkout page.
  • Enable add to cart from product detail pages: Enable this setting to give customers the option to add products to their cart directly within the Bread modal.
    Note: Customizations to your product page may break add to cart functionality. If you are using third party apps to handle product options/configurations or forms for entering custom details (i.e. an engraving or personal note), you should disable the add to cart feature.
  • Allow checkout directly from cart pageDisable this setting to prevent customers from checking out with Bread directly from the cart overview page. Customers will instead be directed to proceed to checkout and select “Pay over time” as the payment method.
  • Show ‘As low as’ promotional text and tooltip: Enable this setting to display example As low as monthly cost on Bread buttons.
  • Disable button and show price(…): Enable this setting to disable Bread buttons once the customer has successfully prequalified for credit.
  • Custom CSS for Product and Cart Buttons: Include custom CSS to define the appearance and behavior of the Bread button on your product detail and cart pages. See Customize the Bread Experience for details.
  • Custom CSS for Cart Button: Include custom CSS to define the appearance and behavior of the Bread button if you want to have separate styling for the cart button, otherwise leave blank.

Advanced Settings

  • Enable targeted financing based on product price or cart total: Enable this setting, add a financing program ID (provided by your Success point of contact), and add a cart size threshold to enable targeted financing by cart total. Learn more.
  • Select if Bread x Shopify javascript files are manually integrated (optional): Enable this setting if you need to manually override parts of the app’s default behavior. Learn more.
  • Use Shopify draft orders to calculate tax: Enable this setting to allow Bread to create/delete temporary Shopify draft orders for the purpose of calculating tax. In certain cases, this feature allows Bread buttons to capture tax more accurately (See the note below about AvaTax).
    Note: With the Bread app creating and deleting temporary draft orders, your draft order ID number will increment silently behind the scenes.
    Note: Shopify Plus merchants using Avalara’s AvaTax service must enable this option for tax calculation to work properly on product and cart Bread buttons, otherwise checkout should be disabled on product and cart pages.
  • Enable Healthcare Mode: Enable this setting if you qualify as a healthcare-related merchant. With Healthcare Mode enabled, the Bread app does not accept personally identifiable information (PII) from your store in order to meet healthcare compliance.

Optimize Button Load Times for Custom CSS (Optional)

When editing the custom CSS for your Bread buttons, you may notice that reloading your site doesn’t update the Bread button styling as you would expect. This is a result of the way certain resources are cached. You can work around this issue by enabling the Select if Bread x Shopify javascript files are manually integrated option and following these steps:

  1. From your Shopify admin, click Apps and then click on the Bread app to access settings
  2. Select the manually integrate Bread-Shopify javascript files checkbox
  3. Locate and copy your Bread ShopID at the top of the page under Information
  4. Copy this URL and replace “your-bread-shop-id” with your actual Bread ShopID from step 3:
  5. From your Shopify admin, navigate to Online Store and choose Edit Code from the Actions menu of your staging or Current theme
  6. Using the URL with your Bread ShopID from step 4, insert a script node in your top level liquid template (theme.liquid) in the <head> element. For example, if your Bread ShopID is 320ac825-9834-41ee-8cb7-f178a7b6ce50:
<script src="" type="text/javascript"></script>

Overriding Shopify App’s Default Behavior (Optional)

Override Instructions

While the Bread app is designed to work out of the box with most Shopify themes, occasionally third party themes or plugins break compatibility with the Bread app. In particular, third party plugins that handle product variations, product add-ons, or product quantities tend to conflict with the Bread app. You may also find that you want to harness the Bread API to implement functionality not included out of the box with our app. In these cases, you can override the Bread app’s default behavior by following these steps:

  1. Complete the steps above in the section “Optimize Button Load Times for Custom CSS” to manually integrate the Bread Shopify javascript files.
  2. Provide a callback function (callback) using window.BreadShopify.setWillCheckoutWithOpts(callback). callback takes two parameters:
    • defaultOpts: The Bread app’s default options used to instantiate the Bread button.
    • callback(err, newOpts): The callback function used to instantiate the button with new options. It takes an error (err) that if provided, will abort the creation of the button, and new options (newOpts) that will be used to configure the custom bread checkout experience.
  3. Inside the callback function, use the button ids (bread-checkout-btn-product or bread-checkout-btn) to customize the experience for each button. You can access the id through the id property of defaultOpts.

This will allow you to execute custom logic and manipulate the Bread button to tailor the experience to your site.

Refer to the Bread API docs for complete information about the opts object and how the checkout experience can be customized.

Example reasons for overriding the Bread app’s default behavior

Note: For any of these examples, ensure that the function is running after the Bread Shopify javascript is loaded onto the page, otherwise the BreadShopify object won’t be available.

Example 1: This example allows you to fetch non-Shopify images or custom urls during the checkout experience. This example is intended to be pasted into the product.liquid page.

// This code assumes that you are in the product detail page which has only one item
window.BreadShopify.setWillCheckoutWithOpts(function (defaultOpts, cb) {    
// update the product image url
defaultOpts.items[0].imageUrl =

// modify the product details url
defaultOpts.items[0].detailUrl =

//finally, we call the callback with our new opts.
cb(null, defaultOpts);

Example 2: If you want to prevent the button from appearing unless specific information is presented, abort button creation by sending an error. If you’re fetching from the server, make sure it’s a synchronous call, otherwise, the button will appear.

window.BreadShopify.setWillCheckoutWithOpts(function (defaultOpts, cb) {
// fetch something important from the server
url: '',
async: false, //makes the call synchronous
}).done( function(data, textStatus, jqXHR) {
        	// modify the defaultOpts based on the data received
        	// defaultOpts.someProperty = ...;
//when done call the callback with the new opts
cb(null, defaultOpts);
}).fail(function (jqXHR, status, err) {
     	// Oh no! Abort button creation

Example 3: This is an alternative way to assign different checkout experiences based on where the button appears (product detail pages or cart pages). Instead of creating a custom experience for each liquid template, you can place the code at the top level object in your shopify store and special case by button id.

window.BreadShopify.setWillCheckoutWithOpts(function (defaultOpts, cb) {    
if (defaultOpts.buttonId ===
'bread-checkout-btn-product') {
//modify the opts for the product detail page
//defaultOpts.someProperty = ...;
// then call the callback     
cb(null, defaultOpts);
} else if (defaultOpts.buttonId ===
'bread-checkout-btn') {
        	//modify the opts for the cart page
//defaultOpts.someProperty = ...;
// then call the callback
cb(null, defaultOpts);
} else {
        	cb('no known button id');