API

Introduction

Welcome to Bread. We help you provide financing to your customers by integrating with the Bread Button; a secure module that allows your customers to apply for transparent credit products in a streamlined, customizable checkout flow. You’re able to show the button at different customer touch points, boosting checkout conversions and average order values.

Our Merchant API helps you manage completed transactions and carts, which can also be created directly in the browser.

Account

New to Bread? Send us a note.

 

Live API Endpoint

https://api.getbread.com

Sandbox API Endpoint

https://api-sandbox.getbread.com

 

Topics

Authentication

Authentication to the API is performed via HTTP Basic Auth. Use your API key as the username and your secret API key as the password. Your secret API key provides access to your account and transaction information, so don’t share or display publicly.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

Example Curl Request

curl -u <api-key>:<secret-key> https://api.getbread.com/transactions/:tx_id

 

Errors

HTTP response codes are used to indicate the success or failure of an API request. In general, 200 indicates success. 401 indicates an authentication error, 500 indicates transaction errors given the information provided, and 400 indicates an error while updating a merchant order ID or when updating a cart.

Example Error Response

curl -u <api-key>:<secret-key> https://api.getbread.com/transactions/a-bad-tx-id

HTTP/1.1 500 Internal Server Error
Server: nginx/1.8.0
Date: Fri, 14 Oct 2016 15:30:46 GMT
Content-Type: application/json; charset=utf-8
Content-Length: 82
Connection: keep-alive
{"description":"Transaction ID was invalid","error":true,"type":"INTERNAL_ERROR"}

 

Sandbox

To test in our sandbox environment, use your sandbox API key and secret API key combination in the request.

Requests made with sandbox credentials won’t result in loan originations.

Sandbox Endpoint

https://api-sandbox.getbread.com

Example Base Request

curl -u <sandbox-api-key>:<sandbox-secret-key> https://api-sandbox.getbread.com

 

Transactions

The transaction object

The transaction object represents successful checkouts with Bread. The API allows you to query, authorize, settle, cancel, or refund a transaction.

Attributes

breadTransactionId
string
Unique identifier used to reference the transaction in the Bread systems.  When you make API calls on a transaction this is the transaction id to use.
billingContact
hash
Billing contact information associated with the transaction

address
string
Billing address line 1
address2
string
Billing address line 2 (i.e apartment number)
fullName
string
First and last name
phone
string
Phone number. 10 numeric characters
zip
string
Zipcode. 5 character US zip code

createdAt
timestamp
lineItems
list
List of line item details, including id, product(s), price, and quantity

price
integer
Price of the item in cents 
product
list
Product object with properties of detailUrl, imageUrl, name, and sku. All properties are strings
quantity
integer
 Number of items for this product
sku
string
The identifier of the product in your system

merchantOrderId
string
Unique identifier to tie to an order in your order management/ecommerce platform – set this via an API call
shippingContact
hash
 Shipping contact information associated with the transaction

address
string
Shipping address line 1
address2
string
Shipping address line 2 (i.e apartment number)
fullName
string
First and last name
phone
string
Phone number. 10 numeric characters
zip
string
Zipcode. 5 digit US zipcode

shippingCost
integer
 A value representing the cost of shipping in cents
shippingMethodCode
string
Code used to identity the type of shipping in your system, ie “FEDEX_OVERNIGHT”
status
string
The current status of the transaction. All transactions start in the PENDING state. Other valid states are CANCELED, REFUNDED, EXPIRED, AUTHORIZED, SETTLED.
total
integer
The completed total of the transaction in cents.
 adjustedTotal
integer
The current total of the transaction after applying any actions such as cancellations or refunds.  Value in cents.
totalTax
integer
Tax total of the transaction in cents
trackingNumber
integer
Shipping carrier tracking number
carrierName
integer
Shipping carrier name
discounts
list
A list of discount objects which were applied to the order

amount
integer
The value in cents of the discount
description
string
A description of the discount

Example Transaction

