Bread Checkout

Overview

How Bread Works

Bread facilitates a full-funnel pre-qualification and checkout flow that you can customize to match the look and feel of your site. Bread seamlessly integrates throughout your customer’s shopping journey to enable higher purchasing power and drive conversions.

In the Bread modal, sensitive customer information is collected in a secure, Bread-served iframe and sent directly to Bread in encrypted form, never touching your server.

Code Example

Transaction of Data

• The customer clicks the Bread button to open the Bread modal and initiate the pre-qualification and checkout flow.
• Optionally, the Bread modal can be launched programmatically with a function call to bread.showCheckout() in JavaScript.
• After a customer is pre-approved, they can complete the Bread checkout flow by clicking the final “Accept & Check Out” button. This generates a PENDING transaction with Bread.
• A transaction token is returned from Bread. If a done callback was defined during the Bread button configuration, this token will be returned as a parameter in the done callback. Otherwise, the containing form will automatically submit with the transaction token included as a input element.
• The transaction token is passed back to the merchant server as either form data or through an AJAX call in a done callback (outlined in the previous step).
• From the merchant server, the customer’s order should be created in your order management system through a series of requests to the Bread REST API. The order will also need to be AUTHORIZED, indicating the transaction is indeed valid. These steps are handled automatically by a plugin if your site is built with a supported e-commerce platform. For custom sites, please refer to our Backend API documentation.

Step 1: Adding bread.js to Your Site

Add the following bread.js script to your base template so that it loads on all pages. Replace the value in data-api-key with your public API Key.

🚧

Sandbox vs. Production

Only use your sandbox API keys and sandbox Bread domain for testing and development. This ensures you do not unintentionally create live transactions.

For production:

<script src="https://checkout.getbread.com/bread.js" data-api-key="REPLACE WITH YOUR PUBLIC API KEY"></script>

For sandbox:

<script src="https://checkout-sandbox.getbread.com/bread.js" data-api-key="REPLACE WITH YOUR SANDBOX PUBLIC API KEY"></script>

Step 2: Button Placement and Configuration

Adding The Bread div Container

Place a div element where you’d like to display the Bread button on your page. This element must have an id attribute. Note that the element must be a div and not a span or other non-block element.

For example:

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

📘

Placeholder Button

Any elements placed inside of this div element will display on your page prior to the JavaScript that creates the Bread button running. This can be used to display a loading element or placeholder. Any elements inside this div element will be removed when the Bread button loads.

📘

Button Sizing

Unless size is otherwise set, the button will inherit all the space given to it in its containing DOM element. For a default size of 200px by 50px, set an attribute of data-bread-default-size=true on the button div.

Basic Button Configuration

Configure the Bread button with a Javascript object (i.e. opts), and render the button by passing the object to the bread.checkout function (i.e. bread.checkout(opts)). Minimally, you pass the id attribute of the button div you created as well as an array of items containing the products to be purchased to the Javascript object.

<script>
var opts = {
 buttonId: 'bread-checkout-btn',
 actAsLabel: false,
 asLowAs: true,
 items: [
 {
   name:'Couch',
   price:150000,
   sku:'COUCH123',
   imageUrl:'[REPLACEMEWITHAREALURL]',
   detailUrl:'[REPLACEMEWITHAREALURL]',
   quantity: 1
 }],
 done: function(){
   //add some code to run when a customer completes their Bread checkout
   //done function is expanded on in STEP 3
 }
};
bread.checkout(opts);
</script>

📘

Bread Configurations

There are additional methods and properties that can be added to the Javascript object which will control the functionality of the Bread button (i.e. calculateTax and calculateShipping). Learn more here

Step 3: Adding a DONE Callback

The “done” callback can be included in your Javascript object (opts) and will be run once a user completes a checkout in the Bread modal. It is a highly customizable function which can allow you to specify additional front-end logic to execute after a user completes checkout. The done callback will receive two parameters: err and tx_token (Bread’s transaction ID tied to the order).

opts.done = function(err, tx_token) {
// example logic below
 if (err) {
   console.error("There was an error: " + err);
   return;
 }
 
 if (tx_token !== undefined) {
   console.log(tx_token);
   var i = document.createElement('input');
   i.type = 'hidden';
   i.name = 'token';
   i.value = tx_token;
   var f = document.createElement('form');
   f.action = '[REPLACEMEWITHSERVICEURL]';
   f.method = 'POST';
   f.appendChild(i);
   document.body.appendChild(f);
   f.submit();
 }
 return;
};
bread.checkout(opts);

