BigCommerce Integration Steps

STEP 1: Install and Configure Bread App

Installation Steps

Get started by logging into your BigCommerce store. From the left-hand menu, select Apps > Marketplace. Search for “Bread” and click on the result that displays the Bread logo
Click on the logo to see the Bread App details page. From here, click Install to add the Bread App to your store.

Plugin Settings And Configuration

In this section we will first walk through the steps to get Bread working on your BigCommerce site. There will be information on the different configuration options found at the bottom of the section.

Once the Bread App is installed, you can find it in your store under Apps > My Apps > Bread Finance. Click on Bread Finance to access the app, then click on App Settings from within the app.

Enter Your Sandbox API Keys

Your Bread API keys, which tie transactions made from your store to your Bread account, should be entered into API Key and API Secret under API Configuration. First, find your sandbox API keys in your Sandbox Bread merchant portal. This is your sandbox merchant portal — you should be able to log in with credentials provided by your main success point of contact.

Your API and Secret key will be listed within the Bread merchant portal under Account > API & Secret Keys. Copy the API Key and Secret Key, and paste both in their corresponding fields within the BigCommerce app. Additionally, make sure Use Sandbox Mode? is enabled. Health Care Mode should only be enabled for merchants selling health-related products.
Once these changes have been made, hit the Save button in the lower right corner of the Bread App settings.

Install Webhooks

Next, at the bottom of the Bread App Settings, click the Install Webhooks button and wait several seconds. If you refresh the page, and the button is not visible, this was installed successfully.

Basic Settings:

Navigate to Storefront -> Script Manager.
Click Create Script
Set the following fields:

Name of script: Bread
Location on Page: Head
Select pages where script will be added: All Pages
Script type: Script

Paste the code at the bottom of the BigCommerce - Bread app settings (Second block of code from the Application Link Code section) into the Script contents field

Note: This script must load on all pages where Bread buttons will be present.

📘
Dual MiniBC Apps
ONLY if you have already installed a MiniBC app to your store that is not Bread, please add the below script to your store in lieu of the script that exists in your Bread app settings. Refer to the app script to replace "YOURBOOTSTRAPID" with your store's unique ID.

<script type="text/javascript">
(function(d,w) {
	var p = window.location.pathname;
    if (p.indexOf('/checkout') === -1 && p.indexOf('/account.php') === -1  ) {
        d.addEventListener("DOMContentLoaded", function(e) {
            var mbcScript = "https://cdn.minibc.com/bootstrap/YOURBOOTSTRAPID.js";
            console.log("Bread Enabled");
            if (window.jQuery) {
                loadScript(mbcScript);
            } else {
                loadScript("https://cdnjs.cloudflare.com/ajax/libs/jquery/2.2.4/jquery.min.js");
                var interval = setInterval(function() {
                    if (window.jQuery) {
                        clearInterval(interval);
                        loadScript(mbcScript);
                    }
                }, 100);
            }
            /**
              * load javascript
              *
              * @param {String} script url
              */
            function loadScript(script) {
                var h = d.getElementsByTagName("head"),
                    s = d.createElement("script");
                s.setAttribute("type", "text/javascript");
                s.setAttribute("src", script);
                h[0].appendChild(s);
            }
        });
    }
})(document);
</script>

STEP 2: Add and Style Bread Buttons

Bread is highly customizable, and the Bread button and modal can be styled to match your site’s theme.

Button Styling

Use Custom CSS to style your Bread buttons. The styling set in this field will apply to the Bread buttons on your Product page, and you can specify styling to use on your cart page within the Cart page settings below.

Note: Your CSS should be minified using a tool such as CSS Minifier. You can also generate customCSS from your Bread Merchant Portal. Please review the Styling Bread section for more information on this.

Positioning and Sizing

Positioning of the Bread button is controlled by the settings in the Bread plugin. For product, cart and checkout pages you can select whether to show bread on that page and where you want to position it on the page.

For height, width, and responsive properties, directly style the element bread-checkout-btn you will be adding to your relevant theme files per the instructions below. For all other Button styling properties, including font, color, background-color, border, hover transitions, and more, please use Button Configuration from within the Bread App settings.

