Add Order

Allows you to add a new order.


This request accepts both representations of an order’s state via the “states” and “status” fields. Updates to either field will be reflected in the other. The “status” field is currently deprecated and it is recommended that you use the “states” field going forward. If both “status” and “states” are both specified, the data supplied in “status” will be used.

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 Order in the response body. If an Order or Return with the same customerOrderId already exists, a 409 Conflict response will be returned. If there is a problem with any of the data in the request body, a 400 Bad Request response will be returned with an explanation of the error. If the orderDate is earlier than January 1st, 2000 or more than 5 years in the future, then the order request is rejected with a 400 Bad Request response.

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.




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.
triggerEvents Optional Boolean Determines whether workflows or other contact interactions can be triggered by the state of this order. If false, workflow nodes do not fire. The default value is true.
force Optional Boolean Determines whether workflows or other contact interactions will be triggered by the state of this order, regardless of whether the state has changed. If true, an order that is currently processed will re-trigger, potentially re-triggering a workflow that might message the customer. If false, workflows and other contact interactions are only triggered when the state changes, such as a pending order changing to processed.
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

The Order data used to create the Order.

import java.util.Arrays;
import java.util.HashMap;
import java.util.Map;
import java.util.UUID;
public class AddOrderExample {
  // Host
  private static final String BRONTO_HOST = "";
  private static final String BRONTO_AUTH_PATH = "";
  // Paths
  private static final String ADD_ORDER_PATH = "orders";
  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 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);
    // Then build and send the request
    Response oauthResponse =
    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 an Order, 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", "");
    lineItemData.put("productUrl", "");
    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> orderData = new HashMap<String, Object>(2);
    orderData.put("customerOrderId", "abc-123");
    orderData.put("cartId", "7255c31c-39ac-4611-a2b7-974b0ebfa555");
    orderData.put("emailAddress", "");
    orderData.put("currency", "USD");
    orderData.put("grandTotal", 4.27f);
    orderData.put("discountAmount", 0);
    orderData.put("taxAmount", 0.28f);
    orderData.put("subtotal", 3.99f);
    orderData.put("lineItems", Arrays.asList(lineItemData));
    orderData.put("orderDate", "2015-01-01");
    orderData.put("status", "PROCESSED");
    orderData.put("originIp", "");
                  "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");
    orderData.put("trackingCookieName", "tid_blkycggbjquivddbiddxylaufhfdbkj");
    orderData.put("trackingCookieValue", "3.Ag.AQ.AQ.AQ.AQ.AQ.t..l.AQ.n.VO4AkA.VO4AkA.G89Jow");
    orderData.put("shippingAmount", 0);
    orderData.put("shippingDate", "2015-01-02");
    orderData.put("shippingDetails", "Free next day shipping");
    orderData.put("shippingTrackingUrl", "");
    // Add the Order
    Response orderResponse =
        .queryParam(CREATE_CONTACT, true)
        .queryParam(IGNORE_INVALID_TRACKING, true)
        .header("Authorization", "Bearer " + accessToken.toString())
    if (orderResponse.getStatus() != Response.Status.CREATED.getStatusCode()) {
      String reason = orderResponse.getHeaderString(REASON_HEADER);
      throw new RuntimeException("Unable to add Order. Reason=" + reason);
    // Retrieve the Order from the response
    Map<String, Object> order = orderResponse.readEntity(Map.class);

cURL Example

# Run the following cURL command after replacing YOUR_ID and YOUR_SECRET with the values from your REST Integration.
curl -X POST -d "grant_type=client_credentials&client_id=YOUR_ID&client_secret=YOUR_SECRET"

# Replace YOUR_ACCESS_TOKEN with your returned token and update the customerOrderID value (ABC-2018-10-11-A) to a real customerOrderId.
curl -i -X POST -H "Content-type: application/json" -H "Authorization: Bearer YOUR_ACCESS_TOKEN" -H "Cache-Control: no-cache" "" -d'{"customerOrderId":"ABC-2018-10-11-A"}'