​
Overview

Customer audience enrollment in Masivo is powered by a sophisticated tagging and segmentation system. By assigning tags to customers, you enable automatic enrollment into dynamic audiences based on conditions and customer behavior. This guide covers the complete workflow from tag management to audience segmentation.
Customer tags are key-value pairs stored in the customer’s tags field. These tags are used by audience conditions to automatically segment customers into targeted groups for marketing campaigns.

​
Understanding Customer Tags and Audiences

​
Customer Tags System

Customer tags in Masivo are flexible key-value pairs that can store:
  • String values: "vip_status": "gold"
  • Number values: "lifetime_purchases": 15
  • Boolean values: "newsletter_subscriber": true

​
Audience Enrollment Process

When you assign tags to customers, Masivo automatically:
  1. Evaluates Audience Conditions: Checks all active audiences for matching conditions
  2. Enrolls Customers: Adds qualifying customers to the customers_by_audience table
  3. Subscribes to FCM Topics: Automatically subscribes device tokens to audience-specific topics
  4. Enables Targeting: Makes customers available for audience-specific campaigns and journeys

​
1. Managing Customer Tags

​
Assign Tags to Customers

Use the PATCH /customers/{id}/tags endpoint to assign or update customer tags: 
const customerId = "your-customer-id";
const customerTags = {
  vip_status: "gold",
  lifetime_purchases: 15,
  newsletter_subscriber: true,
  last_purchase_category: "electronics",
  preferred_language: "en"
};

const response = await fetch(
  `https://app.masivo.ai/api/storefront/v1/customers/${customerId}/tags`,
  {
    method: "PATCH",
    headers: {
      Authorization: `Bearer ${accessToken}`,
      "Content-Type": "application/json",
      "x-account-id": "your-account-id"
    },
    body: JSON.stringify({ tags: customerTags })
  }
);

if (response.ok) {
  const result = await response.json();
  console.log("Customer tags updated:", result.data.customer.tags);
} else {
  const error = await response.json();
  console.error("Tag assignment failed:", error.details);
}

​
Tag Assignment Behavior

When assigning tags, Masivo:
  • Merges Tags: New tags are merged with existing ones using { ...existingTags, ...newTags }
  • Overwrites Values: If a tag key already exists, the new value overwrites the old one
  • Preserves Other Tags: Existing tags not included in the request remain unchanged

​
Remove Customer Tags

Use the DELETE /customers/{id}/tags endpoint to remove specific tags: 
const removeCustomerTags = async (
  customerId: string,
  tagsToRemove: string[]
) => {
  const tagsParam = tagsToRemove.join(",");

  const response = await fetch(
    `https://app.masivo.ai/api/storefront/v1/customers/${customerId}/tags?tags=${encodeURIComponent(tagsParam)}`,
    {
      method: "DELETE",
      headers: {
        Authorization: `Bearer ${accessToken}`,
        "Content-Type": "application/json"
      }
    }
  );

  if (response.ok) {
    const result = await response.json();
    console.log("Tags removed successfully:", result.data.customer.tags);
  } else {
    const error = await response.json();
    console.error("Tag removal failed:", error.details);
  }
};

// Remove specific tags
await removeCustomerTags("customer-123", ["old_segment", "temporary_flag"]);

​
2. Audience Segmentation with Tags

​
How Audience Conditions Work

Masivo audiences use customer tags for segmentation through condition matching. The system supports various condition types:

​
String Tag Conditions

// Example: Target customers with VIP status
const condition = {
  type: "Customer includes tag",
  primitive: "string",
  tag: "vip_status_tag_id", // Reference to customer tag definition
  operator: "equals",
  value: "gold"
};

​
Number Tag Conditions

// Example: Target customers with high purchase count
const condition = {
  type: "Customer includes tag",
  primitive: "number",
  tag: "lifetime_purchases_tag_id",
  operator: "greater_than",
  value: 10
};

​
Boolean Tag Conditions

// Example: Target newsletter subscribers
const condition = {
  type: "Customer includes tag",
  primitive: "boolean",
  tag: "newsletter_subscriber_tag_id",
  operator: "equals",
  value: true
};

​
Automatic Audience Enrollment

When you assign tags to customers, Masivo automatically:
  1. Processes Audience Conditions: Evaluates all active audiences against the customer’s updated tags
  2. Enrolls in Matching Audiences: Adds customer to customers_by_audience table for qualifying audiences
  3. FCM Topic Subscription: Subscribes customer’s device tokens to audience-specific topics ({account_id}_audience_{audience_id})
  4. Real-time Updates: Processes enrollment in background queues for scalability

​
Tag-Based Segmentation Examples

​
E-commerce Segmentation

// Segment high-value customers
const highValueCustomerTags = {
  lifetime_value: 1500,
  purchase_frequency: "high",
  preferred_category: "premium",
  vip_member: true
};

// Segment cart abandoners
const cartAbandonerTags = {
  cart_status: "abandoned",
  last_cart_value: 89.99,
  abandonment_count: 3,
  email_sent: false
};

​
Subscription Business Segmentation

// Segment trial users
const trialUserTags = {
  subscription_status: "trial",
  trial_days_remaining: 7,
  feature_usage_score: 0.6,
  onboarding_completed: true
};

// Segment churned customers
const churnedCustomerTags = {
  subscription_status: "cancelled",
  churn_reason: "price",
  last_login_days_ago: 30,
  win_back_eligible: true
};

​
Conclusion

Customer audience enrollment in Masivo is a powerful system that automatically segments customers based on their tags. By strategically assigning and managing customer tags, you enable sophisticated audience targeting for personalized marketing campaigns and customer journeys. The automatic enrollment system ensures that customers are always in the right audiences based on their current attributes and behaviors, enabling real-time personalization and targeted messaging through FCM topics and campaign targeting. For more information about audience creation and management, see the Create Audiences Guide.