Skip to content

Model multi-subscription accounts with subscription-level profiles

Give each subscription under a shared customer account its own Braze user profile, linked by an account ID custom attribute, so you can message and report at the subscription level while still grouping profiles that belong to the same account.

About this example

StyleRyde is a fictional on-demand ridesharing brand where one customer account can hold multiple subscriptions. For example, a household plan can cover several riders, each with a unique phone number. Consumers log in once at the account level, then choose which subscription (phone line) to manage.

StyleRyde needs to do the following:

  • Send service SMS to the phone number on a specific subscription.
  • Send marketing push and Content Cards to the device session for the active subscription.
  • Keep push and SMS marketing preferences, push and SMS engagement history, and Currents data at the individual subscription level.
  • Group related subscriptions for account-level reporting and journeys.

Braze models engagement around the user profile. Email, phone, preference attributes, and channel history live on that profile. For multi-subscription accounts, treat each subscription as its own user profile, then group profiles with a shared account_id custom attribute. Think of users grouped by account ID, rather than a single account object that contains users.

This example covers the subscription-level profiles pattern. Use it when each subscription has (or can have) a stable unique ID that your app can pass to changeUser().

Considerations

  • Active user ID: Call changeUser() with the subscription ID when a consumer logs in or switches subscriptions. The SDK associates one active user ID per session.
  • Shared account IDs: Don’t call changeUser() with a shared account ID for all subscriptions on a device. That mixes engagement across people and breaks logout and re-engagement. See How changeUser() works.
  • Shared email addresses: Multiple profiles can share one address. Before you rely on shared inboxes, review the email FAQ and email subscription state.
    • Email opt-in: Opt-in follows the address. A change on one profile copies to up to 100 other profiles with the same address. Push and SMS preferences can still differ by subscription when phone numbers are unique.
    • Email deduplication: Braze deduplicates segment-based scheduled sends to a shared address. Named-recipient and later Canvas steps can still send to that address more than once.
    • Email engagement: Deliveries, opens, clicks, and spam reports are recorded on each matching profile (up to 100), and Braze personalizes the send for the one profile it selects.
  • SMS phone numbers: Use a unique phone number on each subscription profile when SMS is your service channel. Phone is stored on the profile you target for SMS.
  • Push tokens: Push tokens belong to one profile per device. See Step 3 for what happens when a consumer switches subscriptions.
  • Account rollups: Account-level rollups (for example, “any subscription on this account purchased a monthly pass”) need a warehouse or Currents join on account_id. An account_id segment filter returns each profile with that value.
  • Billing: Each subscription profile counts as a separate profile toward your monthly active users (MAU) and data point usage, as described in Billing and Data points (Legacy).

Setup

Step 1: Define identifiers

Map your CRM identifiers to Braze as follows.

Concept StyleRyde example Braze field
Account (login and billing) Household account acct_12345 Custom attribute account_id (string) on every related profile
Subscription (individual line) Rider subscription sub_12345_1 Profile external_id
Contact email Shared household email Profile email (may repeat across profiles)
Contact phone Unique per subscription Profile phone

Use a stable, unique subscription ID as external_id. Keep the account ID as a custom attribute so you can segment and join related profiles without collapsing them into one Braze user.

Step 2: Create one profile per subscription

Create or update each subscription through the SDK or the /users/track endpoint. Include at least the following:

Field What to store
external_id Subscription ID
email and phone Contact fields when captured
account_id Shared account identifier
Role or ownership attributes For example, is_account_owner
Push and SMS marketing preference attributes Values you need for segmentation. Email opt-in is managed with email subscription states and groups, which apply per address.

Example profile layout for two StyleRyde accounts:

Attribute Profile A Profile B Profile C Profile D
external_id (subscription) sub_12345_1 sub_12345_2 sub_12345_3 sub_789_1
account_id acct_12345 acct_12345 acct_12345 acct_789
email [email protected] [email protected] [email protected] [email protected]
phone +15555550101 +15555550102 +15555550103 +15555550901
is_account_owner false true false true
marketing_sms_opt_in true true false false

Each column is a separate Braze user. Profiles A to C share account_id acct_12345 but keep distinct phones, SMS preferences, and SMS and push engagement history. Because they share [email protected], they also share one email subscription state and email engagement.

Example /users/track attribute payload for one subscription:

{
  "attributes": [
    {
      "external_id": "sub_12345_2",
      "email": "[email protected]",
      "phone": "+15555550102",
      "account_id": "acct_12345",
      "is_account_owner": true,
      "marketing_sms_opt_in": true
    }
  ]
}

Step 3: Identify the active subscription in the SDK

When the consumer logs in or switches which subscription they are managing, call changeUser() with that subscription’s external_id.

// After the consumer selects subscription sub_12345_2 in the StyleRyde app
braze.changeUser("sub_12345_2");

Push tokens, Content Cards, and in-app messages then follow the active subscription profile for that session. If the consumer switches to another subscription in-app, call changeUser() again with the new subscription ID.

When a profile registers a device’s push token, Braze removes that token from every other profile on the same device. In practice, an account owner who switches between subscriptions on one phone receives push only for the subscription they selected last. Push messages aimed at the other subscriptions don’t reach that phone.

Step 4: Align channels with profile fields

Channel Target using
SMS (service) phone on the subscription profile you intend to reach
Email Use email on the profile. Profiles that share an address also share email subscription state, and some sends are deduplicated, as described in Considerations.
Push and Content Cards The profile currently set with changeUser() on the device. The device’s push token belongs only to the profile that registered it last.

For account-owner-only journeys (for example, billing reminders), filter where is_account_owner is true and the relevant account_id or subscription attributes.

Step 5: Segment and report with account and subscription attributes

  • Build subscription-level segments with phone, push and SMS marketing preferences, and subscription-specific custom attributes.
  • Build account-scoped audiences with the account_id filter (for example, all subscriptions where account_id equals acct_12345). This filter selects each profile with that value.
  • Use Currents and user-level analytics on each subscription profile for engagement reporting. Join on account_id in your warehouse when you need household rollups, such as “account X has a profile that purchased a monthly pass”.
  • Email deliveries, opens, clicks, and spam reports can be stored on more than one profile that shares an address, so account for that when you join on account_id, as described in Considerations.
New Stuff!