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"       │
└─────────────────────────┘

Sync rules are managed in Settings, or programmatically: the API exposes GET/PUT /api/v1/sync-rules, the CLI has sequenzy sync-rules get and sequenzy sync-rules update, and the MCP server provides get_sync_rules / update_sync_rules tools.

Optional Platform Preset

New workspaces start with no sync rules, so importing or subscribing a contact does not silently assign a business-stage tag. You can add rules in Settings or opt into Sequenzy’s legacy platform preset for common SaaS and ecommerce events. The preset includes rules such as:

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.trial_cancelled`	`cancelled`	—
`saas.upgrade`	—	—
`saas.downgrade`	—	—

The platform preset is not enabled automatically for new workspaces. Review its SaaS/ecommerce semantics before enabling it for a services, consulting, or other relationship-led business.

Legacy workspaces that still inherit platform defaults continue receiving future updates to that preset for compatibility. Once you save a customized rule set, it replaces the preset entirely. “Reset to Defaults” in Settings opts back into the inheriting preset, and saving an empty rule set disables sync rules completely. Sync rules also run for events Sequenzy records natively - engagement events (email.opened, email.clicked, email.replied), delivery events (email.bounced, email.unsubscribed, contact.unsubscribed), and integration events like ecommerce.back_in_stock_requested. Rules on bounce and unsubscribe events only change tags; they never start a sequence for a suppressed contact.

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

Rules can also carry optional conditions: required subscriber tags, excluded subscriber tags, and (for commerce events) a product match.

Product Match Conditions

Commerce events that carry products - order placed, product viewed, added to cart, and similar - can be filtered by the product itself. Add a Product match condition and the rule only runs when at least one product on the event matches your selected product tags, collections, or product types. This is how you build ownership audiences from purchases. For example, a record store tags every vinyl product with Vinyl in Shopify, then adds a rule:

{
  "event": "ecommerce.order_placed",
  "addTags": ["vinyl-collector"],
  "conditions": {
    "purchasedProduct": { "tags": ["Vinyl"] }
  }
}

Anyone who buys a vinyl record or accessory is tagged vinyl-collector automatically, ready to receive campaigns for that interest. Within a product match, values in the same selector are OR’d (any of these tags) and different selectors are AND’d (must match the tag AND the collection).

Rules with a product match never run for events without product context, so they are safe to combine with tag conditions.

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.trial_cancelled
  Add: "cancelled"

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:

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.

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

Events

Events that trigger sync rules

Sequences

Automations triggered by tags

Subscribers

Contacts that receive tags

​Sync Rules

​How Sync Rules Work

​Optional Platform Preset

​Sync Rule Anatomy

​Product Match Conditions

​Execution Order

​Use Cases

​Customer Lifecycle

​Payment Status

​Subscription Tiers

​Custom Sync Rules

​Example: Lead Scoring

​Example: Engagement Tracking

​Example: Onboarding Progress

​Sync Rules + Sequences

​Payment Provider Integration

​Automatic Event Firing

​Automatic Customer Sync

​Best Practices

​1. Design Mutually Exclusive Tags

​2. Use System Tags Consistently

​3. Test Your Rules

​4. Document Custom Rules

​5. Don’t Overcomplicate

​Debugging Sync Rules

​Check Event Fired

​Check Tags Applied

​Common Issues

​Related

Events

Tags

Sequences

Subscribers

Sync Rules

How Sync Rules Work

Optional Platform Preset

Sync Rule Anatomy

Product Match Conditions

Execution Order

Use Cases

Customer Lifecycle

Payment Status

Subscription Tiers

Custom Sync Rules

Example: Lead Scoring

Example: Engagement Tracking

Example: Onboarding Progress

Sync Rules + Sequences

Payment Provider Integration

Automatic Event Firing

Automatic Customer Sync

Best Practices

1. Design Mutually Exclusive Tags

2. Use System Tags Consistently

3. Test Your Rules

4. Document Custom Rules

5. Don’t Overcomplicate

Debugging Sync Rules

Check Event Fired

Check Tags Applied

Common Issues

Related