Migrate subscription preferences

You may have managed your audience’s subscription preferences manually—with your own attributes in a system outside of Customer.io. Before you use our subscription center feature, you probably want to migrate your audience’s preferences to the cio_subscription_preferences attribute, so that your audience’s preferences still apply when you enable the subscription center.

How it works

If you used to manage subscription preferences outside our subscription center feature, or you set up new “opt-in” topics, you’ll want to apply people’s current preferences to the cio_subscription_preferences attribute.

This ensures that you continue to observe your audience’s preferences when you enable the subscription center feature in Customer.io.

To migrate your audience’s preferences, we’ll:

  1. Create a segment of people who have subscription preference attributes
  2. Use this segment as a campaign trigger
  3. In the campaign, use a Create or Update Person action to set current preferences as topics in the cio_subscription_preferences object.

The subscription preferences attribute

You can set your audience’s subscription preferences using the reserved cio_subscription_preferences attributeA key-value pair that you associate with a person—like their name, the date they were created in your workspace, etc. Use attributes to target people and personalize messages.. Each topic in the attribute is numbered, based on the ID that you see in the UI—topic_1 corresponds to ID 1 in the left-column in your Subscription Center setup page. We set subscription preferences by topic ID rather than the topic Name, so that you can change the name of a topic without affecting your audience’s preferences. For each topic, true means that a person is subscribed to a topic; false means they’re unsubscribed.

You’ll set this attribute—either through the API, a CSV upload, a Create or Update Person action, or Database sync—to apply preferences to a person.

{
   "cio_subscription_preferences": {
      "topics": {
         "topic_1": true,
         "topic_2": false
      }
   }
}
Within Workspace Settings, this subscription center has a table wih 3 topics. Each topic has an ID followed by a name and the default status - not subscribed or subscribed.
Within Workspace Settings, this subscription center has a table wih 3 topics. Each topic has an ID followed by a name and the default status - not subscribed or subscribed.

 Check your payload

Applying subscription preferences incorrectly prevents us from observing your audience’s preferences, and can result in extra, misapplied attributes that clutter your workspace.

Migrate subscription preferences

There are plenty of ways to map subscription preferences. In this case, we’re using a campaign, but you could also use our API, upload a CSV, etc.

Before you start this process, we recommend that you:

  1. Create your topics
  2. Apply topics to your campaigns and broadcasts
  3. Figure out all the places where you’ll need to update subscription preferences. If you let your audience set their subscription preferences when they sign up, or inside your mobile apps, etc, you’ll want to make sure that you update those places to use Customer.io’s subscription center attributes as well.

Before you begin: relate preferences to topics

In Customer.io, we store subscription preferences by number (incremental, beginning at 1), so that changing the name of a preference doesn’t cause cascading changes to your audience. But that means that you’ll need to map your previous preference attributes to your new topic number.

So, if your attribute was previously called basketball and your first topic, that tells you that you’ll map your audience’s basketball preference to cio_subscription_preferences.topics.topic_1.

Create a segment

In this process, we assume that you previously stored your audience’s preferences as individual attributes, but the same basic process applies if you previously stored preferences as an object, array, etc.

  1. Go to Segments and click Create Segment.
  2. Set a Name and Description for your segment, and then click Create Data-driven Segment.
  3. Set up your campaign so At least one of the following conditions match. This ensures that people with any preference join your segment.
  4. Add conditions where each “preference” attribute exists.
  5. Click Save Changes.

Now your’e ready to set up a campaign to move your preference attributes to the new cio_subscription_preferences attribute.

set up a segment with your past subscription settings
set up a segment with your past subscription settings

Create your migration campaign