{
  "billingContact": {
    "fullName": "Emily Blunt",
    "address": "39 W 14th St.",
    "address2": "403",
    "city": "New York",
    "state": "NY",
    "zip": "10010",
    "phone": "5552342602",
    "email": "emily.blunt@example.com"
  },
  "breadTransactionId": "addfa809-f4d5-4540-8902-0da4e3fd53c0",
  "merchantOrderId": "",
  "createdAt": "2016-10-13T18:00:00.000000Z",
  "lineItems": [{
    "sku": "TEST001",
    "quantity": 1,
    "price": 50000,
    "product": {
      "name": "Test Item",
      "sku": "TEST001",
      "imageUrl": "http://placehold.it/350x150",
      "detailUrl": "http://placehold.it/350x150"
    }
  }],
  "shippingContact": {
    "fullName": "Emily Blunt",
    "address": "39 W 14th St.",
    "address2": "403",
    "city": "New York",
    "state": "NY",
    "zip": "10010",
    "phone": "5552342602"
  },
  "shippingCost": 1500,
  "shippingMethodCode": "FEDEX_OVERNIGHT",
  "trackingNumber": "ABCDEF1234",
  "carrierName": "USPS",
  "discounts": [],
  "status": "PENDING",
  "total": 50000,
  "adjustedTotal": 50000,
  "totalTax": null
}

 

Retrieve a transaction

Retrieves the details of a transaction that has already been created. Send the unique transaction ID that was returned from a completed checkout and Bread will return details associated with the transaction.

Arguments

:tx-id
required
Identifier of the transaction to be retrieved

Returns

Returns a transaction if a valid identifier is provided, otherwise returns an error.

Definition

GET https://api.getbread.com/transactions/:tx-id

Example request

curl -u <api-key>:<secret-key> -H "Content-Type: application/json" https://api.getbread.com/transactions/fe6499b7-9b6b-4c3d-9cdf-5afc1d840d12

Example response

{
  "billingContact": {
    "fullName": "Donald Duck",
    "address": "201 Quack Lane",
    "address2": "3",
    "city": "Brooklyn",
    "state": "NY",
    "zip": "11238",
    "phone": "5559073301",
    "email": "donald.duck@example.com"
  },
  "breadTransactionId": "fe6499b7-9b6b-4c3d-9cdf-5afc1d840d12",
  "merchantOrderId": "my-order-id",
  "createdAt": "2016-08-08T18:50:14.853224Z",
  "lineItems": [],
  "shippingContact": {
    "fullName": "Donald Duck",
    "address": "137 Duffy Place",
    "address2": "3",
    "city": "Brooklyn",
    "state": "NY",
    "zip": "11238",
    "phone": "5559073301"
  },
  "shippingCost": 6500,
  "shippingMethodCode": "fedex-2day",
  "trackingNumber": "ABCDEF1234",
  "carrierName": "USPS",
  "discounts": [],
  "status": "CANCELED",
  "total": 25000,
  "adjustedTotal": 0,
  "totalTax": 4380
}

 

Update a transaction

Updates or sets the transaction with the values of the parameters passed.

This request only accepts the merchantOrderId as an argument.

Arguments

merchantOrderId
string | optional
Unique identifier from your system to match to the Bread transaction ID

Definition

PUT https://api.getbread.com/transactions/:tx-id
{
  "merchantOrderId": "my-cms-order-id"
}

 

curl -u <api-key>:<secret-key> \
    -X PUT \
    -H 'Content-Type: application/json' \
    https://api.getbread.com/transactions/86279175-3d85-4be7-a368-5615d932ef3c \
    -d '{"merchantOrderId": "my-cms-order-id"}'

Example Response

{
  "billingContact": { ... },
  "breadTransactionId": "caf8afac-1a6f-4f55-a6d8-fd46763e8cb3",
  "merchantOrderId": "my-order-id",
  "createdAt": "2015-10-13T20:00:00.000000-04:00",
  "lineItems": [...],
}

 

Authorize a transaction

A transaction can be authorized after a checkout is completed. The authorization status confirms that Bread has approved a loan for the amount and items and guarantees payment once the customer’s order is fulfilled. Only pending transactions can be authorized.

It’s advised to confirm the Bread transaction amount against your expected transaction total prior to making the authorize call. Additionally, if you include a merchantOrderId in your authorize call, the Bread transaction will be updated with your system generated order ID.

Arguments

