Update Order

Update an existing order using the Bronto-generated order ID.

Overview

If you want to update an order using the order ID generated by your system, use Update Order By Customer Order Id. Properties that are not included in the request body will remain unchanged on the existing order. No properties are required in the update.

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.

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.

Note: If you have a workflow that is triggered by an Order Is Added trigger node, that workflow will only be triggered for an order the first time an order’s status is changed to PROCESSED. This is true both when a PENDING order in Bronto transitions to PROCESSED or if an order with the PROCESSED status is added directly to Bronto.

This request requires an access token with “orders/carts-write” scope. If the request is successful, a 200 OK response will be returned with the latest version of the Order in the response body. 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.

URI

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

Parameters

Parameter Type Description
orderId String The Bronto-generated unique order ID for the order you want to update.
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 update the order.

{
    status:PENDING | PROCESSED
    discountAmount:number
    emailAddress:validly formatted email address
    contactId:string
    grandTotal:number
    lineItems:[
      {
        name:string
        description:string
        sku:string
        other:string
        imageUrl:string
        category:string
        productUrl:string
        quantity:number
        salePrice:number
        totalPrice:number
        unitPrice:number
      }
    ]
    messageId:string    
    originIp:IPv4 or IPv6 address
    originUserAgent:string
    shippingAmount:number
    shippingDate:ISO-8601 datetime
    shippingDetails:string
    shippingTrackingUrl:string
    subtotal:number
    taxAmount:number
    trackingCookieName:string
    trackingCookieValue:string
    deliveryId:string
    orderDate:ISO-8601 datetime
    currency:ISO-4217 currency code
    tid:string
    states: {
      processed:boolean
      shipped:boolean
    }
}

Response

A response containing the updated order.

{
    emailAddress:validly formatted email address
    contactId:string
    orderDate:ISO-8601 datetime
    status:PENDING | PROCESSED
    hasTracking:boolean
    trackingCookieName:string
    trackingCookieValue:string
    deliveryId:string
    customerOrderId: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
      }
    ]
    messageId:string    
    originIp:IPv4 or IPv6 address
    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
    states: {
      processed:boolean
      shipped:boolean
    }
    orderId:UUID
}

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 UpdateOrderExample {
 
  // 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 UPDATE_ORDER_PATH = "orders/{orderId}";
  private static final String ORDER_ID = "orderId";
  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";
 
  // Id of the Order we are updating
  private static final String EXAMPLE_ORDER_ID = "0ad24370-96de-4922-9a53-954530fcbb64";
 
 
  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 update the 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", "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> orderData = new HashMap<String, Object>(2);
    orderData.put("emailAddress", "example@email.com");
    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("status", "PROCESSED");
    orderData.put("originIp", "127.0.0.1");
    orderData.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");
    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", "http://www.shipping.com/1234");
 
    // Update the Order
    Response orderResponse = client.target(BRONTO_HOST)
        .path(UPDATE_ORDER_PATH)
        .resolveTemplate(ORDER_ID, EXAMPLE_ORDER_ID)
        .queryParam(CREATE_CONTACT, true)
        .queryParam(IGNORE_INVALID_TRACKING, true)
        .request(MediaType.APPLICATION_JSON)
        .header("Authorization", "Bearer " + accessToken.toString())
        .post(Entity.json(orderData));
 
    if (orderResponse.getStatus() == Response.Status.NOT_FOUND.getStatusCode()) {
      throw new RuntimeException("No Order found with orderId=" + EXAMPLE_ORDER_ID);
    } else if (orderResponse.getStatus() != Response.Status.OK.getStatusCode()) {
      String reason = orderResponse.getHeaderString(REASON_HEADER);
      throw new RuntimeException("Unable to update Order. Reason=" + reason);
    }
 
    // Retrieve the Order from the response
    Map<String, Object> order = orderResponse.readEntity(Map.class);
    System.out.println(order);
  }
}

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" https://auth.bronto.com/oauth2/token
	      
# Replace YOUR_ACCESS_TOKEN with your returned token and replace YOUR_ORDER_ID with an order ID.
curl -i -X POST -H "Content-type: application/json" -H "Authorization: Bearer YOUR_ACCESS_TOKEN" -H "Cache-Control: no-cache" "https://rest.bronto.com/orders/YOUR_ORDER_ID?createContact=true" -d'{"lineItems":[{"quantity":1,"totalPrice":1.23},{"quantity":13,"totalPrice":15.99}]}'