Overview

The Orders Collection contains all order data related to a purchase event. It is a separate collection designed specifically to accommodate data associated with orders. The most common order-related attributes are provided by default as part of the schema.

• API set name: orders

Related collections

The following collections are associated with the Orders Collection.

POST /orders

Parameters

* Required

Example JSON requests

Simple example (minimum requirements)

{
  "orderID": "33451",
  "purchaseDate": "2018-01-09T22:47:12+0000",
  "email": "marksmith@example.com"
}

Kitchen sink example (optional fields included)

{
  "orderID": "33451",
  "email": "marksmith@example.com",
  "purchaseDate": "2018-01-09T22:47:12+0000",
  "linkID": "55373eed6c87669bw",
  "mcID": "45:55373eed6c87669bwewewee7:ot:55375ba27ec3343a77ce07ec:1422343949",
  "customerID": "5432225",
  "properties": {
    "color": "red",
    "size": "large",
    "currency": "USD"
  },
  "shippingAddress": {
    "name": "Mark Smith",
    "address": "13130 Silverlake Road",
    "city": "Los Angeles",
    "state": "CA",
    "postalCode": 92332,
    "country": "USA"
  },
  "billingAddress": {
    "name": " Mark Smith ",
    "address": "13130 Silverlake Road",
    "city": "Los Angeles",
    "state": "CA",
    "postalCode": 92332,
    "country": "USA"
  },
  "items": [
    {
      "productID": "1234abcd",
      "sku": "ssd-2344-15",
      "description": "This shirt is amazing!",
      "category": "Shirts",
      "name": "Awesome Flannel",
      "qty": 1,
      "url": "http://awesomeflannels.com/1234abcd",
      "itemPrice": 129.95,
      "images": [
        "http://awesomeflannels.com/image_1.jpg",
        "http://awesomeflannels.com/image_2.jpg"
      ],
      "tags": [
        "flannels",
        "winter"
      ],
      "properties": {
        "brands": [
          "Marmot",
          "Quicksilver"
        ],
        "return_date": "2018-07-09T22:47:12+0000"
      },
      "attr": {
        "color": "red",
        "size": "large"
      }
    }
  ],
  "tax": 7,
  "shippingAndHandling": 0
}

Add order and item properties

The properties parameter can be used to insert additional custom order and item values. Values added using the properties attribute will become available for segmenting audiences using the Audience Builder.  Please use the properties parameter in place of the attr parameter if you want it to be searchable.

Example of adding order properties

{
  "orderID": "33451",
  "properties": {
    "color": "red",
    "size": "large",
    "currency": "USD"
  },
  "items": [
    {
      "productID": "1234abcd",
      "name": "Red Flannel",
      "category": "shirts",
      "sku": "ssd-2344-15",
      "tags": [
        "flannels",
        "winter"
      ]
    }]
}

Example of adding order item properties

{
  "orderID": "33451",
  "items": [
    {
      "productID": "1234abcd",
      "name": "Red Flannel",
      "category": "shirts",
      "sku": "ssd-2344-15",
      "tags": [
        "flannels",
        "winter"
      ],
      "properties": {
        "brands": [
          "Marmot",
          "Quicksilver"
        ]
      }
    }]
}

Work with multiple shipping addresses

The shippingAddress and billingAddress parameters are part of the default kitchen sink order object. However, your order data may contain a secondary ship-to address as well as a separate ship-to address for each order item. Using the order and order item properties parameter, you can pass additional address fields as custom order and item values.

Adding a custom secondary shipping address using order properties:

{
  "orderID": "33451",
  "email": "marksmith@example.com",
  "purchaseDate": "2018-01-09T22:47:12+0000",
  "properties": {
    "shippingAddress2": {
      "name": "Mark Smith",
      "address": "5555 Park Avenue",
      "city": "Los Angeles",
      "state": "CA",
      "postalCode": 90038,
      "country": "USA"
    }
  },
  "shippingAddress": {
    "name": "Mark Smith",
    "address": "13130 Silverlake Road",
    "city": "Los Angeles",
    "state": "CA",
    "postalCode": 92332,
    "country": "USA"
  },
  "billingAddress": {
    "name": " Mark Smith ",
    "address": "13130 Silverlake Road",
    "city": "Los Angeles",
    "state": "CA",
    "postalCode": 92332,
    "country": "USA"
  }
}