type
string | required, value is “authorize”
lineItems
list | optional
Array of line item types you want to associate with the authorization. 
merchantOrderId
string | optional
Unique identifier from your system to match to the Bread transaction ID. This is recommended for easier financial reconciliation and to troubleshoot any customer support issues

Definition

POST https://api.getbread.com/transactions/actions/:tx-id

Usage

curl -u <api-key>:<secret-key> -X POST \
 -H 'Content-Type: application/json' \
 https://api.getbread.com/transactions/actions/caf8afac-1a6f-4f55-a6d8-fd46763e8cb3 \
 -d = '{"lineItems": [{"price": 4000,"product": {"detailUrl": "http://your-site.com/your-product","imageUrl": "http://our-bucket.s3.amazon.com/your-product-img.jpg","name": "Your cool product","sku": "coolproductsku"},"quantity": 1}],"merchantOrderId": "12345", "type": "authorize"}'

Note: Inclusion of the lineItems is optional, as well as the merchantOrderId.

Settle a transaction

A transaction should be settled after the order has been fulfilled. This will initiate payment from Bread for the amount of the transaction.

If a cancellation was processed before the transaction was settled, the payment you receive will reflect the canceled amounts.

Arguments

type
string | required, value is “settle”

Definition

POST https://api.getbread.com/transactions/actions/:tx-id
{ 
  "type": "settle"
}

Example Usage

curl -u <api-key>:<secret-key> -X POST -H 'Content-Type: application/json' \
    https://api.getbread.com/transactions/actions/caf8afac-1a6f-4f55-a6d8-fd46763e8cb3 \
    -d '{"type":"settle"}'

 

Cancel a transaction

You can process full or partial cancellations after a transaction is pending but before it’s settled. The cancellation can also be associated with specific line items. If the cancellation amount and line items are not specified, all items and the entire transaction amount will be cancelled.

Arguments

type
string | required, value is “cancel”
amount
integer | optional
The amount to cancel, which must be less than or equal to the original amount
lineItems
list | optional
The items that are being fully or partially cancelled

Definition

POST https://api.getbread.com/transactions/actions/:tx-id
{
  "type": "cancel",
  "amount": 3200, //optional
  "lineItems": [{ //optional
    "sku": "product-sku-1",
    "quantity": 1
  },
  {
    "sku": "product-sku-2",
    "quantity": 2
  }]
}

Usage

curl -u <api-key>:<secret-key> -X POST -H 'Content-Type: application/json' \
    https://api.getbread.com/transactions/actions/caf8afac-1a6f-4f55-a6d8-fd46763e8cb3 \
    -d '{"type":"cancel", "amount":3200}'

 

Refund a transaction

You can process full or partial refunds after a transaction is settled. The refund can also be associated with specific line items. If the refund amount and line items are not specified, all items and the entire transaction amount will be refunded.

Arguments

type
string | required, value is “refund”
amount
integer | optional
The amount to refund, which must be less than or equal to the original amount
lineItems
list | optional
The items that are being fully or partially refunded

Definition

POST https://api.getbread.com/transactions/actions/:tx-id
{
  "type": "refund",
  "amount": 5000,
  "lineItems": [{ //optional
    "sku": "product-sku-1",
    "quantity": 1
  },
  {
    "sku": "product-sku-2",
    "quantity": 3
  }],
}

Usage

curl -u <api-key>:<secret-key> -X POST -H 'Content-Type: application/json' \
    https://api.getbread.com/transactions/actions/caf8afac-1a6f-4f55-a6d8-fd46763e8cb3 \
    -d '{"type":"refund", "amount":3200}'

 

Set shipping details

Merchants will be required to notify Bread about certain shipment events details. This is facilitated by submitting a POST request to an endpoint identified by the transactionId.

Arguments

trackingNumber
string | optional
Shipment carrier tracking number
carrierName
string | optional
Shipment carrier name
POST https://api.getbread.com/transactions/:tx-id/shipment
POST https://api.getbread.com/transactions/:tx-id/shipment
{
  "trackingNumber": "ABCDEFGH1234",
  "carrierName": "USPS"
}
curl -u <api-key>:<secret-key> -X POST \
 -H 'Content-Type: application/json' \
 https://api.getbread.com/transactions/caf8afac-1a6f-4f55-a6d8-fd46763e8cb3/shipment \
 -d = '{"trackingNumber":"ABCDEF1234","carrierName": "USPS"}'

