Overview

This article details how to place, update, retrieve, and delete data from the orders collection using REST API calls. 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

Authentication

Cordial's core APIs use HTTPS Basic Authentication (BA). From within the Cordial platform, you can generate an encoded API key for your account and use it for authorization.

• Learn more about Cordial API authentication here.

Related collections

The following collections are associated with the orders collection.

Methods, parameters, and examples

• POST/v2/orders
• GET/v2/orders
• GET/v2/orders/{id}
• PUT/v2/orders/{id}
• DELETE/v2/orders/{id}

POST/v2/orders

• * Required

  Base level parameters
  Parameter	Type	Description	Example
  * orderID	string	Unique identifier assigned for the order.	33451
  * cID	string	Unique primary or secondary contact identifier (key/value pair) to look up and reference the contact.	cID: "1234abcd" or email: "mikesmith@example.com"
  * purchaseDate	string	A date value signifying the purchase data and time. Date format is ISO 8601.	2025-01-09T22:47:12+0000
  linkID	string	Cordial ID that represents the message and link. * Required to track revenue attribution to a specific link.	45:55....aef:1
  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
  customerID	string	An ID value assigned by the eCommerce or CRM system.	abc123
  properties	object	Key value pairs describing the properties of the order. Learn how to add custom order and item values using the properties object here.	"currency": "USD"
  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
  shippingAdress and billingAddress object parameters Find out how to work with multiple shipping addresses here
  name	string	The name of the person or company making the order and/or who the order will be shipped to	Mark Smith
  address	string	Defines the street address	13130 Silverlake Road
  city	string	Defines the city	Los Angeles
  state	string	Defines the state	CA
  postalCode	integer	Defines the postal code	90028
  country	string	Defines the country	USA
  items object parameters The items object is optional—but, if included, productID, 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	https://myproduct.com
  images	array	A comma separated array of image file locations. Use an empty array [] as default if no values exist.	"https://example.com/pic.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":["Cool Brand", "Other Cool Brand"], "return_date": "2025-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"
  discountApplication object parameters If discountApplication is included, type and amount are required.
  discountApplication	object	Calculates a specified discount to arrive at a final sales price. Calculate the final amount as: totalAmount = totalAmount - discountApplication.amount  When discountApplication.amount is zero or not present: Calculate totalAmount without any changes.	For a $10 discount: "discountApplication": { "type": "fixed", "amount": 10.00 }
  type	string	Type of discount. This API accepts discounts of fixed amounts.	fixed
  amount	integer	amount of discount	10.00

• Basic example (minimum requirements)

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

  All optional fields included

  {
    "orderID": "33451",
    "email": "marksmith@example.com",
    "purchaseDate": "2025-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": "https://awesomeflannels.com/1234abcd",
        "itemPrice": 129.95,
        "images": [
          "https://awesomeflannels.com/image_1.jpg",
          "https://awesomeflannels.com/image_2.jpg"
        ],
        "tags": [
          "flannels",
          "winter"
        ],
        "properties": {
          "brands": [
            "Cool Brand",
            "Other Cool Brand"
          ],
          "return_date": "2025-07-09T22:47:12+0000"
        },
        "attr": {
          "color": "red",
          "size": "large"
        }
      }
    ],
    "discountApplication": {
      "type": "fixed",
      "amount": 10.00
    },
    "tax": 7,
    "shippingAndHandling": 0
  }

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

  https://<path>/v2/orders

Custom order and item values

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. 

Use the properties parameter in place of the attr parameter if you want it to be searchable.

• Example of adding custom 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 custom items 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.

• Add a custom secondary shipping address using order properties:

  {
    "orderID": "33451",
    "email": "marksmith@example.com",
    "purchaseDate": "2025-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"
    }
  }
  

  Add a custom order item shipping address using items properties:

  {
    "orderID": "33451",
    "email": "marksmith@example.com",
    "purchaseDate": "2025-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/v2/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.

• 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 URL will retrieve all orders and include all fields.

  https://<path>/v2/orders

  The following URL will retrieve all orders, but only include the fields data for shippingAddress

  https://<path>/v2/orders?fields=shippingAddress

  The following URL will retrieve all orders, and include the fields data for both totalAmount and tax

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

  The following URL will retrieve all orders with a purchaseDate greater than 2024-11-10

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

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

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

  The following URL 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.

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

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

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

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

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

GET/v2/orders/{id}

• Parameter	Type	Description	Example
  fields	string	Sets which data fields will be returned.	?fields=shippingAddress

• Return records filtered by ID

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

  https://<path>/v2/orders/128

  Return records filtered by ID field

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

  https://<path>/v2/orders/128?fields=shippingAddress

  Return records filtered by ID multiple fields

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

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

PUT/v2/orders{id}

• 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": "2025-01-10T22:47:12+0000"
  }

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

  https://<path>/v2/orders

DELETE/v2/orders/{id}

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

  https://<path>/v2/orders/128

Test in Swagger

You can access and test Cordial's APIs in Swagger.

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.