Update Order

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.

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

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}]}'