Carts

The cart object

The cart object allows you to create preconfigured carts to send to customers using an offsite checkout or for retargeting customers after a cart abandonment.

Attributes

id
string
This is an identifier which can be used to relate checkouts with this cart to an entity on your backend.
cartName

string

Name for identifying the cart with a promotion.
expiration

string

Expiration date for cart link.
url

string

Cart link URL to send to customer.
isCustomTotal

boolean

Set to true for a flat cost Cart link, false for Cart link with line items.
options
hash

orderRef
string
Unique identifer to match with the Bread transaction ID
callbackUrl
string
Where we’ll POST the transactionId of the checkout and the orderRef following a successful checkout
completeUrl
string
Where the customer is redirected following a successful checkout, e.g. a confirmation page
errorUrl
string
Where the customer is redirected following an unsuccessful checkout, including if no financing offer is available or if there are technical issues
shippingOptions
hash
Array of shipping option(s) the customer can select from when checking out with the cart, this includes type, typeId, and cost (int representing cost in cents)
shippingContact
hash
The customer’s shipping details. Includes firstName, lastName, email, address, address2, city, state, zip and phone
billingContact
hash
The customer’s billing details. Includes firstName, lastName, email, address, address2, city, state, zip and phone
items
list
 List of items in cart. Each item object has an imageUrl, detailUrl, name, price, quantity, sku
discounts
list
 List of any discounts applied to the order. Factored into the cart total, unless a customTotal is provided. Each discount has an amount (in cents) and description

asLowAs

hash

Object containing cart information for generating advertising content or financing disclosure.

monthly
integer
“As low as” monthly price as an integer in cents
amount
string
“As low as” monthly price as a formatted string
termLength
integer
“As low as” term length
termInterval
string
“As low as” term interval
apr
float
“As low as” example APR
minApr
float
“As low as” minimum APR
maxApr
float
“As low as” maximum APR
asLowAsText
string
“As low as” financing disclosure

{
  "id": "86279175-3d85-4be7-a368-5615d932ef3c",
  "cartName": "Labor Day Sale 2016",
  "expiration": "2100-01-01",
  "url": "https://checkout.getbread.com/qyi9Qd",
  "isCustomTotal": false,
  "options": {
    "apiKey": "aaaaaaa-0000-bbbb-1111-cccccccccccc",
    "orderRef": "",
    "callbackUrl": "",
    "completeUrl": "http://complete.example.com",
    "errorUrl": "http://error.example.com",
    "shippingOptions": [
      {
        "cost": 1000,
        "type": "Standard",
        "typeId": "std"
      },
      {
        "cost": 2000,
        "type": "Fast",
        "typeId": "fast"
      }
    ],
    "requireShippingContact": true,
    "items": [
      {
        "imageUrl": "http://image.example.com",
        "detailUrl": "http://detail.example.com",
        "name": "Ring",
        "price": 30000,
        "quantity": 1,
        "sku": "i-ring-1"
      },
      {
        "imageUrl": "http://ring.example.com",
        "detailUrl": "http://ring-detail.example.com",
        "name": "Ring 2",
        "price": 45000,
        "quantity": 1,
        "sku": "i-ring-2"
      }
    ],
    "discounts": [
      {
        "amount": 1000,
        "description": "LABOR_DAY"
      }
    ],
    "shippingContact": {
      "firstName": "Carlos",
      "lastName": "Ladron",
      "email": "carlos@example.com",
      "address": "540 W 112th St",
      "address2": "Apt 12",
      "city": "New York",
      "state": "NY",
      "zip": "10025",
      "phone": "5553213443"
    },
    "billingContact": {
      "firstName": "David",
      "lastName": "Ladron",
      "email": "david@example.com",
      "address": "370 W 30th St.",
      "address2": "Apt 11",
      "city": "New York",
      "state": "NY",
      "zip": "10001",
      "phone": "5551233443"
    }
  },
  "asLowAs": {
    "monthly": 3414,
    "amount": "$34.14",
    "termLength": 24,
    "termInterval": "Month",
    "apr": 0.0999,
    "minApr": 0.08,
    "maxApr": 0.2999,
    "asLowAsText": "This example payment is the amount of equal monthly payments on a loan to finance the purchase based on the listed product price of $740.00 assuming a 24-month term and a 9.99% APR. Your terms may vary and are subject to application. Rates range from 8.00% to 29.99% APR. Bread loans are made by Cross River Bank, member FDIC."
  }
}

 