Following the steps to this point will allow you to render a basic Bread button on your site, and pass the Bread transaction ID to your OMS. The transaction ID should be used to integrate with Bread's Backend API for order management.

The remaining steps cover styling and additional functionality available in the Bread button.

Step 4: Styling the Bread Button

There are various button styling and checkout flow decisions that can be customized to fit your brand and customer flow. The customCSS property is a minified string of CSS styling can be added to the Bread opts configuration. Using the customCSS property, you can override default Bread styling and by applying styles directly to the classes and ids that compose the Bread button.

Button Structure:

#bread-button[.bread-btn, .bread-label][.bread-logged-out, .bread-as-low-as, .bread-no-terms, .bread-show-terms]
 .bread-embed-inner
   .bread-center
     .bread-center-inner
       .bread-text[.bread-pot, .bread-as-low-as, .bread-for]
         [span.bread-amt
         span.bread-dur]
 .bread-embed-icon

Button States:

The main button element has an id attribute of #bread-button. The button can have the following states, represented by classes on the element:

Best Practices:

• Use a service like CSS Compressor or CSS Minifier to compress your CSS into a single string.
• Leave height and width out of your customCSS. Those dimensions should be handled by a containing element and normal CSS.
• Use @import to include custom fonts.
• Use the content property on pseudo-elements (:before and :after) to add your own custom words and phrases to the button.
• Ensure the selectors and properties you leverage are available to the browsers your site supports. You may need to use browser pre-fixed properties to get the best support.
• Consider the responsiveness of your site: Does that need to translate to your button styling?

For example:

opts.customCSS = '#bread-button{background:#71a532;line-height:50px;height:50px;display:block;color:#fff;border:0 solid #f4802e;font-family:Helvetica,Arial,sans-serif;font-size:14px;font-weight:400;text-align:center;vertical-align:middle;transition:all .3s ease;border-radius:40px;cursor:pointer}#bread-button.bread-btn:hover{background:#c86214}#bread-as-low-as:before{content:"As low as "}.bread-for:before{content:"For "}';

Adding a Placeholder Button

You can add a placeholder button to your page to display to your customers while Bread loads on the page and creates the Bread button. This can be added on many Bread platforms including Shopify, BigCommerce, and using a Direct API integration.

To add a placeholder button to your page navigate in your code or theme to where the Bread div markup exists.

/* button id may vary depending on platform */
<div id="bread-checkout-btn-product"></div>

When the Bread script is loaded onto the page it will find this div and convert it to the Bread button. If you would like to add a placeholder button to display on the page while Bread loads you can style this div and any content inside it. When Bread loads it will overwrite all this styling and use the styling you have chosen through the Bread settings.

An example of a styled placeholder button can be found below, you can change the styling to fit your own site's needs.

<!-- button id may vary depending on platform -->
<div id="bread-checkout-btn-product" data-bread-default-size="false">
    <div
      style="
        display: flex;
        align-items: center;
        justify-content: center;
        width: 350px;
        background: #5156ea;
        height: 50px;
    ">
        <div style="color: #ffffff; font-weight: bold; font-size: 22px">
          Financing Now
        </div>
    </div>
</div>

The above markup and styling with produce a button that looks like the following:

This button will display on your page until Bread loads and overwrites it with the actual clickable Bread button.

Additional Features

Calculating Tax and Shipping

If tax and shipping amounts are available, that information can be passed to the Bread button as part of the configuration by setting the tax and shippingOptions properties on the Javascript object (opts). Review our Checkout Reference for additional detail on the requirements of these properties.

opts.tax = 4999 //a tax amount of $49.99

opts.shippingOptions = [{
  typeId: 'ship-type-1',
  cost: 599,
  type: 'Overnight Shipping'
},{
  typeId: 'ship-type-2',
  cost: 299,
  type: 'Standard Shipping'  
}]

Alternatively, the Javascript object (opts) can also be configured with the calculateTax and calculateShipping callbacks to retrieve tax and shipping details from a separate service. These callbacks are provided with the billing and shipping information input by the customer in the Bread modal to facilitate the tax and shipping calculations.

opts.calculateTax = function(shippingContact, billingContact, callback) {
  $.ajax({
    url: '/tax',
    type: 'POST',
    contentType: 'application/json',
    data: JSON.stringify({
      shippingAddress: shippingContact,
      total: items[0].price * items[0].quantity
    })
  })
  .done(function(data){
    callback(null, data);
  })
  .fail(function(err){
    callback(err);
  });
};

