Add Cart

This call can be used to create a new cart. If your cart includes lineItems, then the customerCartId, quantity, and totalPrice fields are required for each lineItem.

Overview

You can provide tracking attribution by including a tid with your request or a TrackingCookieName and TrackingCookieValue pair. For more information see Orders REST API Tracking Attribution.

This request requires an access token with “orders/carts-write” scope. If the request is successful, a 201 Created response will be returned with the newly created Cart in the response body. If a Cart with the same customerCartId already exists, a 409 Conflict response will be returned.

URI

POST: https://rest.bronto.com/carts?createContact={boolean}&ignoreInvalidTid={boolean}

Parameters

Parameter Type Description
createContact Optional Boolean Determines behavior when the request contains an email address that is not associated with a Contact. If true, a transactional Contact will be created. If false, the service will return a 409 Conflict response. The default value is false.
ignoreInvalidTid Optional Boolean Determines behavior when the request contains an invalid TID orTrackingCookieName and TrackingCookieValue pair. If true, the service will ignore the invalid values and continue.

Request Body

Cart data used to create the cart.

{
    url: string
    customerCartId: string
    discountAmount: number
    emailAddress: validly formatted email address
    contactId:string
    grandTotal: number
    deliveryId:string
    lineItems: [
      {
        name: string
        description: string
        sku: string
        other: string
        imageUrl: string
        category: string
        productUrl: string
        quantity: number
        salePrice: number
        totalPrice: number
        unitPrice: number
      }
    ]
    originIp: string
    messageId:string
    originUserAgent: string
    shippingAmount: number
    shippingDate: ISO-8601 datetime
    shippingDetails: string
    shippingTrackingUrl: string
    subtotal: number
    taxAmount: number
    trackingCookieName: string
    trackingCookieValue: string
    tid:string
    phase: SHOPPING | BILLING | PAYMENT | SHIPPING_INFO | SHIPPING_METHOD | ORDER_REVIEW | ORDER_COMPLETE
    currency: ISO-4217 currency code
}

Response

A response containing the newly created cart.

{
    url:string
    emailAddress:validly formatted email address
    contactId:string
    status:ACTIVE | ABANDONED | EXPIRED | COMPLETE
    phase:SHOPPING | BILLING | PAYMENT | SHIPPING_INFO | SHIPPING_METHOD | ORDER_REVIEW | ORDER_COMPLETE
    hasTracking:boolean
    customerCartId:string
    trackingCookieName:string
    trackingCookieValue:string
    deliveryId:string
    discountAmount:number
    grandTotal:number
    lineItems:[
      {
        name:string
        other:string
        sku:string
        category:string
        imageUrl:string
        productUrl:string
        quantity:number
        salePrice:number
        totalPrice:number
        unitPrice:number
        description:string
        position:number
      }
    ]
    originIp:IPv4 or IPv6 address
    messageId:string
    originUserAgent:string
    shippingAmount:number
    shippingDate:ISO-8601 datetime
    shippingDetails:string
    shippingTrackingUrl:string
    subtotal:number
    taxAmount:number
    cartId:UUID
    createdDate:ISO-8601 datetime
    updatedDate:ISO-8601 datetime
    currency:ISO-4217 currency code
}

Java Code Example

import java.util.Arrays;
import java.util.HashMap;
import java.util.Map;
import java.util.UUID;
 
import javax.ws.rs.client.Client;
import javax.ws.rs.client.ClientBuilder;
import javax.ws.rs.client.Entity;
import javax.ws.rs.core.Form;
import javax.ws.rs.core.MediaType;
import javax.ws.rs.core.Response;
 
 
public class AddCartExample {
 
  // Host
  private static final String BRONTO_HOST = "http://rest.bronto.com";
  private static final String BRONTO_AUTH_PATH = "https://auth.bronto.com/oauth2/token";
 
  // Paths
  private static final String ADD_CART_PATH = "carts";
  private static final String CREATE_CONTACT = "createContact";
  private static final String IGNORE_INVALID_TRACKING = "ignoreInvalidTracking";
 
  // OAuth Request property names
  private static final String GRANT_TYPE = "grant_type";
  private static final String CLIENT_ID = "client_id";
  private static final String CLIENT_SECRET = "client_secret";
 