Create a cart

Create preconfigured carts to expedite the checkout process. The response will include a url, the ‘as low as’ monthly rate and the legal disclosure text to be displayed with the rate.

Arguments

orderRef
string | optional
Unique identifer to match with the Bread transaction ID
callbackUrl
string | optional
Where we’ll POST the transaction ID of the checkout and the orderRef following a successful checkout
completeUrl
string | optional
Default: Merchant store url
Where the customer is redirected following a successful checkout, e.g. a confirmation page
createdBy
string | optional
Default: “Merchant API”
The identifier of the creator of the cart.
errorUrl
string | optional
Default: Merchant store url
Where the customer is redirected following an unsuccessful checkout, including if no financing offer is available or if there are technical issues
shippingOptions
list | optional
Array of shipping option(s) the customer can select from when checking out with the cart. Include only one shipping option to preselect this shipping option.

type
string | required
Description of the shipping option, which will be displayed to the customer
typeId
string | required
Identifier for the specific shipping option
cost
integer | required
Cost of the shipping option in cents

 shippingContact
object | optional
The customer’s shipping information. You can pre-populate customer’s shipping information for customers to expedite the checkout flow

firstName
string | required
Customer’s first name
lastName
string | required
Customer’s last name
email
string | optional
Customer’s email
address
string | required
Customer’s address
address2
string | optional
Any continuation of the customer’s address, including apartment number or suite
city
string | required
Customer’s city of residence
state
string | required
Customer’s state of residence. Must be the 2 character abbreviation for a valid US state or the District of Columbia. (ie. NY, DC)
phone
string | optional
Customer’s phone number. A 10 digit phone number with only numeric characters.

 billingContact
object | optional
The customer’s billing information. You can pre-populate customer’s billing information for customers to expedite the checkout flow.

firstName
string | required
Customer’s first name
lastName
string | required
Customer’s last name
email
string | optional
Customer’s email
address
string | required
Customer’s address
address2
string | optional
Any continuation of the customer’s address, including apartment number or suite
city
string | required
Customer’s city of residence
state
string | required
Customer’s state of residence. Must be the 2 character abbreviation for a valid US state or the District of Columbia. (ie. NY, DC)
phone
string | optional
Customer’s phone number. A 10 digit phone number with only numeric characters.

items
list | required, unless customTotal is defined
 Array of items that are a part of the cart

imageUrl
string | required
Image url for the item. This will be displayed to confirm the order on the cart summary page
detailUrl
string | required
Product detail url for the item
name
string | optional
Name of the item
price
integer | required
Price in cents of the item. Unless customTotal is used, this will be used to calculate the total cost with discounts, tax and shipping cost
quantity
integer | required
Number of items in the cart
sku
string | required
Unique sku for the product. Shopify specific documentation available

discounts
list | optional
Discount(s) will be applied to the cart at checkout, unless a customTotal is provided

amount
integer | required
Positive discount amount in cents
description
string | required
Discount description

customTotal
integer| optional, unless items are not defined
The total checkout price of the cart, in cents, including items, shipping cost, taxes and discounts. This value will override any other costs associated with the cart
tax
integer | optional
Represents the amount of tax associated with the cart when customTotal is applied

 

Definition

POST api.getbread.com/carts

Usage

curl https://api.getbread.com/carts/ \
    -u <api-key>:<secret-key> \
    -X POST \
    -H "Content-Type: application/json" \
    -d '{"expiration": "2017-03-31","options": {"orderRef":"merchantProvidedId","callbackUrl": "https://www.sample.com/newBreadTransaction","completeUrl": "https://www.sample.com/successRedirectPage","errorUrl": "https://www.sample.com/fallbackPage","items": [{"imageUrl": "https://www.merchant.com/assets/picture.jpg","detailUrl": "https://www.merchant.com/product/0394j039jf","name": "Super Comfy Mattress","price": 50000,"quantity": 1,"sku": "0349j0394fj"}]}}'

