How can we help?

Search

Orders API

Overview

The orders collection contains all order data related to a purchase event. It's 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.

Collection Association
products A product record will be created or updated in the products collection each time an order is placed.

POST/orders

Method URI Path
POST /orders

Creates a new order in the Cordial database using the appropriate JSON body.

An order can include one or more items. Posting more than one time for the same orderID name will generate an error.

  • Required

    Parameter Type Description Example
    Order
    *contact identifier string Unique primary or secondary contact identifier key/value pair to look up and reference the contact. cID: 54b0143f9e6f974f1e98ba19 or email: mikesmith@example.com
    *orderID string Unique identifier assigned for the order. 33451
    *purchaseDate string A date value signifying the purchase data and time. Date format is ISO 8601.

    2018-01-09T22:47:12+0000
    mcID string Cordial ID that represents the account, contact and the message. Required to track revenue attribution to an email. 45:55....aef:1
    msID string Cordial ID that represents the  message. 45:55....aef:1
    linkID string Cordial ID that represents the message and link. Required to track revenue attribution to a specific link. 45:55....aef:1
    customerID string An ID value assigned by the eCommerce or CRM system. abc123
    totalAmount float Auto-calculated as the sum of each item.amount. 235.99
    tax float The amount of the tax. 22.50
    shippingAndHandling float The amount charged for shipping and handling. 0.0
    shippingAddress object name, address, city, state, postalCode, country. see below
    billingAddress object name, address, city, state, postalCode, country. see below
    properties object Key value pairs describing the properties of the order. "currency": "USD"
    items array of objects Each object describes an item of the order. See parameters per item object below
    Parameters per each item object. The items object is optional—but, if included, product ID, SKU, category, and name parameters are required.
    *productID string A unique identifier for the product. 1234abcd
    *sku string The Stock Keeping Unit value for a particular item. RF-WP33286-21
    *category string The category given to the particular item. Major Appliance
    *name string The name of the product. S22-Refrigerator
    qty integer The number of items purchased. Defaults to 1 if not passed. 2
    itemPrice float The item price. 29.95
    amount float Auto calculated as qty x itemPrice. If a value not equal to qty x itemPrice is passed, it will be overwritten. 59.90
    description string Description of the product. Great product!
    url string Link to the product. http://myproduct.com
    images array A comma separated array of image file locations. Use an empty array [] as default if no values exist. "http://example.com/image1.jpg", "http://example.com/image2.jpg"
    attr object Key value pairs describing attributes of the product. Values added cannot be searched using the Audience Builder or within Smarty for personalization.

    "size":"large",
    "color":"red"
    properties object Can be used in place of the attr key. Values added can be searched using the Audience Builder and within Smarty for personalization, if searching of nested order properties is enabled in the account. "brands":["Marmot", "Quicksilver"], "return_date": "2018-07-01 00:00:00"
    tags array A comma separated array of values to describe the product. Only accepts alphanumeric characters or dashes. "office","office-supplies"
    Optional Parameters for billingAddress and shippingAddress objects
    name string The name of the person or company making the order. Mark Smith
    address string Defines the street address. 13130 Silverlake Road
    city string Defines the city. Hollywood
    state string Defines the state. CA
    postalCode integer Defines the postal code. 90028
    country string Defines the country. USA

  • 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
}

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

    http://<path>/orders

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

1.) The orderID field must be a unique value. 2.) 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. 3.) 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. 4.) One or more items can be included in an order.

GET/orders

Method URI Path
GET /orders
  • Retrieves all orders from the Cordial database.
  • Using query string parameters, it's also possible to filter the response by contactId to retrieve all orders for a single contact, and filter the response by purchaseDate to limit the data to orders on that date and time. purchaseDate can be filtered by date range using gte and lte filters. (e.g. purchaseDate[gte]=2016-11-10&purchaseDate[lt]=2016-11-11) Additionally, it is possible to filter the field set returned using a query string for the parameter fields.
  • When retrieving a large amount of orders in the response, it is also possible to apply the per_page and page query string parameters to limit the count returned and page position.

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.

  • Parameter Type Description Example
    fields string Sets which data fields will be returned. ?fields=shippingAddress
    cID string Unique contact ID to identify and reference the contact. ?cID=5ada55ed132f37e60e63c04d
    email string Unique email address to identify and reference the contact. ?email=msmith@example.com
    purchaseDate string Filters the data by date using gte and lte. ?purchaseDate[gte]=2017-01-10
    page number Page number of results. ?page=3
    per_page number Number of results per page. ?per_page=10
    sort_by string Column to sort by. Note: Works in conjunction with sort_dir. ?sort_by=purchaseDate
    sort_dir string Direction to sort by. Note: Works in conjunction with sort_by. ?sort_by=purchaseDate&sort_dir=desc

  • 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}

Method URI Path
GET /orders/{id}
  • Retrieves a specific order from the Cordial database.
  • The order is defined by the order's unique orderID value.
  • For example, /orders/112233 would return the response data for the order with the orderID value of 112233.
  • Additionally, it is possible to filter the field set returned using a query string for the parameter fields.
  • Parameter Type Description Example
    fields string Sets which data fields will be returned. ?fields=shippingAddress

  • 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}

Method URI Path
PUT /orders
Updates an order in the Cordial database using the appropriate JSON body.

  • Same requirements and schema as the POST method above.

  • The following will update the purchase date of order 33451.

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

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

    http://<path>/orders

DELETE/orders/{id}

Method URI Path
DELETE /orders/{id}

Deletes an order from the Cordial database.

The order id defined by the order's unique orderID value.

For example, /orders/22345 would delete the attribute with the orderID value of 22345.

  • 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.

errorKey Message Modifications
ORDERS_ID_UNIQUE ID must be unique The orderID must be unique.
ORDERS_CID_MCID_NOT_MATCH cID and mcID do not match The Cordial database contact ID and message contact ID do not match.
ORDERS_PRIMARY_FILTER Use only one from existing filters ':primaryKey' OR 'cID' Please use either the primaryKey or cID filter, but not both.
ORDERS_NOT_FOUND Order not found The identifier entered didn't return any results.
ORDERS_INCORRECT_FILTER Time value is incorrect Time input should be in ISO 08601 formate (e.g. YYY-MM-DDThh:mm:ss).
ORDERS_CONTACT_NOT_FOUND Must include customPK or secondaryKey customPK,email,cID,firebase,push Ensure the contact information has been input correctly.

Comments

0 comments

Please sign in to leave a comment.