Customer.io events

Customer.io events are events that perform specific actions in Customer.io. These events can remove profiles from your environment, delete relationships, suppress users, and so on.

How it works

Your workspace supports a number of actions that aren’t immediately apparent from the API. For example, I can add a profile using the identify function, but what if I want to remove a profile?

That’s what semantic events are for: they let you send track calls with a specific event name to perform actions in Customer.io. In general, the event names map directly to the thing you want to do: like Create Device or Delete Person.

Create or Update Device

The Device Created or Updated event creates a new device if device.token doesn’t exist and updates the device if it does.

A “device” is a mobile device or browser that a person uses to interact with your app or website. You might send this event when someone logs into your app or website. These events require a device object. The device object must contain a token.

cioanalytics.track("Device Created or Updated", {
  device: {
    token: "string",
    type: "ios"
  }
});

eventstringrequired
The event name.
Accepted values: Device Created or Updated, Device Created or Updated
userIdstringrequired
The user's unique identifier.
contextobjectrequired
Information about the device performing the event.
- deviceobjectrequired
  Device information.
  - tokenstringrequired
    The device token.
  - typestring
    The device type.
    Accepted values: ios, android, ios, android
- appobject
  Information about your app.
  - namespacestring
    The bundle ID (iOS) or package name (Android) of your app. We map it to the device's app_identifier attribute, so that we know which of your apps the device belongs to. If you have a single app, you don't need to send it.
- additional properties *any type

Delete Device

This event removes a device. You might send this event when someone logs out of your app.

As with the Create Device and Update Device events, this event requires a device object. The device object must contain a token.

cioanalytics.track("Device Deleted", {
  device: {
    token: "string",
    type: "ios"
  }
});

eventstringrequired
The event name.
Accepted values: Device Deleted, Device Deleted
userIdstringrequired
The user's unique identifier.
contextobjectrequired
Information about the device performing the event. Our SDKs typically collect these properties automatically.
- deviceobjectrequired
  Device information.
  - tokenstringrequired
    The device token.
  - typestring
    The device type.
    Accepted values: ios, android, ios, android
- additional properties *any type

Delete Person

This event removes a profile from your Customer.io workspace. You might do this when someone cancels their subscription with you or otherwise leaves your service.

