Overview

The data stored within the orders collection can be referenced and used within any message body.

Our example

For our example we'll be using hypothetical order data. In order to test in your system you will need to add your own order data via the API.

• Learn more about order data.

Using the tabs below, you can view the HTML and Smarty used in the message, the order data being referenced (in JSON format), and the rendered output that will display when a message is sent or previewed.

• {$orders=$utils->getOrders()} 
  {foreach $orders as $order}
  <b>OrderID {$order.orderID}</b><br>
  Purchase Date - {$order.purchaseDate|date_format}<br><br>
      {foreach $order.items as $orderitem}
          Product {$orderitem.productID}<br>
          {$orderitem.description|capitalize} - ${$orderitem.amount|string_format:"%.2f"}<br>
          Size - {$orderitem.attr.size}<br>
          Color - {$orderitem.attr.color}<br><br>
      {/foreach}
  Total Amount - ${$order.totalAmount}<br><br>
  Shipping Address:<br>
  {$order.shippingAddress.name|capitalize}<br>
  {$order.shippingAddress.address|capitalize}<br>
  {$order.shippingAddress.city|capitalize} {$order.shippingAddress.state|capitalize} {$order.shippingAddress.postalCode}<br><br>
  {/foreach}

• [
     {
        "cID": "58d2fc99ac0c8117814d4e78"
        "orderID": "001",
        "purchaseDate": "2015-01-10T01:47:43+0000",
        "shippingAddress": {
          "name": "fred garvin",
          "address": "555 truss St",
          "city": "san diego",
          "state": "ca",
          "postalCode": "92108",
          "country": "usa"
        },
        "billingAddress": {
          "name": "fred garvin",
          "address": "555 truss st",
          "city": "san diego",
          "state": "ca",
          "postalCode": "92108",
          "country": "usa"
        },
        "items": [
          {
            "productID": "111",
            "description": "khaki shorts",
            "sku": "1212",
            "category": "shorts",
            "name": "khaki shorts",
            "qty": 1,
            "itemPrice": 19.99,
            "amount": 19.99,
            "attr": {
              "color": "tan",
              "size": "large"
            }
          },
          {
            "productID": "222",
            "description": "khaki pants",
            "sku": "1213",
            "category": "pants",
            "name": "khaki pants",
            "qty": 1,
            "itemPrice": 29.99,
            "amount": 29.99,
            "attr": {
              "color": "tan",
              "size": "large"
            }
          }
        ],
        "tax": 0,
        "totalAmount": 49.98
      }
    ]

• OrderID 001
  Purchase Date - Jan 10, 2015
  
  Product 111
  Khaki Shorts - $19.99
  Size - large
  Color - tan
  
  Product 222
  Khaki Pants - $29.99
  Size - large
  Color - tan
  
  Total Amount - $49.98
  
  Shipping Address:
  Fred Garvin
  555 Truss St
  San Diego CA 92108

When creating a message, it's useful to use the following Smarty utility to view the contact's order records in JSON format:

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

getOrder method

In order to access order data for a specific order within a message, use the getOrder method, which is a custom extension of Smarty provided by Cordial.

The contact primary identifier key is implied when rendering order data in a message. Only order data associated with the contact will be available for rendering in a message.

The getOrder method takes 1 parameter: orderID.

getOrder($orderID)

Write the getOrder method

{$orders=$utils->getOrder($orderID)}

