Set preferences outside of the subscription center
A subscription center helps you differentiate between the types of messages you send and lets your audience decide what kinds of campaigns and messages they want to receive. Your customers can update their preferences from within your Customer.io messages or other locations including, but not limited to, account creation.
How it works
Customer.io’s Subscription Center feature lets your audience set their subscription preferences when they click Unsubscribe or Manage your preferences in your messages. But you might want to let your audience proactively manage their preferences as a part of your sign-up flow or elsewhere.
You can set your audience’s subscription preferences using the reserved cio_subscription_preferences
attributeA key-value pair that you associate with a person or an object—like a person’s name, the date they were created in your workspace, or a company’s billing date 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
}
}
}


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.
Your subscription center starts your relationship with your audience on the right foot by letting them tell you which types of messages they’re interested in.
Create a custom subscription preferences page
If you need more flexibility over the branding and location of your subscription preferences page, you can use our App and Track APIs to fetch and update preferences within a page that you host. Use our App API to fetch susbcription preferences for your customers and our Track API to update subscription preferences. You can also set preferences using our Web SDK.
outside Customer.io]-->b subgraph App API direction LR b[fetch preferences
on page load] end b-->c subgraph Track API or Web SDK direction LR c[set preferences when
form is submitted] end
App API: Fetch preferences
You can fetch subscription preferences from your workspace using our App API endpoint: /v1/customers/{customer_id}/subscription_preferences
.
const axios = require('axios');
let config = {
method: 'get',
maxBodyLength: Infinity,
url: 'api.customer.io/v1/customers/sdade8@example.com/subscription_preferences?id_type=email',
headers: {
'Accept': 'application/json',
'Authorization': 'Bearer'
}
};
axios.request(config)
.then((response) => {
console.log(JSON.stringify(response.data));
})
.catch((error) => {
console.log(error);
});
Track API: Set preferences
If you have your own backend integration, you can send subscription preferences to your workspace from the /v1/customers
endpoint or by using the identify action in the /api/v2/entity
endpoint or /api/v2/batch
endpoint.
In order to update some preferences, while preserving those set for other topics, use JSON dot notation "cio_subscription_preferences.topics.topic_<topic ID>":<boolean>
.
const axios = require('axios');
let data = JSON.stringify({
"cio_subscription_preferences": {
"topics": {
"topic_1": true,
"topic_2": true,
"topic_3": false
}
}
});
let config = {
method: 'put',
maxBodyLength: Infinity,
url: 'https://track.customer.io/api/v1/customers/sdade8@example.com',
headers: {
'Content-Type': 'application/json',
'Authorization': 'Basic'
},
data : data
};
axios.request(config)
.then((response) => {
console.log(JSON.stringify(response.data));
})
.catch((error) => {
console.log(error);
});
const axios = require('axios');
let data = JSON.stringify({
"cio_subscription_preferences.topics.topic_2": false
});
let config = {
method: 'put',
maxBodyLength: Infinity,
url: 'https://track.customer.io/api/v1/customers/sdade8@example.com',
headers: {
'Content-Type': 'application/json',
'Authorization': 'Basic'
},
data : data
};
axios.request(config)
.then((response) => {
console.log(JSON.stringify(response.data));
})
.catch((error) => {
console.log(error);
});
const axios = require('axios');
let data = JSON.stringify({
"type": "person",
"identifiers": {
"email": "sdade8@example.com"
},
"action": "identify",
"attributes": {
"cio_subscription_preferences": {
"topics": {
"topic_1": true,
"topic_2": true,
"topic_3": true
}
}
}
});
let config = {
method: 'post',
maxBodyLength: Infinity,
url: 'https://track.customer.io/api/v2/entity',
headers: {
'Content-Type': 'application/json',
'Accept': 'application/json',
'Authorization': 'Basic'
},
data : data
};
axios.request(config)
.then((response) => {
console.log(JSON.stringify(response.data));
})
.catch((error) => {
console.log(error);
});
const axios = require('axios');
let data = JSON.stringify({
"type": "person",
"identifiers": {
"email": "sdade8@example.com"
},
"action": "identify",
"attributes": {
"cio_subscription_preferences.topics.topic_1": false
}
});
let config = {
method: 'post',
maxBodyLength: Infinity,
url: 'https://track.customer.io/api/v2/entity',
headers: {
'Content-Type': 'application/json',
'Accept': 'application/json',
'Authorization': 'Basic'
},
data : data
};
axios.request(config)
.then((response) => {
console.log(JSON.stringify(response.data));
})
.catch((error) => {
console.log(error);
});
Javascript/Web SDK: Set preferences
If you use our JavaScript snippet, you can set preferences with the identify
function. You can identify a person when they first sign up for your service and set their preferences or when they update their preferences in a settings page that you make available to them.
To set preferences for all topics, use the cio_subscription_preferences
key. To set some preferences, while preserving those set for other topics, use JSON dot notation "cio_subscription_preferences.topics.topic_<topic ID>":<boolean>
.
_cio.identify({
// request must contain an identifier like `id` or `email`, depending on the settings in your workspace
email: 'cool.person@example.com',
cio_subscription_preferences: JSON.stringify({ topics: { topic_1: true, topic_2: false, topic_3: false} })
});
You must stringify the values in order for the attribute to successfully update on the person’s profile.
_cio.identify({
// request must contain an identifier like `id` or `email`, depending on the settings in your workspace
email: 'cool.person@example.com',
"cio_subscription_preferences.topics.topic_<topic ID>":<boolean>
});