# How can we help?

## Search

## Overview

Order data is stored in the orders collection. This collection contains all data associated with a purchase event. Order data can be used to [personalize message content](https://support.cordial.com/hc/en-us/articles/115005528568-Orders#ordersMessage), [trigger messages](https://support.cordial.com/hc/en-us/articles/115005528568-Orders#h_01H7G5J292AA62ZMY4XCB2DBFD), and [build audiences](https://support.cordial.com/hc/en-us/articles/115005528568-Orders#audiences).

- For more information on order attributes and requirements for interacting with this collection, you can [read about order data and the API](https://support.cordial.com/hc/en-us/articles/204570677-Orders).

## How Cordial stores orders

Below is a simple example of an order stored in the orders collection as a JSON object. The example includes the reserved fields `productID`, `sku`, and `category`, as well as an object of customized attributes: `color` and `size`.

```
[
  {
    "orderID": 1,
    "cID": "55d7294629aa544d75c6b810",
    "purchaseDate": "2015-10-29T15:05:00+0000",
    "properties": {
      "custom_order_key": "custom_order_value"
    },
    "items": [
      {
        "productID": "1",
        "sku": "sku",
        "model": "mymodel",
        "category": "garment",
        "name": "dress",
        "qty": 1,
        "amount": 2.5,
        "attr": {
          "color": "blue",
          "size": "xs"
        },
        "properties": {
          "custom_order_item_key": "custom_order_item_value"
        }
      }
    ]
  }
]
```

The most common order-related attributes are required by default. These required fields include `email`, `order ID`, and `purchaseDate`. The items object is optional. If the items object is included, the `productID`, `sku`, `category`, and `name` item fields are required. Some attributes are set as arrays and can include customizable name/value pairs such as `color:blue`, `size:large`, and much more.

## Import orders

Order data is imported into Cordial via the API, or with JavaScript Listeners embedded on your site.

- [Learn more about the order collection and Cordial's API](https://support.cordial.com/hc/en-us/articles/204570677-Orders).
- [Learn about importing order data via JavaScript Listener](https://support.cordial.com/hc/en-us/articles/360016285852#order).

## View orders

You can [view your order collection with GET API calls](https://support.cordial.com/hc/en-us/articles/204570677-Orders-API#getOrders).

### View orders via message preview

You can also view orders specific to a contact using a Smarty utility. Paste the following code into an HTML message and click the **Preview** button to see all the orders for the previewed contact.

```
{$orders=$utils->getOrders()}
{$utils->jsonPrettyPrint($orders)}
```

## Use orders in a message

Message content can be personalized with order data using the [Smarty getOrders method](https://support.cordial.com/hc/en-us/articles/115005693207-Get-Order-Data-getOrders-method-).

> **Use case**  
> You could send contacts a message with items on sale that are relevant to their past orders.

When displaying product meta data related to an order (images, descriptions, etc.), we recommend that you pull that data from the product catalog because it might be more up to date.

## Trigger messages when an order is created or updated

You can trigger messages when orders are created or updated. For example, you could trigger a message when an order's delivery status changes.

1. When creating a message, open the **Trigger Events** pane and select **When an order is created or updated** for the **Trigger event**.
2. Select the **Trigger strategy** you want to use:
   - Trigger when an order is created or updated.
   - Trigger only when an order is updated (ignore new orders).
   - Trigger only when an order is created (ignore existing orders).

3. Under **Changed field**, select the event change that will trigger the message, such as when an order's status changes from shipped to delivered.
4. Add a **Conditional filter** as needed.
5. Set the **Delay,** select whether to **Enable quiet hours**, and choose **How often can this message be sent to an individual**.

The `$triggerData` utility contains both old and new order data, which you can differentiate in Smarty to display additional changes.

## Build audiences with orders

Using the Audience Builder, you can create audiences of contacts who purchased specific products and segment your audiences in powerful ways.

1. Navigate to **Contacts > Audience** and edit or create a new audience.
2. Select **Orders** from the **Rules** dropdown in the Audience Builder and drag the rule into your audience.
3. Click **Select Products** to configure your audience by specific purchases.
4. Configure **Order Property**, **Item Property**, **Recency**, and **Frequency** to add further segmentation.

> **Use case**  
> You could create an audience of all contacts that have purchased the Emi Jumpsuit within the past 30 days and send them a personalized message with recommended product accessories or related products from your catalog.

## Build analytics reports using orders

Audiences based on orders can be saved as [audience rules](https://support.cordial.com/hc/en-us/articles/115005532168) and visualized over time with [Audience Trend reports](https://support.cordial.com/hc/en-us/articles/115005364907) or used as filters for [event data dashboards](https://support.cordial.com/hc/en-us/articles/115005533188) and [event data reports](https://support.cordial.com/hc/en-us/articles/115005533268).

### Audience Trends reports

To access Audience Trends reports, log in to Cordial and navigate to **Analytics > Audience Trends**. From here, select the audience from the **Select audience(s)** dropdown to view the population of an audience over time based on order history.

> **Use case**  
> You could create an audience of contacts who've made a purchase in the last 30 days. To do so, [enable Audience Trends analytics](https://support.cordial.com/hc/en-us/articles/115005364907) on the audience rule, and then view the population over time on an Audience Trends chart by selecting the audience from the dropdown or manually entering it.

### Filter event dashboards

[Event dashboards](https://support.cordial.com/hc/en-us/articles/115005533188) provide a way to visualize event activity over time by creating customizable charts. You can take advantage of orders in event dashboard charts using audience filters.

1. To create an event chart, navigate to **Analytics > Event Dashboards** and select **Add Chart**.
2. To edit an event chart (also called a time series chart), navigate to **Analytics > Event Dashboards** and select **Chart Settings** in the upper right corner of the chart.

> **Use case**  
> You could create a chart that plots message activity over time and is filtered by a saved audience rule of people who've placed an order in the past 30 days.

### Filter event data reports

[Event data reports](https://support.cordial.com/hc/en-us/articles/115005533268-Event-Data-Reports) allow you to view reports of event activity. You can filter reports using audience rules similar to event dashboard charts.

> **Use case**  
> You could filter by a saved audience rule of contacts who've placed an order in the past 30 days.

## Export orders

You can export orders by creating a data job in the UI.

1. Log in to Cordial and navigate to **Data Jobs > Create New Data Job**.
2. Under **Export**, select **Orders**.
3. Fill in the **Name** and **Tags** fields. For **Type**, choose either **One-time** or **Recurring**. Assign a **Priority** for the job and click **Continue**.
4. On the Data Job creation page, click **Edit** in the **Data Source** pane to specify the orders you want to export.
5. In the Orders pane, configure the orders you'd like to export: specify the actual **Orders**, **Order properties**, **Item properties** (if applicable), **Contacts**, and the **Date Range** for when the orders occurred.

> **Use case**  
> You could export order data for anyone in San Diego (Order properties) who's ordered a Sweater (Orders) from Cordial Threads (Item properties) within the past 15 days.

6. Select **Edit** under **Data Mapping** and enter the required fields: **Export name** and **Export file name**.
7. Select **Edit** under **Data Destination** and choose the destination for your exported orders file. You can select Local, FTP, SFTP, AWS S3 bucket, Google Cloud, or Azure Blob.

8. In the **On Completion** pane, enter an email address where you'd like to receive a notification once the job is complete. This step is optional.
9. If your data job is recurring, **Publish** the data job then select **Recurring** under **Settings** on the left. From here, set the **Schedule** for your data job and then **Enable** it.
10. Run the export events data job. Once completed, you can find the job under the **Jobs** widget.

In the next article, you can [learn about supplements](https://support.cordial.com/hc/en-us/articles/115005528468-Supplements).