Update subscription group status for customers

You can associate customers with subscription groups in three main ways: 

• Identify events
• Data imports
• Customer Profile API

Once the data is ingested, subscription group details appear in the customer’s profile under the Subscription groups section.

Update via identify events

Send an identify event when you know who the customer is. This lets you update their subscription group status in real time. You can use either a flat or nested format.

Flat format

{
  "event": "identify",
  "email": "john.doe@example.com",
  "customer_id": "customer_123",
  "subscription_group_id": "newsletter",
  "subscription_group_subscribed": true
}

Nested format

{
  "event": "identify",
  "email": "jane.doe@example.com",
  "customer_id": "customer_456",
  "subscription_groups": [
    {
      "id": "newsletter",
      "subscribed": true
    },
    {
      "id": "promotions",
      "subscribed": false
    }
  ]
}

For details on tracking event data from your site or app and sending it to Blueshift, please take a look at Send events from your site or app.

Update via imports

You can update subscription groups through file imports (CSV, Data Warehouse, or JSONL). This method is helpful for large datasets or scheduled updates.

Flat format import

For flat files (CSV, JSONL, or Data Warehouse), map your data file to the following attributes:

Nested format import

Nested imports let you include multiple subscription groups in a single record. This is supported for Data Warehouse and JSONL formats. In this case, the subscription_groups attribute is treated as an array of objects.

Example: one row can contain customer_id and an array of groups, each with an id and subscribed value.

For detailed instructions on setting up customer imports, please take a look at the Import customer data documentation.

Update via Customer Profile API

You can also associate customers with subscription groups using the Bulk Create or Update Customers API. This method is recommended when you want to update subscription groups for one or more users programmatically.

Single group (flat format)

Use this format to update a single customer with one subscription group:

{
  "email": "john.doe@example.com",
  "subscription_group_id": "newsletter",
  "subscription_group_subscribed": true
}

Multiple groups (nested format)

Use this format to update a single customer with multiple subscription groups in one request:

{
  "email": "jane.doe@example.com",
  "subscription_groups": [
    {
      "id": "newsletter",
      "subscribed": true
    },
    {
      "id": "promotions",
      "subscribed": false
    }
  ]
}

"subscription_groups": [
  { "id": "newsletter", "subscribed": true },
  { "id": "promotions", "subscribed": false },
  { "id": "offers123", "subscribed": true }
]
  

View subscription groups on the customer profile

After data is ingested—whether through events, imports, or APIs—the associated subscription groups appear in the Subscription groups section of the customer profile. This view shows each group alongside its subscription status and the most recent update timestamp.