Adding Bread to the Product Details Page

To create Bread buttons on each product detail page, you must first add a Bread HTML element to your product page template. Get started by finding your theme under Storefront > My Themes from the left-hand menu. Under your “Current Theme”, select Edit HTML/CSS. Locate the appropriate theme file to edit your product pages, and add the following HTML where you want your Bread button to display:

<div id="bread-checkout-btn"></div>

📘
Create a Theme Copy
When integrating Bread on a staging or production site, it is best practice to make a copy of your active theme that you can edit to test the Bread integration.

If using a Stencil template, refer to the steps below to add Bread buttons to your product pages:

Begin by adding the Bread button HTML element

Open templates/components/products/product-view.html in your theme editor. Depending on your theme, this may be a different file, like templates/components/product/purchase.html.
Place the element <div id="bread-checkout-btn"></div> in this template under the add-to-cart template — it should look similar to this:

{{#if product.can_purchase}}
   {{> components/products/add-to-cart}}
   <div id="bread-checkout-btn"></div>
{{/if}}

Add HTML attributes to help Bread identify product details (Optional)

Open templates/components/products/product-view.html
Search for the element <div class="productView-options"> — it should contain the add to cart
Add a class name "page-product"to that div so it looks similar to this:

<div class="productView-options page-product">
   {{#if product.release_date }}
       <p>{{product.release_date}}</p>
   {{/if}}
   <form class="form" method="post" action="{{product.cart_url}}" enctype="multipart/form-data"
       data-cart-item-add>

Enable within Bread App

Once the element has been added to your product page template, navigate back to the Bread App settings and find the Product Details Page section. Make sure Display Bread Button? is enabled. You should now see additional options:

Adding Bread to the Cart Summary Page

To add a Bread button to the cart summary page, you must first include a Bread HTML element in your cart page template. Get started by finding your theme under Storefront > My Themes from the left-hand menu. Under your “Current Theme”, select Edit HTML/CSS. Locate the appropriate theme file to edit your cart pages, and add the following HTML where you want your Bread button to display:

<div id="bread-checkout-btn"></div>

Note: ALL products are REQUIRED to have product images and SKUs for the Bread button to load successfully on your cart page.

Add Bread to Cart Template (Stencil Only)

If you are using a Stencil based theme, refer to the steps below to add Bread buttons to your cart page.

Add the Bread button HTML element

Open templates/pages/cart.html in your theme editor. This may also be templates/components/cart/content.html for some themes.
Place the element <div id="bread-checkout-btn"></div> in this template where it makes sense — typically near the checkout button

Add 2 additional HTML attributes that help the Bread identify cart item names, prices, and SKUs (Optional)

Open templates/components/cart/content.html in your theme editor
On or near line 83, add a class name "cart-item-price" to <span class="cart-item-value">
Your span element should now have at least two classes: <span class="cart-item-value cart-item-price" ...>
On or near line 102, add a data attribute "data-quantity-control-input" to <input class="form-input form-input--incrementTotal">
This input element has several other data attributes, but it should now look similar to this:

<input class="form-input form-input--incrementTotal"
   id="qty-{{id}}"
   name="qty-{{id}}"
   type="tel"
   value="{{quantity}}"
   data-quantity-control-input
   data-quantity-min="{{min_purchase_quantity}}"
   data-quantity-max="{{max_purchase_quantity}}"
   data-quantity-min-error="{{lang 'products.quantity_min' quantity=min_purchase_quantity}}"
   data-quantity-max-error="{{lang 'products.quantity_max' quantity=max_purchase_quantity}}"
   min="1">

Enable within the Bread app

Once the element has been added to your product page template, navigate back to the Bread App settings and find the Cart Page section. Make sure Display Bread Button? is enabled. You should now see additional options:

Adding Bread to the Checkout Page

Adding Bread as a payment method on the checkout page requires the use of a “Proxy Payment Method”. This is essentially an unused payment method that Bread can replace on the checkout page.

Note: ALL products are REQUIRED to have product images and SKUs for Bread to load successfully on your checkout page.

Add a Proxy Payment Method for Optimized One-Page Checkout (Most Common)

Get started by logging into your BigCommerce admin and navigating to Store Setup > Payments. If your store uses BigCommerce Optimized One-Page Checkout, under the Checkout Payment Settings tab, scroll down and expand Offline Payment Methods. Toggle on the Cash on Delivery payment method. The Display Name you enter must begin with “Bread #”. For example, “Bread # Pay Over Time” would be a valid Display Name.

Add a Proxy Payment Method for Legacy One-Page Checkout

If your store is using the legacy One-Page checkout, follow the same steps above, but navigate to Online Payment Methods. Select an online payment method that your store is NOT currently using, e.g., Beanstream. Remember, you are choosing a payment method that Bread will override on the checkout page.

Click Set up next to the selected online payment method. On the Settings page for the selected online payment method, fill in dummy information where necessary and enter a Display Name of your choice.
Click Save once you have completed the form.

Insert Footer Script (STRONGLY RECOMMENDED)

Navigate to Storefront -> Footer Scripts and insert the below script. This will hide the Cash On Delivery payment method on your checkout page until it is properly replaced by Bread.

Note: If you find your store is missing Footer Scripts, this is because BigCommerce deprecated this feature for your store. As an alternative, navigate to Advanced Settings > Data Solutions. Edit Google Analytics, connect with Tracking Code, and paste the below code within the “Tracking Code” field. Save your changes.

<style>
.form-checklist label[for="radio-cod"] {
display:none;
}
</style>

Enable within Bread App

Find the Bread App settings under Apps > Bread Finance > App Settings.
Scroll down to Checkout and find the Proxy Payment Method menu. From the drop down menu, select the payment method that you configured earlier. You can refer to the App Settings Reference page for an overview of the additional Checkout settings.

Click Save to update your settings.

Bread will now available as a payment method on your live or staging site. Please confirm that Bread is available on your checkout page and perform a few test transactions in sandbox mode.

Note: If you find that Bread is not loading on your checkout page while testing, and you have confirmed all the products in your cart have images and SKUs, it is likely that the Application Link Code you installed in your Script Manager settings is not carrying to your checkout page. Please follow these directions to get the script on your checkout page:

📘
Script Not Carrying to Checkout Page
If the addition of this script does not carry to your checkout page, navigate to Advanced Settings > Data Solutions. Edit Google Analytics, connect with Tracking Code, and paste the Application Link code within the “Tracking Code” field. Save your changes.
Optionally, the script can be pasted in the Site Verification settings as well.

Otherwise, it may be that the jQuery namespace is not available at your checkout page. If so, please add the following line above the Bread Script you previously added to your Google Analytics text field:

<script type=text/javascript src=https://cdnjs.cloudflare.com/ajax/libs/jquery/2.2.4/jquery.min.js></script>

STEP 3: Test The Bread Extension

We strongly recommend you test your Bread integration with your sandbox API keys and our sandbox domain before pushing Bread live on your production site. You can leverage the following dummy data when testing Bread in sandbox mode.

Any name, address and email
Mobile Number: A random sequence of 10 digits – don’t use duplicates or sequential numbers (e.g. 555-555-5555 or 123-456-7890)
Birth Date: A birth date before 2000
Last 4 Digits of SSN: 07xx (Any 4-digit number starting with 07, such as 0789) to simulate approval, or 0400 to simulate denial
Mobile Code / Token: 1234

Note: You will not receive emails nor text messages when testing in sandbox mode. Please refer our Testing documentation for additional guidelines.

STEP 4: Going Live With Bread

Once you have completed integration and testing with Bread and are satisfied with your implementation, it is time to make Bread live. Please follow these steps to turn Bread on for your customers.

If you originally integrated on a staging site, please repeat the prior steps on your live site to install the app, enable webhooks, and configure the app settings to meet your specifications.
Navigate to your Bread Finance App Settings, remove your Sandbox API keys, enter your Live API and API Secret keys without leading or trailing whitespaces.

Flip Use Sandbox Mode? to off.

Save your changes.

Bread is now live!