opts.calculateShipping = function(shippingContact, callback) {
  $.ajax({
    url: '/shipping',
    type: 'POST',
    contentType: 'application/json',
    data: JSON.stringify({
      shippingAddress: shippingContact,
      total: items[0].price * items[0].quantity
    })
  })
  .done(function(data){
    callback(null, data);
  })
  .fail(function(err){
    callback(err);
  });
};

📘

Note

This example assumes a simple endpoint on the server that will return tax cost and shipping options based on total price and shipping address; your actual system configuration may be more complex.

📘

Note

The shipping contact will include the customer’s selected shipping option as the field selectedShippingOption. This will contain shipping information provided by the shippingOptions field or by the calculateShipping callback, which may be used to calculate tax.

Capture Information About Abandoned Checkouts

If a customer exits the Bread modal before completing their checkout, merchants can capture the customer’s email address and prequalification status through an onCustomerClose callback function assigned to the Javascript object (opts).

There are four potential prequalification statuses:

• PREQUALIFIED - Customer is pre-qualified for financing options for at least the amount of the checkout
• PARTIALLY_PREQUALIFIED - Customer is pre-qualified for financing options, but not for the total amount of the desired checkout. To help partially pre-qualified customers convert, talk to your Success representative about using Bread’s out-of-the-box Overflow Pay feature
• NOT_PREQUALIFIED - Customer is not pre-qualified for financing options at this time
• ABANDONED - Customer didn’t complete the application and authentication steps, so pre-qualification status is unknown

Merchants can add custom code to execute within onCustomerClose, but the snippet below highlights a potential approach that can be used to run different logic based on prequalification status.

opts.onCustomerClose: function(err, customer) {
  if (err !== null) {
    console.error("An error occurred getting customer close data.");
    return;
  }
  var prequalStatus = customer.state;
  switch (prequalStatus) {
    case 'PREQUALIFIED':
      console.log(customer.email + " was prequalified for financing.");
    break;
    case 'PARTIALLY_PREQUALIFIED':
      console.log(customer.email + " was partially prequalified for financing.");
    break;
    case 'NOT_PREQUALIFIED':
      console.log(customer.email + " was not prequalified for financing.");
    break;
    case 'ABANDONED':
      if (customer.email === undefined || customer.email === null) {
        console.log("Unknown customer abandoned their prequalification attempt.");
      } else {
        console.log(customer.email + " abandoned their prequalification attempt.");
      }
    break;
  }
}

Capture Information During Button Interaction

Similar to the onCustomerClose function, the onCustomerOpen function provides a method for including your own logic when customers open the Bread modal.

opts.onCustomerOpen: function(err, data, callback) {
  if (err !== null) {
    console.error("An error occurred getting customer open data.");
    return;
  }
  switch (data.source) {
    case 'PROMO':
      alert('Triggered by a promo click.');
      callback(true);
      break;
    case 'OFFSITE':
      alert('Triggered by an offsite redirect.');
      callback(true);
      break;
    case 'BUTTON':
      alert('Triggered by a button click');
      // Example use case where you want to make sure a user
      // applies discounts before proceeding. `user` object is
      // fictional and not related to Bread.
      if (user.hasDiscounts == false) {
        alert('You have unapplied discounts you can add before checking out!');
        callback(false);
      } else {
        callback(true);
      }
      break;
    default:
      callback(true);
  }
  // or add your own logic here
  // This code will run in the time between the customer clicking on the Bread button
  // and the Bread modal appearing
  // Finally, make sure to run callback(data) or the Bread modal won't open
  callback(data);
}

Trigger Bread without the button

You can trigger the checkout experience without a Bread button by calling bread.showCheckout(opts) during a click event on the page. The opts object here mimics the object used in bread.checkout(), but without the buttonId property.

var opts = {...};
            
document.getElementById('my-own-button').addEventListener('click', function(e) {
  bread.showCheckout(opts);
});

📘

Common bread.showCheckout() use cases

Use this method to trigger Bread Checkout when a user toggles a radio button or clicks a custom button, text, or image. This allows additional flexibility in integrating the Checkout flow in your existing customer workflows.

🚧

Running bread.showCheckout() synchronously

It's important that bread.showCheckout() is run in a synchronous context. Some browsers may interpret the call as a pop-up and block the display if executed from an async callback. When using bread.showCheckout() it is important to test functionality across browsers and devices.

Targeted Financing