Example response

{
  "expiration": "2017-03-31",
  "createdBy": "Merchant API",
  "options": {
    "orderRef": "merchantProvidedId",
    "callbackUrl": "https://www.sample.com/newBreadTransaction",
    "completeUrl": "https://www.sample.com/successRedirectPage",
    "errorUrl": "https://www.sample.com/fallbackPage",
    "shippingType": "Express",
    "shippingTypeId": "merchantShippingId",
    "shippingCost": 5000,
    "shippingContact": {
      "firstName": "Jennifer",
      "lastName": "Reeves",
      "email": "jreeves@gmail.com",
      "address": "39 West 14th Street",
      "address2": "Suite 403",
      "city": "New York",
      "state": "NY",
      "zip": "10011",
      "phone": "9729899173"
    },
    "billingContact": {
      "fullName": "Jennifer Reeves",
      "email": "jreeves@gmail.com",
      "address": "39 West 14th Street",
      "address2": "Suite 403",
      "city": "New York",
      "state": "NY",
      "zip": "10011",
      "phone": "9729899173"
    },
    "items": [{
      "imageUrl": "https://www.merchant.com/assets/picture.jpg",
      "detailUrl": "https://www.merchant.com/product/0394j039jf",
      "name": "Super Comfy Mattress",
      "price": 50000,
      "quantity": 1,
      "sku": "0349j0394fj"
    }],
    "discounts": [{
      "amount": 10000,
      "description": "$10 Off"
    }]
  }
}

Retrieve a cart

Retrieves the details of a previously created cart. Use the unique cart ID that was returned from your previous request, and Bread will return the corresponding cart information. The same information is returned when creating a cart.

Definition

GET api.getbread.com/carts/:cartId

Usage

curl -u <api-key>:<secret-key> https://api.getbread.com/carts/b6c8caa2-cfcf-418b-ae72-88ee14e5a190

Example response

{
  "id": "34hf9384h-938h4f983-9384h9f384",
  "createdBy": "Merchant API",
  "merchantId": "04j034f-34jf349f-3049jf0-3049jf0394f",
  "url": "https://checkout.getbread.com/checkout/45gh847g",
  "expiration": "2017-01-30",
  "options": { ... } // options saved to cart, defined above
}

 

Expire a cart

Expire a cart to prevent customers from checking out with that url. After a cart is expired, clicking on the cart url will result in an error message.

Definition

POST api.getbread.com/carts/:cartId/expire

Usage

curl  -u <api-key>:<secret-key> -X POST https://api.getbread.com/carts/b6c8caa2-cfcf-418b-ae72-88ee14e5a190/expire

Example Response

HTTP 204 on success

 

Update a cart

Updating a cart via the API is not supported. If an update needs to be made, you can create a new cart and send that to your customers.  If you need to invalidate the old cart, use the /expire endpoint.

Email a cart

Send an email of the cart’s URL using our email template.

Arguments

email
string | required
The email address of the customer whom you’re sending the email to.
name
string | required
The name of the customer whom you’re sending the emailing to.

Definition

POST api.getbread.com/carts/:cartId/email

Usage

curl -X POST \
    https://api.getbread.com/carts/b6c8caa2-cfcf-418b-ae72-88ee14e5a190/email \
    -u '<api-key>:<secret-key&>' \
    -H 'content-type: application/json' \
    -d '{"email": "email@example.com", "name": "John"}'

Example response
HTTP 200 on success

{
  "message": "Email Sent"
}

 

Text a Cart

Send a text of the cart’s URL using our SMS template.

Arguments

phone
string | required
The phone number of the customer whom you’re sending the text to.

Definition

POST api.getbread.com/carts/:cartId/text

Usage

curl -X POST \
  https://api.getbread.com/carts/b6c8caa2-cfcf-418b-ae72-88ee14e5a190/text \
  -u '<api-key>:<secret-key&gt' \
  -H 'content-type: application/json' \
  -d '{"phone": "1234567890"}'

Example response
HTTP 200 on success

{
  "message": "SMS Sent"
}