The bread-classic Developer Hub

Welcome to the bread-classic developer hub. You'll find comprehensive guides and documentation to help you start working with bread-classic as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    

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

Add Bread

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 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:

  • If the button has the actAsLabel option set to false, it is assigned the bread-btn class. Otherwise, it is assigned the bread-label class
  • Depending on the current state of the user checking out, an additional class is added
    • bread-logged-out if the user is not logged in
    • bread-as-low-as if the user is not logged in and the asLowAs option is set to true
    • bread-no-terms if the button cannot provide an exact monthly payment amount for the logged in user
    • bread-show-terms if the button can provide a monthly payment amount for the logged in user
  • Inside #bread-button, the .bread-text has an additional class state:
    • bread-pot is the default state, displaying “Pay Over Time” in the default CSS
    • bread-as-low-as if the user is not logged in and the asLowAs option is set to true
    • bread-for when the user is logged in and the button can provide a monthly payment amount

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:

Financing Now

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 Cross River Bank, member FDIC.",
    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.

Parameter

Description

token

The ID of the token representing checkout details.

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

Required

Attribute

Type

Parent Attribute

Description

buttonId

string

The DOM id of the checkout button

items

array

An array of objects containing item(s) in the customer’s cart at checkout. Fields in the items object are required.

name

string

items

The name of the item.

price

integer

items

The price of the item in cents. Must be a positive integer.

sku

string

items

The unique identifier or SKU for the product.

imageUrl

string

items

A URL for the product image. The supported image types are .jpg, .gif, and .png.

(optional)

detailUrl

string

items

A URL pointing to the product page for the item

quantity

integer

items

The quantity of the item as a positive integer

Highly Recommended

Attribute

Type

Parent Attribute

Description

calculateTax

function

The callback method to dynamically calculate tax based on shipping address and product price/cart total. Recommended to enable checkouts from the product detail or cart summary page. Pass in shippingContact and callback as parameters. Return the tax total (as an integer in cents) or an error through the callback.

calculateShipping

function

The callback method to dynamically generate shipping options and prices based on shipping address. Recommended to enable checkouts from the product detail or cart summary page. Pass in shippingContact and callback as parameters. Return an array of shippingOptions or an error through the callback. Please refer to shippingOptions under Checkout Reference for valid formatting.

billingContact

object

Customer’s billing address and information. Providing these fields will auto-populate fields in the form.

fullName

string

billingContact

The customer’s full name. Can be used in place of firstName and lastName.

firstName

string

billingContact

Optional unless a fullName isn’t provided

lastName

string

billingContact

Optional unless a fullName isn’t provided

address

string

billingContact

The customer’s billing address

address2

string

billingContact

  • (Optional)

zip

string

billingContact

The customer’s 5 digit US billing zipcode

city

string

billingContact

state

string

billingContact

A two character state abbreviation

phone

string

billingContact

A 10 digit phone number

email

string

billingContact

A valid email address

shippingContact

object

Customer’s shipping address and information. Providing this field will auto-populate fields in the form.

fullName

string

shippingContact

The customer’s full name. Can be used in place of firstName and lastName.

firstName

string

shippingContact

Optional unless a fullName isn’t provided

lastName

string

shippingContact

Optional unless a fullName isn’t provided

address

string

shippingContact

The customer’s shipping address

address2

string

shippingContact

zip

string

shippingContact

The customer’s 5 digit US shipping zipcode

city

string

shippingContact

state

string

shippingContact

A two character state abbreviation

phone

string

shippingContact

A 10 digit phone number

buttonLocation

string

A String representing the location of the Bread button in the customer’s shopping journey. The options are: “product”, “cart_summary”, “checkout”, “category”, “financing”, “marketing”, and “other”.

Optional

Attribute

Type

Parent Attribute

Description

tax

integer

The amount of tax on the purchase in cents.

customTotal

integer

The total amount of the purchase in cents, including all items, tax and shipping. This field will override the total amount calculation and must be a positive integer.

This field is required if no items are provided.

discounts

array

An array of objects containing the discount(s) to be applied to the customer’s order. This amount will be deducted from the cart total, unless a customTotal is provided.

amount

integer

discounts

Positive integer amount for the discount value in cents

description

string

discounts

Text displayed to describe the discount.

financingProgramId

string

Set promotional financing programs with financingProgramId. If financingProgramId is not specified or invalid, the default financing program will be used. For more details, see Targeted Financing under Additional Features.

shippingOptions

array

An array of objects containing the shipping option(s) to be displayed to the customer. If more than one option is presented, the customer will be able to select their option prior to checkout.

typeId

string

shippingOptions

The ID representing the shipping type

cost

integer

shippingOptions

The cost of the shipping option in cents. This must be a positive integer.

type

string

shippingOptions

Text displayed to the user to name or describe the shipping option

actAsLabel

boolean

Default is true.

Display price per month label text instead of the button to logged in users. The button will not be clickable if true. The bread-button element is assigned the bread-label class, instead of the bread-btn class.

asLowAs

boolean

Default is false.

Display price per month to logged out users using the lowest available APR and longest term length offered. Displayed with a tooltip explaining terms are subject to change. If a user is pre-qualified, she will see price per month based on her custom rate.

allowCheckout

boolean

Default is true.

Specify whether users are able to complete checkout after pre-qualification. If set to false, the user will be prompted to ‘Continue shopping’ if pre-qualified for financing

showInWindow

boolean

Default is false.

Specify whether Bread Checkout launches in a new window regardless of device or browser. Use this if the page containing Checkout is not on a secure HTTPs connection.

disableEditShipping

boolean

Default is false.

Specify whether customers are able to modify the shipping address on the review order screen of the Bread Checkout modal.

requireShippingContact

boolean

Default is true.

Specify whether a user is required to fill out a shipping contact form during checkout. This is used in cases like virtual goods where no shipping address is ever collected.

customCSS

string

Overwrite the default Bread CSS with your own.

onCustomerOpen

function

The callback to track when a user opens the Bread Checkout modal. This can be used to prevent the modal from opening.

onCustomerClose

function

The callback to track when a user closes the Bread Checkout modal. This returns the user’s email address and pre-qualification status of the user.

done

function

The callback to invoke when the checkout is completed. A tx_token is passed if upon a successful checkout, otherwise an error object is passed.

addToCart

function

The callback to override the default flow of allowing users to checkout from the Bread Checkout flow. Instead, this override allows the user to add the items to her cart.

Updated 7 days ago


What's Next

Testing

Bread Checkout


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.