In addition to your default financing program, Bread allows for additional, promotional financing programs that your store can selectively offer based on various factors. For example, you could conditionally offer a 0% financing program on higher-margin SKUs or when the customer’s cart size has met a price threshold. Another example, if your default financing program includes 0% options you could conditionally offer only interest positive financing options for carts that include sale items or discounts.

Set your targeted financing program by including the financingProgramId attribute on the Javascript object (opts).

// Example - Offer promotional financing for cart sizes over $1,000
var cartSize = opts.items.reduce(function(total, item) {
  return total + (item.quantity * item.price);
}, 0);
if (cartSize > 100000) {
  opts.financingProgramId = 'cdcf5ae4-4f74-4e6d-9a9c-302e8d359cb9';
}
// Example - Change financing program for carts with discounts
if (opts.discounts.length > 0) {
  opts.financingProgramId = 'aabf5ae4-4f74-4e6d-9a9c-302e8d319cb9';
}

📘

Financing Programs

Additional financing programs must be created by your Success Manager. Get started with targeted financing by reaching out to your main Success point of contact

Display Calculated “as low as” amount without Bread Button

In some cases you may only need the calculated “as low as” language and implementing an additional Bread button doesn’t make sense. For these situations, use bread.asLowAs to generate the as low as amount and required disclosure.

📘

bread.asLowAs() Common Use Cases

Two common examples include adding promotional “as low as” text on a home page banner or creating multiple “as low as” elements for a category page with several products.

bread.asLowAs([
  {
    customTotal: 10000,
    id: 'product-x-123', // optional
    financingProgramId: 'cdcf5ae4-4f74-4e6d-9a9c-302e8d359cb9' // optional
  }
], function(data, err) {
  if (err) {
    console.error(err);
    return;
  }
  data.forEach(function(item) {
    const asLowAs = item.asLowAs;
    const el = document.getElementById(item.id);
    el.innerHTML = 'As low as ' + asLowAs.amount + ' / Month <span id="financing-disclosure">*</span>';
  });
});

The bread.asLowAs method takes two arguments.

The first argument should be an array of elements that you wish to calculate “as low as” prices and disclosures for. Each object within the array must contain a customTotal property representing the total cart or product price in cents. The following properties are optional:

• Id: The id will be included in the completed response and can be used to later identify the associated product or element. (Optional)
• financingProgramId: Calculate “as low as” amount and generate disclosure based on an alternate financing program. (Optional)

The second argument in bread.asLowAs is a callback function that will execute once Bread has completed the request. This callback function receives the “as low as” response as an argument and should include the logic that implements the response. The response is formatted as an array of calculated “as low as” objects. Please see below for an example of an individual “as low as” response object.

{
  asLowAs: { 
    amount: "$4.62",
    apr: 0.0999,
    asLowAsText: "This example payment is based on the listed product price of $100.00 assuming a 24-month term and a 9.99% APR. Your terms may vary and are subject to application. Rates range from 5.99% to 29.99% APR. Bread® loans are made by Comenity Capital Bank.",
    maxApr: 0.2999,
    minApr: 0.0599,
    monthly: 462,
    termInterval: "Month",
    termLength: 24
  },
  customTotal: 10000,
  financingProgramId: "cdcf5ae4-4f74-4e6d-9a9c-302e8d359cb9",
  id: "product-x-123"
}

Initialize API Key After Page Load

In some cases, you might need to initialize your API key after the page has loaded instead of providing it in the script tag. The setAPIKey method allows you to do this.

bread.setAPIKey('YOURAPIKEY');

Display Inline Checkout Experience

You can also trigger the checkout experience inline by simply replacing the buttonId field with formId. As a note, the Bread Inline Experience should not exist on the same page as a Bread Checkout or Bread Apply/Promo button.

<form id="bread-checkout-form" action="/confirm" method="POST">
<script>
var opts = {
 formId: 'bread-checkout-btn',
 actAsLabel: false,
 asLowAs: true,
 items: [
 {
   name:'Couch',
   price:150000,
   sku:'COUCH123',
   imageUrl:'[REPLACEMEWITHAREALURL]',
   detailUrl:'[REPLACEMEWITHAREALURL]',
   quantity: 1
 }]
};
bread.checkout(opts);
</script>
</form>

Checkout Reference

The following parameters are submitted to your form’s action endpoint, along with other elements of your form, once a Checkout is completed with Bread.

You can further customize your customer’s Checkout experience by configuring the following options in our opts object.

Required

Highly Recommended

Optional