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.

POST api.getbread.com/carts
{
  "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"
      }
    ]
  }
}
curl https://api.getbread.com/carts/ \
    -u <api-key>:<secret-key> \
    -X POST \
    -H "Content-Type: application/json" \
    -d '{"expiration": "2021-05-27","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"}]}}'
{
  "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": "[email protected]",
      "address": "39 West 14th Street",
      "address2": "Suite 403",
      "city": "New York",
      "state": "NY",
      "zip": "10011",
      "phone": "9729899173"
    },
    "disableEditShipping": "false",
    "billingContact": {
      "fullName": "Jennifer Reeves",
      "email": "[email protected]",
      "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"
    }]
  }
}
ArgumentsType | RequiredParent AttributeDescription
orderRefstring | optionaloptionsUnique identifier to match with the Bread transaction ID
callbackUrlstring | optionaloptionsWhere we’ll POST the transaction ID of the checkout and the orderRef following a successful checkout

The POST body will be JSON in the format of:
{
“transactionId”: “addfa809-f4d5-4540-8902-0da4e3fd53c0”,
“orderRef”: “ABCD1234”
}
completeUrlstring | optionaloptionsWhere the customer is redirected following a successful checkout, e.g. a confirmation page.

The completeUrl will be appended with query parameters of the transactionId and orderRef in the format of:
https://www.merchant.com/orderConfirmation?orderRef=ABCD1234&transactionId=addfa809-f4d5-4540-8902-0da4e3fd53c0
createdBystring | optionaloptionsThe identifier of the creator of the cart.
errorUrlstring | optionaloptionsSet to true for a flat cost Cart link, false for Cart link with line items.
shippingOptionsarray | optionaloptionsArray 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)
typestring | requiredshippingOptionsDescription of the shipping option, which will be displayed to the customer
typeIdstring | requiredshippingOptionsIdentifier for the specific shipping option
costinteger | requiredshippingOptionsCost of the shipping option in cents
shippingContactobject | optionaloptionsThe customer’s shipping details. Includes firstName, lastName, email, address, address2, city, state, zip and phone
firstNamestring | requiredshippingContactCustomer’s first name
lastNamestring | requiredshippingContactCustomer’s last name
emailstring | requiredshippingContactCustomer’s email
addressstring | requiredshippingContactCustomer’s address
address2string | requiredshippingContactAny continuation of the customer’s address, including apartment number or suite
citystring | requiredshippingContactCustomer’s city of residence
statestring | requiredshippingContactCustomer’s state of residence. Must be the 2 character abbreviation for a valid US state or the District of Columbia. (ie. NY, DC)
phonestring | requiredshippingContactCustomer’s phone number. A 10 digit phone number with only numeric characters
billingContactobject | optionaloptionsThe customer’s billing details. Includes firstName, lastName, email, address, address2, city, state, zip and phone
firstNamestring | requiredbillingContactCustomer’s first name
lastNamestring | requiredbillingContactCustomer’s last name
emailstring | requiredbillingContactCustomer’s email
addressstring | requiredbillingContactCustomer’s address
address2string | requiredbillingContactAny continuation of the customer’s address, including apartment number or suite
citystring | requiredbillingContactCustomer’s city of residence
statestring | requiredbillingContactCustomer’s state of residence. Must be the 2 character abbreviation for a valid US state or the District of Columbia. (ie. NY, DC)
phonestring | requiredbillingContactCustomer’s phone number. A 10 digit phone number with only numeric characters
itemsarray | conditional

required if customTotal is not defined
optionsList of items in cart. Each item object has an imageUrl, detailUrl, name, price, quantity, sku
imageUrlstring | requireditemsImage url for the item. This will be displayed to confirm the order on the cart summary page
detailUrlstring | requireditemsProduct detail url for the item
namestring | optionalitemsName of the item
priceinteger | requireditemsPrice in cents of the item. Unless customTotal is used, this will be used to calculate the total cost with discounts, tax and shipping cost
quantityinteger | requireditemsNumber of items in the cart
skustring | requireditemsUnique sku for the product. Shopify specific documentation available
discountsarray | optionaloptionsList of objects 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
amountinteger | requireddiscountsPositive discount amount in cents
descriptionstring | requireddiscountsDiscount description
customTotalinteger | conditional

required if items are not defined
optionsThe 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
taxinteger | optionaloptionsRepresents the amount of tax associated with the cart when customTotal is applied
disableEditShippingboolean | optionaloptionsHide shipping address in cart to prevent customer from changing shipping address. By default, set to “false”