This is a very short campaign with one step that simply sets your audience’s preferences. We’ll use the segmentA group of people who match a series of conditions. People enter and exit the segment automatically when they match or stop matching conditions. that you created as the trigger. And then we’ll map your previous migration preferences to attributes.

  1. Go to Campaigns and click Create Campaign.

  2. Set a Name and Description for your campaign, and then click Create Campaign.

  3. Select When a person moves in or out of a segment—this lets us use the segment we created in previous steps as the trigger and audience for the campaign.

  4. Under Define the trigger condition, click Add segment condition and select the segment you created. Click Save and Next.

    set up your campaign trigger using the segment you created in previous steps
    set up your campaign trigger using the segment you created in previous steps

  5. In your workflow, add a Create or Update Person action, select it, and click Add Details.

    this is what your workflow will look like
    this is what your workflow will look like

  6. Add a line for preferences, where

    • The Attribute is your cio_subscription_preferences.
    • The Value is JavaScript. Don’t worry if you don’t know JavaScript; we’ve provided an example below!
    • In the final box, set up the logic that maps your data to the subscription preference attributes. In our example, we check if the baseball and basketball attributes exist. These attributes are boolean, so we can map the value directly to the new subscription preference—if they exist; otherwise, we assume that a person isn’t subscribed to the corresponding topic (false). Use the “return partial” JavaScript to set updates to specific topic preferences and preserve existing preferences for other topics.
        return {
           topics: {
             topic_1: customer.baseball ? customer.baseball : false,
             topic_2: customer.basketball ? customer.basketball : false
           }
         }
      
        return {
           topics: {
             ...customer.cio_subscription_preferences?.topics,
             topic_1: customer.baseball ? customer.baseball : false // this sets the topic_<x>, while preserving other topic preferences that the user already set.
           }
         }
      
      set your audience's subscription attributes
      set your audience's subscription attributes You also have the option to set cio_subscription_preferences as a static value with the following JSON: {"topics":{"topic_1": true, "topic_2": false, ... "topic_<x>": false}}. To use this, you’ll have to set up additional logic in your campaign for the attribute to update appropriately. Setting a static value replaces all existing preferences, so you’d need to set all preferences to avoid overwriting a person’s existing preferences with defaults. This is more error prone, so we recommend utilizing JavaScript instead.
  7. (Optional) Delete the attribute that you’re migrating from. After we apply the baseball attribute to topic_<x>, we probably don’t need to keep it around!

  8. When you’ve added all of your attributes click Save and start your campaign.

Update subscription preferences via the API

For each person in your workspace, you can set subscription attributes using the identify action in our API. Your payload changes based on whether you use our v1 or v2 APIs, but we’ve posted examples of both below.

 Use the v2 API to batch changes

The v2 API supports a /batch endpoint that lets you send changes for multiple people in a single request.

https://track.customer.io/api/v2/batch

{
  "batch": [
    {
      "type": "person",
      "identifiers": {
        "email": "cool.person@example.com"
      },
      "action": "identify",
      "attributes": {
        "cio_subscription_preferences": {
          "topics": {
            "topic_1": true
          }
        }
      }
    }
  ]
}
https://track.customer.io/api/v1/customers/cool.person@example.com

{
  "cio_subscription_preferences": {
    "topics": {
      "topic_1": true
    }
  }
}

Set subscription preferences using the web SDK

If you use the JavaScript snippet on your website, you can set subscription preferences with the identify function. You might want to do this if you let people set their subscription preferences as a part of your signup flow.

_cio.identify({
  email: "cool.person@example.com",
  first_name: 'cool',
  last_name: 'person',
  cio_subscription_preferences: {
    "topics": {
      "topic_1": true,
      "topic_2": false
    }
  }
})

Upload subscription preferences via CSV

When you set cio_subscription_preferences in a CSV, you’ll use the same JSON structure that that our API expects. See our example spreadsheet for an example.

You’ll add a column to your CSV called cio_subscription_preferences. The contents of this column are topics objects, as follows:

email,first_name,cio_subscription_preferences
person@example.com,person,{"topics":{"topic_1":true,"topic_2":false}}
another.person@example.com,another,{"topics":{"topic_1":true,"topic_2":true}}
Copied to clipboard!
  Contents
Is this page helpful?