cioanalytics.track("User Deleted);

eventstringrequired
The event name.
Accepted values: User Deleted, User Deleted
userIdstringrequired
The user's unique identifier or their email address. If you provide an email address, we'll look up the person by their email address and delete them.
propertiesobject
Properties for the event. These aren't typically useful in Customer.io when deleting people, but you might use them in other places—like an analytics tool (e.g. Mixpanel).

Delete Object

This event removes a group (also called an object) from Customer.io. Groups/objects represent things like accounts, companies, and online classes. You might delete a group when an account is closed, a company is acquired, or you stop offering a class.

This event requires an objectId and an objectTypeId. If you don’t provide an objectTypeId, we’ll assume it’s 1, but if the objectId with the associated objectTypeId (defaulting to 1) does not exist, the event will not find and delete the objectId.

cioanalytics.track("Object Deleted", {
  objectId: "Acme",
  objectTypeId: 1
})

eventstringrequired
The event name.
Accepted values: Object Deleted, Object Deleted
anonymousIdstringrequired
While you must set a value, it can be anything; we don't use it. Customer.io requires events to be performed by people, but the "performer" is irrelevant to this event.
propertiesobjectrequired
Properties for the event. In this case, you'll need to provide the objectId. You should also provide the objectTypeId if you have more than 1 object type; if you don't include it, we'll assume it's 1.
- objectIdstring
  This is the group/object you want to remove.
- objectTypeIdinteger
  Default: 1
  The type of group/object the objectId represents. In Customer.io, each type of group/object has a an integer value, starting at 1 and incrementing. For example, if you have two types of groups/objects, you might have 1 represent accounts and 2 might represent companies.
  If you leave this value blank, we'll assume it's 1.

Delete Relationship

This event removes a relationship between a profile and an object in Customer.io. This is basically the opposite of the group function in Customer.io. Groups (or objects) represent things like accounts, companies, or online classes, you might delete a relationship when a profile is no longer on an account, leaves a company, or drops a class.

cioanalytics.track("Relationship Deleted", {
  objectId: "Acme",
  objectTypeId: 1
})

eventstringrequired
The event name.
Accepted values: Relationship Deleted, Relationship Deleted
userIdstringrequired
The user's unique identifier or their email address. If you provide an email address, we'll look up the person by their email address.
propertiesobjectrequired
Properties for the event. In this case, you'll need to provide the objectId. You should also provide the objectTypeId if you have more than 1 object type; if you don't include it, we'll assume it's 1.
- objectIdstringrequired
  A person is related to a group/object. This is the group/object you want to remove the person from.
- objectTypeIdinteger
  Default: 1
  The type of group/object the objectId represents. In Customer.io, each type of group/object has a an integer value, starting at 1 and incrementing. For example, if you have two types of groups/objects, you might have 1 represent accounts and 2 might represent companies.
  If you leave this value blank, we'll assume it's 1.

Suppress Person

Remove a profile from your Customer.io workspace and prevent them from being added back to your workspace using the same identifier. In general you should only send this event for compliance reasons, like when someone invokes their right to be forgotten in accordance with GDPR or CAN-SPAM regulations.

cioanalytics.track("Suppress Person");

eventstringrequired
The event name.
Accepted values: User Suppressed, User Suppressed
timestampstring(date-time)
The ISO-8601 timestamp when the event occurred.
userIdstringrequired
The user's unique identifier.
propertiesobject
Properties for the event. These aren't typically useful in Customer.io when suppressing people, but you might use them in other places—like an analytics tool (e.g. Mixpanel).
- additional properties *any type

Unsuppress Person

Allow a userId to be added back to your Customer.io workspace. This does not restore information from a profile you previously suppressed. It only allows you to add a profile back to your workspace using the same identifier.

You might do this if a profile explicitly asks to be resubscribed to your messages after having been suppressed.

cioanalytics.track("Unsuppress Person", {
  userId: "person-i-want-to-unsuppress"
});

eventstringrequired
The event name.
Accepted values: User Unsuppressed, User Unsuppressed
timestampstring(date-time)
The ISO-8601 timestamp when the event occurred.
userIdstringrequired
The user's unique identifier.
propertiesobject
Properties for the event. These aren't typically useful in Customer.io when unsuppressing people, but you might use them in other places—like an analytics tool (e.g. Mixpanel).
- additional properties *any type

Report Delivery Event

In general, we use this event with our JavaScript snippet to report delivery events for in-app messages back to your Customer.io workspace.

While Customer.io knows about messages that are sent, this event reports back to Customer.io when an in-app message is delivered, clicked, and so on. Each message contains a unique deliveryId that we trace back to the profile, automation/broadcast, and other items in your Customer.io workspace.

You can use this event to report delivery events for other message types, like push notifications. You might do this if you’re using a third-party push notification service and want to report delivery events back to Customer.io.

cioanalytics.track("Report Delivery Event", {
  deliveryId: "delivery-id",
  metric: "clicked",
  recipient: "device-token",
  actionValue: "enable push",
  href: "myApp://settings/push"
});

eventstringrequired
The event name.
Accepted values: Report Delivery Event, Report Delivery Event
timestampstring(date-time)
The ISO-8601 timestamp when the event occurred.
propertiesobjectrequired
Properties for the event. These aren't typically useful in Customer.io when suppressing people, but you might use them in other places—like an analytics tool (e.g. Mixpanel).
- deliveryIdstring
  The ID of the message delivery.
- metricstring
  The metric you're reporting. Remember, these are metrics that occur outside of Customer.io—after the message is sent. Because this event typically tracks in-app messages, you'll generally see metrics like delivered, opened, clicked, etc.
  Accepted values: delivered, clicked, converted, opened, delivered, clicked, converted, opened
- recipientstring
  The recipient of the message. This field changes depending on the type of message. For in-app messages, this is the person's deviceId; for SMS it's the recipient's phone number; for push notifications, it's their device token.
- reasonstring
  If the message failed for some reason, this field contains the reason why.
- actionValuestring
  For in-app messages that are clicked, this value represents the value of the action the recipient clicked.
- hrefstring
  For in-app messages that are clicked, this value represents the URL/link the recipient clicked.
- additional properties *any type

Updated September 1, 2026