Adding a custom order item shipping address using order item properties:

{
  "orderID": "33451",
  "email": "marksmith@example.com",
  "purchaseDate": "2018-01-09T22:47:12+0000",
  "properties": {
    "color": "red",
    "size": "large",
    "currency": "USD"
  },
  "items": [
    {
      "productID": "1234abcd",
      "name": "Red Flannel",
      "category": "shirts",
      "sku": "ssd-2344-15",
      "tags": [
        "flannels",
        "winter"
      ],
      "properties": {
        "itemShipAddress": {
          "name": "Mark Smith",
          "address": "5555 Park Avenue",
          "city3": "Los Angeles",
          "state": "CA",
          "postalCode": 90038,
          "country": "USA"
        }
      }
    }
  ]
}

Note:

• The orderID field must be a unique value.
• The contact identifier primary or secondary key field is required. This is the unique identifier for the contact. Cordial does not accept anonymous order records.
• mcID or linkID are required if you need to attribute the order to a specific message or link within a message. These can be passed in the link as linkID={$linkID}&mcID={$mcID} and stored in a session variable for use in the API
• One or more items can be included in an order.

Example POST /orders request URIs

The following URI in conjunction with the JSON will perform the POST.

http://<path>/orders

GET /orders

The GET /orders endpoint can retrieve up to 10,000 records at a time. To page through more than 10,000 records, multiple queries must be made with manually adjusted parameters for each.

Parameters

Example GET /orders request URIs

The following URI will retrieve all orders and include all fields.

http://<path>/orders

The following URI will retrieve all orders, but only include the field data for the "shippingAddress".

http://<path>/orders?fields=shippingAddress

The following URI will retrieve all orders, and include the field data for both "totalAmount" and "tax".

http://<path>/orders?fields=totalAmount,tax

The following URI will retrieve all orders with a purchaseDate greater than "2017-11-10".

https://api.cordial.io/v1/orders?purchaseDate[gt]=2017-11-10

The following URI will retrieve all orders where the purchaseDate is between "2017-01-10" and "2017-01-11".

https://api.cordial.io/v1/orders?purchaseDate[gte]=2017-01-10&purchaseDate[lte]=2017-01-11

The following URI will retrieve all orders starting from the third page grouping contacts by 10. For example, page 1 would have included the first 10, page 2 the second group of 10 and so on.

http://<path>/orders?page=3&per_page=10

The following URI will retrieve all orders associated with the specified batch message ID (msID).

https://api.cordial.io/v1/orders?msID=45:58d99989486e542f5291c5b8:ot

The following URI will retrieve all orders associated with the specified automation template ID (mdtID).

https://api.cordial.io/v1/orders?mdtID=5b83b2e161c95f012b8255d6

GET /orders/{id}

Parameters

Example GET /orders/{id} request URIs

Return records filtered by ID

The following URI will retrieve an order where the id value is 128.

http://<path>/orders/128

Return records filtered by ID field

The following URI will retrieve an order where the id value is 128, but only include the field data for the shippingAddress.

http://<path>/orders/128?fields=shippingAddress

Return records filtered by ID multiple fields

The following URI will retrieve an order where the id value is 128, and include the field data for both totalAmount and tax.

http://<path>/orders/128?fields=totalAmount,tax

PUT /orders{id}

Example JSON request

The following will update the purchase date of order 33451.

{
  "email": "marksmith@example.com",
  "orderID": "33451",
  "purchaseDate": "2018-01-10T22:47:12+0000"
}

Example PUT /orders request URIs

The following URI in conjunction with the JSON will perform the PUT.

http://<path>/orders

Parameters

Same requirements and schema as the POST method above.

DELETE /orders/{id}

Example DELETE /orders/{id} request URIs

The following URI will delete an order where the id value is 128.

http://<path>/orders/128

Error responses

The Cordial API will return an error object with an errorKey and message if there is a problem with an API call. Below is a list of errors specific to the Orders API endpoint, along with suggested modifications to resolve each error. If you receive an error from this API endpoint that is not listed in this table, it is likely recorded within the Global API error responses page.