# How can we help?

## Overview

This article details how to place, update, retrieve, and delete data from the [orders collection](https://support.cordial.com/hc/en-us/articles/115005528568) 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](https://support.cordial.com/hc/en-us/articles/115005365087) and use it for authorization.

- [Learn more about Cordial API authentication here](httpss://support.cordial.com/hc/en-us/articles/203885498-RESTful-API-summary-and-usage#authentication).

## Related collections

The following collections are associated with the orders collection.

| Collection | Association |
| --- | --- |
| [products](https://support.cordial.com/hc/en-us/articles/115005528548) | A product record will be created or updated in the products collection each time an order is placed. |

## Methods, parameters, and examples

- [POST/v2/orders](https://support.cordial.com/hc/en-us/articles/204570677-Orders-API#postOrders)
- [GET/v2/orders](https://support.cordial.com/hc/en-us/articles/204570677-Orders-API#getOrders)
- [GET/v2/orders/{id}](https://support.cordial.com/hc/en-us/articles/204570677-Orders-API#getOrdersId)
- [PUT/v2/orders/{id}](https://support.cordial.com/hc/en-us/articles/204570677-Orders-API#putOrdersId)
- [DELETE/v2/orders/{id}](https://support.cordial.com/hc/en-us/articles/204570677-Orders-API#deleteOrdersId)

## POST/v2/orders

| Method | URL Path |
| --- | --- |
| POST | /v2/orders |
| Creates a new order in the Cordial database using the appropriate JSON body.<br>An order can include one or more items. Posting more than one time for the same `orderID` name will generate an error. |

- [Parameters](https://support.cordial.com/hc/en-us/articles/204570677-Orders-API#zp-1-0)
- [Example JSON requests](https://support.cordial.com/hc/en-us/articles/204570677-Orders-API#zp-1-1)
- [Example request URL](https://support.cordial.com/hc/en-us/articles/204570677-Orders-API#zp-1-2)

\* 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<br>`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](https://support.cordial.com/hc/en-us/articles/204570677-Orders-API#itemOrderProperties). | `"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<br>- [Find out how to work with multiple shipping addresses here](https://support.cordial.com/hc/en-us/articles/204570677-Orders-API#multipleAddresses)
| Parameter | Type | Description | Example |
| --- | --- | --- | --- |
| `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<br>The `items` object is optional—but, if included, `productID`, `sku`, `category`, and `name` parameters are required.
| Parameter | Type | Description | Example |
| --- | --- | --- | --- |
| \*`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<br> 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](https://support.cordial.com/hc/en-us/articles/115005532168) or within [Smarty](https://support.cordial.com/hc/en-us/articles/115005691407) for personalization. | `"size":"large",<br>"color":"red"` |
| `properties` | object | Can be used in place of the `attr` key. Values added **can be** searched using the [Audience Builder](https://support.cordial.com/hc/en-us/articles/115005532168) and within [Smarty](https://support.cordial.com/hc/en-us/articles/115005691407) for personalization, if searching of nested order properties is enabled in the account. | `"brands":["Cool Brand",<br>"Other Cool Brand"], "return_date": "2025-07-01<br> 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<br>If `discountApplication` is included, `type` and `amount` are required.
| Parameter | Type | Description | Example |
| --- | --- | --- | --- |
| `discountApplication` | object | Calculates a specified discount to arrive at a final sales price.<br>Calculate the final amount as: `totalAmount = totalAmount<br> - discountApplication.amount`<br>When `discountApplication.amount` is zero or not present: Calculate `totalAmount` without any changes. | For a $10 discount:<br>```json
"discountApplication": {<br>    "type": "fixed",<br>    "amount": 10.00<br>  }<br>``` |
| `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
}
```

## 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](https://support.cordial.com/hc/en-us/articles/115005532168).

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

| Method | URL Path |
| --- | --- |
| GET | /v2/orders |
| - Retrieves all orders from the Cordial database.<br>- 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.<br>- 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.

- [Parameters](https://support.cordial.com/hc/en-us/articles/204570677-Orders-API#zp-4-0)
- [Example GET/orders request URLs](https://support.cordial.com/hc/en-us/articles/204570677-Orders-API#zp-4-1)

| 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://support.cordial.com/hc/en-us/articles/360016355691).

```
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://support.cordial.com/hc/en-us/articles/360016355691).

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

## GET/v2/orders/{id}

| Method | URL Path |
| --- | --- |
| GET | v2/orders/{id} |
| - Retrieves a specific order from the Cordial database.<br>- The order is defined by the order's unique `orderID` value.<br>- For example, /orders/112233 would return the response data for the order with the `orderID` value of `112233`.<br>- Additionally, it's possible to filter the field set returned using a query string for the parameter fields. |

- [Parameters](https://support.cordial.com/hc/en-us/articles/204570677-Orders-API#zp-5-0)
- [Example GET/orders/{id} request URLs](https://support.cordial.com/hc/en-us/articles/204570677-Orders-API#zp-5-1)

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

| Method | URL path |
| --- | --- |
| PUT | /v2/orders |
| Updates an order in the Cordial database using the appropriate JSON body. |

- [Parameters](https://support.cordial.com/hc/en-us/articles/204570677-Orders-API#zp-6-0)
- [Example JSON request](https://support.cordial.com/hc/en-us/articles/204570677-Orders-API#zp-6-1)
- [Example PUT/orders request URL](https://support.cordial.com/hc/en-us/articles/204570677-Orders-API#zp-6-2)

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}

| Method | URL Path |
| --- | --- |
| DELETE | /v2/orders/{id} |
| Deletes an order from the Cordial database.<br>The order id defined by the order's unique `orderID` value.<br>For example, v2/orders/22345 would delete the attribute with the `orderID` value of **22345**. |

- [Example DELETE/orders/{id} request URL](https://support.cordial.com/hc/en-us/articles/204570677-Orders-API#zp-7-0)

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

```
https://<path>/v2/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](https://support.cordial.com/hc/en-us/articles/4402427843597-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 format, 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.