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:
- Event recorded - Stored in analytics
- Remove tags - Listed tags are removed first
- Add tags - Listed tags are added
- 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"
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
- 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
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)
✓ "customer", "lead", "trial", "churned"
✗ "is-customer", "isLead", "in_trial"
3. Test Your Rules
Before going live:
- Create a test subscriber
- Trigger events via API
- Verify tags are added/removed correctly
- 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.
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 |
