Sync Rules

Automatically manage tags based on events

Sync Rules

Sync rules automatically add and remove tags when events occur. They’re the glue between events and tags, enabling powerful automation without manual intervention.

How Sync Rules Work

When an event is triggered for a subscriber:

Event: "saas.purchase"
         │
         ▼
┌─────────────────────────┐
│    Check Sync Rules     │
│    for this event       │
└───────────┬─────────────┘
            │
            ▼
┌─────────────────────────┐
│   Add Tags: "customer"  │
│   Remove: "lead",       │
│           "trial"       │
└─────────────────────────┘

Default Sync Rules

Sequenzy includes built-in sync rules for common SaaS events:

Event	Tags Added	Tags Removed
saas.purchase	customer	lead, past-due, cancelled, churned
saas.churn	churned	customer, cancelled, past-due
saas.cancelled	cancelled	customer
saas.payment_failed	past-due	—
saas.refund	refunded	—
saas.trial_started	trial	lead
saas.trial_ended	—	trial
saas.upgrade	—	—
saas.downgrade	—	—

Default rules are applied automatically. You can customize them per company in Settings.

Sync Rule Anatomy

Each sync rule defines:

{
  "event": "saas.purchase",
  "addTags": ["customer"],
  "removeTags": ["lead", "past-due", "cancelled", "churned"]
}

Field	Description
event	The event name that triggers this rule
addTags	Tags to add when the event fires
removeTags	Tags to remove when the event fires

Execution Order

When an event triggers:

1. Event recorded - Stored in analytics
2. Remove tags - Listed tags are removed first
3. Add tags - Listed tags are added
4. Automations checked - Sequences triggered by new tags

This order ensures clean state transitions.

Use Cases

Customer Lifecycle

Track where subscribers are in their journey:

Event: saas.trial_started
  Add: "trial"
  Remove: "lead"

Event: saas.purchase
  Add: "customer"
  Remove: "lead", "trial", "past-due"

Event: saas.cancelled
  Add: "cancelled"
  Remove: "customer"

Event: saas.churn
  Add: "churned"
  Remove: "customer", "cancelled"

Result: Subscribers always have exactly one lifecycle tag.

Payment Status

Track payment health:

Event: saas.payment_failed
  Add: "past-due"

Event: saas.purchase
  Remove: "past-due"

Subscription Tiers

When integrated with payment providers:

Event: subscription.upgraded_to_pro
  Add: "pro-plan"
  Remove: "starter-plan", "free-tier"

Event: subscription.downgraded_to_starter
  Add: "starter-plan"
  Remove: "pro-plan", "enterprise-plan"

Custom Sync Rules

Create custom rules in Settings → Sync Rules:

Example: Lead Scoring

Event: page_viewed_pricing
  Add: "high-intent"

Event: demo_requested
  Add: "demo-lead", "high-intent"
  Remove: "cold-lead"

Event: demo_completed
  Add: "demo-completed"
  Remove: "demo-lead"

Example: Engagement Tracking

Event: email.opened
  Add: "engaged"
  Remove: "inactive"

Event: product_used
  Add: "active", "engaged"
  Remove: "inactive", "at-risk"

Example: Onboarding Progress

Event: onboarding_step_1_completed
  Add: "onboarding-started"
  Remove: "new-signup"

Event: onboarding_completed
  Add: "onboarded"
  Remove: "onboarding-started"

Sync Rules + Sequences

Sync rules work seamlessly with sequences:

1. Event: "saas.purchase"
         │
         ▼
2. Sync Rule Applied
   Add: "customer"
         │
         ▼
3. Sequence Trigger
   "When tag 'customer' added"
         │
         ▼
4. Sequence Starts
   Customer onboarding flow

This pattern lets you:

• Keep event handling simple (just fire events)
• Centralize tag logic (sync rules)
• Build flexible sequences (tag-based triggers)

Payment Provider Integration

When you connect Stripe or other payment providers:

Automatic Event Firing

The integration automatically fires events:

Stripe Event	Sequenzy Event
customer.subscription.created	saas.purchase
customer.subscription.deleted	saas.cancelled
invoice.payment_failed	saas.payment_failed
customer.subscription.updated (downgrade)	saas.downgrade
customer.subscription.updated (upgrade)	saas.upgrade

Automatic Customer Sync

Stripe customers are synced as subscribers with:

• Email from Stripe customer
• Name from Stripe customer
• Custom attributes for subscription data

Best Practices

1. Design Mutually Exclusive Tags

For lifecycle states, ensure only one tag at a time:

✓ Sync rules that remove old state when adding new
  Event: saas.purchase
    Add: "customer"
    Remove: "lead", "trial", "churned"

✗ Tags that can accumulate
  Event: saas.purchase
    Add: "customer"
    (lead and trial remain)

2. Use System Tags Consistently

Stick to the built-in tag names:

✓ "customer", "lead", "trial", "churned"
✗ "is-customer", "isLead", "in_trial"

3. Test Your Rules

Before going live:

1. Create a test subscriber
2. Trigger events via API
3. Verify tags are added/removed correctly
4. Check that sequences trigger

4. Document Custom Rules

Keep a reference of your custom sync rules:

Event	Add	Remove	Purpose
feature_activated	power-user	new-user	Track activation
support_ticket_opened	needs-support	—	Flag for attention
support_ticket_resolved	—	needs-support	Clear flag

5. Don’t Overcomplicate

Start with default rules, add custom ones as needed:

✓ Start simple
  - Use default SaaS events
  - Add custom rules for specific needs

✗ Over-engineer
  - Custom rule for every possible event
  - Complex tag dependencies

Debugging Sync Rules

Check Event Fired

View subscriber’s event history in dashboard.

Check Tags Applied

View subscriber’s current tags after event.

Common Issues

Issue	Cause	Solution
Tag not added	Event name mismatch	Check event name exactly
Old tag not removed	Not in removeTags	Add to removeTags array
Sequence not triggering	Tag trigger doesn’t match	Verify sequence trigger

Related

Events

Events that trigger sync rules

Tags

Tags managed by sync rules

Sequences

Automations triggered by tags

Subscribers

Contacts that receive tags