You can optionally set the $orderID in a variable prior to making the call:

  {$orderID="12345}
  {$orders=$utils->getOrder($orderID)}

Or you can pass the orderID directly to method call:

  {$orders=$utils->getOrder("12345")}

getOrders method

In order to access data for multiple orders within a message, use the getOrders method, which is a custom extension of Smarty provided by Cordial.

The contact primary identifier key is implied when rendering order data in a message. Only order data associated with the contact will be available for rendering in a message.

The getOrders method has three parameters: query, limit, and sort. They must be written in this order and separated by commas. All are optional.

getOrders($query, $limit, $sort)

Write the getOrders method

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

In the example above, a variable "orders" is assigned to the resulting data set returned from the orders collection. The getOrders method will get the data from the orders collection for each message that is rendered per contact.

Set the query

In some cases, you may want to get specific records from the order collection. You can achieve this by adding query filters.

Return records filtered by a specified value

["key"=>"value"]

Example:

{$orders=$utils->getOrders(["orderID"=>"002"])}

Return records filtered by multiple specified values

["key"=>"value", "key2"=>"value2"]

Example:

{$orders=$utils->getOrders(["purchaseDate"=>["gt"=>"2016-01-09"],"shippingAddress.city"=>"san diego"])} 

Return records filtered by a value within an order item

["items"=>["key"=>"value"]]

Example:

{$orders=$utils->getOrders(["items"=>["productID"=>"111"]])}

Set the limit

Use the limit filter to limit the amount of records returned.

Example with no query filter and a limit of 5 records:

{$orders=$utils->getOrders([],5)}

If an array parameter is left empty (query in this example) you must leave a placeholder of empty brackets "[]".

Example with a query filter and a limit of 5 records:

{$orders=$utils->getOrders(["purchaseDate"=>["gt"=>"2016-01-09"]],5)}

Sort the data

Sort results by purchase date in an ascending order

{$orders=$utils->getOrders([],null,['column'=>'purchaseDate','direction'=>'ASC'])}

Sort results by purchase date in an descending order

{$orders=$utils->getOrders([],null,['column'=>'purchaseDate','direction'=>'DESC'])}

Sort results by order ID in an descending order

{$orders=$utils->getOrders([],null,['column'=>orderID,'direction'=>'DESC'])}

Empty array parameters must use a placeholder of square brackets "[]". Empty limit parameter must use either "null" or "false".

Render the data in a message

After the data is available with the getRecords method, you can render the data in the message.

Loop through data with {foreach}

A {foreach} statement is the most common way to loop through the data array and render the results in a message.

Example:

{$orders=$utils->getOrders()} 
{foreach $orders as $order}
<b>OrderID {$order.orderID}</b><br>
Purchase Date - {$order.purchaseDate|date_format}<br><br>
    {foreach $order.items as $orderitem}
        Product {$orderitem.productID}<br>
        {$orderitem.description|capitalize} - ${$orderitem.amount|string_format:"%.2f"}<br>
        Size - {$orderitem.attr.size}<br>
        Color - {$orderitem.attr.color}<br><br>
    {/foreach}
Total Amount - ${$order.totalAmount|string_format:"%.2f"}<br><br>
Shipping Address:<br>
{$order.shippingAddress.name|capitalize}<br>
{$order.shippingAddress.address|capitalize}<br>
{$order.shippingAddress.city|capitalize} {$order.shippingAddress.state|capitalize} {$order.shippingAddress.postalCode}<br><br>
{/foreach}

Order items are stored as an array. You can use a nested {foreach} in order to loop through each of the items per order.

• Learn more about using the {foreach} statement.

Render orders between two purchase dates

You can render orders placed between two specified dates. This method requires the use of getConvertedDate Smarty utility.

{$orders.startDate = '2018-01-22'}
{$orders.endDate = '2018-01-22'}
{$orders.query.purchaseDate.between.start = $utils->getConvertedDate($orders.startDate|cat:' 00:00:00', 'UTC', $account.timezone, 'Y-m-d\TH:i:sO')}
{$orders.query.purchaseDate.between.end = $utils->getConvertedDate($orders.startDate|cat:' 23:59:59', 'UTC', $account.timezone, 'Y-m-d\TH:i:sO')}
{$orders.limit = 50}
{$orders.sort = ['column'=>'purchaseDate','direction'=>'DESC']}
{$orders.data = $supplements->getOrders($orders.query, $orders.limit, $orders.sort)}
<h2>Debug $orders</h2>
{$utils->jsonPrettyPrint($orders)}
<h2>Debug $contact</h2>
{$utils->jsonPrettyPrint($contact)}

Reference an index of the array

You also have to option to target the "nth" item within an array using it's index. For example, if you only wanted to render the first item of each item array you would write:

{$orders=$utils->getOrders()} 
{foreach $orders as $order}
<b>OrderID {$order.orderID}</b><br>
Purchase Date - {$order.purchaseDate|date_format}<br><br>
        Product {$order.items[0].productID}<br>
        {$order.items[0].description|capitalize} - ${$order.items[0].amount|string_format:"%.2f"}<br>
        Size - {$order.items[0].attr.size}<br>
        Color - {$order.items[0].attr.color}<br><br>
Total Amount - ${$order.totalAmount|string_format:"%.2f"}<br><br>
Shipping Address:<br>
{$order.shippingAddress.name|capitalize}<br>
{$order.shippingAddress.address|capitalize}<br>
{$order.shippingAddress.city|capitalize} {$order.shippingAddress.state|capitalize} {$order.shippingAddress.postalCode}<br><br>
{/foreach}

This example will look in the first item of the items array and render the values for "productID", "description", "amount", "size" and "color".

The first item of an array is referenced by "0", the second is "1", the third is a "2", and so on.

In the next article, you can learn about getting event data.