  // OAuth Request property values
  private static final String CLIENT_CREDENTIALS = "client_credentials";
  private static final String EXAMPLE_CLIENT_ID = "XXXXXXXXXXXXXXXXXXXXXXX";
  private static final String EXAMPLE_CLIENT_SECRET = "XXXXXXXXXXXXXXXXXXXXXXX";
 
  private static final String ACCESS_TOKEN = "access_token";
 
  private static final String REASON_HEADER = "X-Reason";
 
 
  public static void main(String[] args) {
    Client client = ClientBuilder.newClient();
 
    // To be able to access Orders Rest API, you need an access token.
    // First, we build the request data needed to gain an access token
    Form requestData = new Form();
    requestData.param(GRANT_TYPE, CLIENT_CREDENTIALS);
    requestData.param(CLIENT_ID, EXAMPLE_CLIENT_ID);
    requestData.param(CLIENT_SECRET, EXAMPLE_CLIENT_SECRET);
 
    // Then build and send the request
    Response oauthResponse = client.target(BRONTO_AUTH_PATH)
        .request(MediaType.APPLICATION_JSON)
        .accept(MediaType.TEXT_PLAIN_TYPE)
        .post(Entity.form(requestData));
 
    if (oauthResponse.getStatus() != Response.Status.OK.getStatusCode()) {
      throw new RuntimeException("Unable to get access token.");
    }
 
    // Retrieve the access token from the response
    Map<String, Object> responseData = oauthResponse.readEntity(Map.class);
    UUID accessToken = UUID.fromString((String) responseData.get(ACCESS_TOKEN));
 
    // Now to add a Cart, we first build the request data
    Map<String, Object> lineItemData = new HashMap<String, Object>(2);
    lineItemData.put("name", "Coffee Mug");
    lineItemData.put("description", "A cool coffee mug");
    lineItemData.put("category", "Kitchen Stuffs");
    lineItemData.put("other", "5oz");
    lineItemData.put("imageUrl", "http://www.example.com/images/0003105.jpg");
    lineItemData.put("productUrl", "http://www.example.com/products/0003105");
    lineItemData.put("sku", "0003105");
    lineItemData.put("quantity", 1);
    lineItemData.put("totalPrice", 3.99f);
    lineItemData.put("unitPrice", 3.99f);
    lineItemData.put("salePrice", 3.99f);
 
    Map<String, Object> cartData = new HashMap<String, Object>(2);
    cartData.put("customerCartId", "abc-123");
    cartData.put("emailAddress", "example@email.com");
    cartData.put("currency", "USD");
    cartData.put("grandTotal", 4.27f);
    cartData.put("discountAmount", 0);
    cartData.put("taxAmount", 0.28f);
    cartData.put("subtotal", 3.99f);
    cartData.put("lineItems", Arrays.asList(lineItemData));
    cartData.put("phase", "SHOPPING");
    cartData.put("url", "http://www.example.com/carts/abc-123");
    cartData.put("originIp", "127.0.0.1");
    cartData.put("originUserAgent",
                 "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_9_4) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/46.0.2490.71 Safari/537.36");
    cartData.put("trackingCookieName", "tid_blkycggbjquivddbiddxylaufhfdbkj");
    cartData.put("trackingCookieValue", "3.Ag.AQ.AQ.AQ.AQ.AQ.t..l.AQ.n.VO4AkA.VO4AkA.G89Jow");
    cartData.put("shippingAmount", 0);
    cartData.put("shippingDate", "2015-01-02");
    cartData.put("shippingDetails", "Free next day shipping");
    cartData.put("shippingTrackingUrl", "http://www.shipping.com/1234");
 
    // Add the Cart
    Response cartResponse = client.target(BRONTO_HOST)
        .path(ADD_CART_PATH)
        .queryParam(CREATE_CONTACT, true)
        .queryParam(IGNORE_INVALID_TRACKING, true)
        .request(MediaType.APPLICATION_JSON)
        .header("Authorization", "Bearer " + accessToken.toString())
        .post(Entity.json(cartData));
 
    if (cartResponse.getStatus() != Response.Status.CREATED.getStatusCode()) {
      String reason = cartResponse.getHeaderString(REASON_HEADER);
      throw new RuntimeException("Unable to add Cart. Reason=" + reason);
    }
 
    // Retrieve the Cart from the response
    Map<String, Object> cart = cartResponse.readEntity(Map.class);
    System.out.println(cart);
  }
}