45

Collections

Collections provide a way to store data in your workspace that you can use in campaigns with Liquid.

What’s a Collection?

A collection is a new type of data in Customer.io that’s separate from people or events in your account. They represent any set of “things” that exist in your business. For instance, a Collection could be a list of upcoming events, promotions/coupons, or available classes.

You should store this data in Customer.io when it’s helpful to be able to sort through the Collection to identify a specific set of data that you want to include in a message, tailored to the data you know about each person. Let’s take the example of an online learning service. By storing all the courses offered in a Collection, you could retrieve the specific set of classes that are relevant for each individual person and list them in a campaign email.

Collections are flexible. They’re simply lists of JSON objects that do not require specific schemas or indexes. However, your collection cannot be larger than 10 MB, and rows in your collection are limited to 10 KB.

Creating a Collection

You can upload your collection as JSON, a CSV file, or by sharing a Google Sheet with us. If you upload a CSV file or share a Google Sheet, we expect your file to be a simple table with headers, as in this example.

If you want to share a Google Sheet with us, you must grant Customer.io access to specific files in your Google Drive.

To upload your collection:

1. Select Content > Collections in the navigation menu.
2. Click Add Collection.
3. Select your collection file.
4. Click Add Collection.

Alternatively, you can can add a Collection using the API.

Adding Collection Data to your Messages

Now that you’ve added a Collection, the next step is to use them in your campaigns. The power of Collections is that you can query the Collection as part of a campaign workflow, meaning that you can retrieve only the Collection items relevant to that particular person and campaign.

First, add a “Query Collection” action to your campaign

When one of your customers reaches this part of the workflow, we’ll retrieve the data you want to use in subsequent messages.

Build a query to retrieve the rows relevant to the person

Select your new collection in the workflow, give it a name, and click “Add Query” to get started. You’ll arrive at our new query builder:

To show how this works, lets take the example of a service that delivers online courses. Let’s say you want to query for a list of courses that are appropriate for the skill level of the person who triggered the campaign.

First, select the Profile Attribute you want to store the results of the query in, something like next_courses. Then, select the Collection you want to query. Next is the exciting part: click Add query condition and use it to filter for the courses you want to send an email about. For example, all courses where the Collection attribute level is equal to the profile attribute skill_level.

After you add this condition, select the preview tab to see what Collection rows would be returned for the person you have selected in the Sample Data panel on the left side.

When this query is run as part of a campaign, the rows from this Collection that match your query will be stored in the profile attribute you selected formatted as JSON. If you choose to return only one result, the result will be a JSON object, or an array if you choose to return multiple.

Use Liquid to add Collection data to your message

Now that you’ve set up your query, it’s time to use the Collection data in a message! As the results of Collections queries are stored as JSON arrays in customer attributes, you work with the results in Liquid in all the familiar ways.

For example, you can use a for loop to show the names of each of the courses returned by the query in the previous section:

{% for item in customer.next_courses %}
  {{ item.name }}
{% endfor %}

Also helpful are Liquid’s array filters, such as first, last, and map which allow you to select specific items or attributes. For example:

{% assign first_course = customer.next_courses | first %}

If you limited your query to a single result, then the attribute will be an object rather than an array. You can instead directly access the name and course description:

{{ promo_course.name }}
{{ promo_course.description }}

Collections API

The endpoints for Collections are available via our App API:

• US region: https://api.customer.io/v1/
• EU region: https://api-eu.customer.io/v1/

Creating a new Collection:

POST:/v1/api/collections

Create a new collection by providing both a name and either an array of JSON objects as data, or a url to download CSV or JSON data from.

{
  "name": "collection name",
  "data": [ { row }, { row } ],
}

If you provide a URL, the data can either be JSON (array or newline delimited) or a CSV file. Ensure that you provide a Content-Type definition so that we know how to parse the data. If you don’t provide a Content-Type, we use the file extension. If you don’t include a content type or file extension, we assume the URL contains JSON.

You cannot share a Google Sheet with us using this API.

Once created, a Collection has the following JSON definition:

"bytes": bytes_of_data_in_collection,
"created_at": 1589471110,
"updated_at": 1589471132
"id": 1,
"name": collection_name
"rows": number_of_rows_in_collection,
"schema": ["name1", "name2", "name3" ],

The schema will have a list of all attributes used by any items in the Collection, but remember that we don’t enforce that all items have this set of attributes.

Retrieve info about a Collection you’ve already created

GET:/v1/api/collections/:id

Get the details of a collection with the given id. This does not include the content.

Retrieve the content of a Collection you’ve already created

GET:/v1/api/collections/:id/content

Returns the entire content of the collection with the given id.

Retrieve a list of all your Collections

GET:/v1/api/collections

Returns the details (but not content) for all of your Collections:

{"collections": ["collection1", "collection2"]}

Update the content of a Collection

PUT:/v1/api/collections/:id/content

Provide the content of a Collection as JSON-encoded text or CSV-encoded data. This will replace all the content for the Collection. For example:

[
  {
    "name":"Steak",
    "price":20,
    "quantity":10,
    "can_deliver":false
  }
]

Update the name and content of a Collection

PUT:/v1/api/collections/:id

Update an existing collection. If name or data or url aren’t provided, the associated data is not updated. This will replace all content for the Collection.

{
"name": "collection name",
"data": [
  {"name":"Hot Dog","price":2,"quantity":1,"can_deliver":true},
  {"name":"Pizza","price":10,"quantity":2,"can_deliver":true},
  {"name":"Steak","price":20,"quantity":10,"can_deliver":false} ]
}
OR
{
  "name": "collection name",
  "url": "https://example.com/sheet.csv"
}

Delete a Collection

DELETE:/v1/api/collections/:id

Deletes the collection with the given id.