Events

Events represent actions or occurrences in your application that are associated with a subscriber. They’re the foundation for behavioral automation and analytics.

What Are Events?

Events are timestamped records of something that happened:

{
  "email": "user@example.com",
  "event": "purchase_completed",
  "properties": {
    "orderId": "order_12345",
    "amount": 99.99,
    "product": "Pro Plan",
    "currency": "USD"
  }
}

Unlike tags (which represent current state), events represent what happened and when.

Events vs Tags

Aspect	Events	Tags
Purpose	Track occurrences	Categorize subscribers
Multiple	Can have many of same event	Only one instance per tag
Time	Timestamped	No timestamp
Data	Can carry properties	No additional data
Use case	”User purchased 3 times"	"User is a customer”

Use events when:

The action can happen multiple times
You need to track when it happened
You want to attach properties/metadata
You’re building analytics

Use tags when:

You’re categorizing subscribers
You need to segment for campaigns
You want simple presence/absence logic

Built-in Events

Sequenzy recognizes these built-in event types:

SaaS Events

Event	Description
`saas.purchase`	Customer made a purchase
`saas.payment_failed`	Payment attempt failed
`saas.cancelled`	Subscription cancelled
`saas.churn`	Customer churned (end of cancelled period)
`saas.refund`	Refund processed
`saas.upgrade`	Plan upgraded
`saas.downgrade`	Plan downgraded
`saas.trial_started`	Trial period started
`saas.trial_ended`	Trial period ended
`saas.trial_cancelled`	Trial was cancelled before paid conversion

Contact Events

Event	Description
`contact.subscribed`	Subscribed to communications
`contact.unsubscribed`	Unsubscribed from communications

Email Events

Event	Description
`email.opened`	Opened an email
`email.clicked`	Clicked a link in email
`email.replied`	Replied to an email
`email.bounced`	Email bounced

Commerce Events

Event	Description
`ecommerce.order_placed`	Customer placed an order
`ecommerce.order_cancelled`	Order was cancelled
`ecommerce.order_fulfilled`	Order was fulfilled
`ecommerce.order_shipped`	A shipment left the warehouse
`ecommerce.order_out_for_delivery`	A shipment is out for delivery
`ecommerce.order_delivered`	A shipment was delivered
`ecommerce.delivery_failed`	A delivery attempt failed
`ecommerce.order_refunded`	Refund was created
`ecommerce.price_drop`	Price dropped on a recently viewed product
`ecommerce.browse_abandoned`	Viewed a product but didn’t buy or add to cart
`ecommerce.collection_viewed`	Known customer viewed a store collection
`ecommerce.search_submitted`	Known customer searched the store
`ecommerce.customer_created`	Store customer was created
`ecommerce.checkout_started`	Checkout started
`ecommerce.replenishment_due`	A product-specific replenishment reminder is due
`ecommerce.back_in_stock_requested`	Customer requested a back-in-stock notification
`ecommerce.back_in_stock`	Requested product or variant returned to stock
`ecommerce.back_in_stock_out_of_stock`	Requested product or variant went out of stock

Built-in events automatically apply sync rules when triggered.

Custom Events

Create your own events for any action in your application:

curl -X POST "https://api.sequenzy.com/api/v1/subscribers/events" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "event": "feature_used",
    "properties": {
      "feature": "export",
      "format": "csv",
      "rowCount": 1500
    }
  }'

Common Custom Events

Product engagement:

feature_used
project_created
file_uploaded
report_generated

User lifecycle:

onboarding_completed
first_value_moment
invited_team_member

E-commerce:

product_viewed
cart_started
cart_cleared
checkout_started
review_submitted

Content:

article_read
video_watched
course_completed

Event Properties

Properties are key-value data attached to events:

{
  "event": "order_placed",
  "properties": {
    "orderId": "ord_abc123",
    "total": 149.99,
    "currency": "USD",
    "items": ["Product A", "Product B"],
    "couponUsed": "SAVE20",
    "isFirstOrder": true
  }
}

Property Types

Properties can be:

Strings: "product": "Pro Plan"
Numbers: "amount": 99.99
Booleans: "isFirstPurchase": true
Arrays: "tags": ["new", "featured"]
Objects: "metadata": { "source": "web" }

Using Properties in Sequences

Properties can be accessed in sequence conditions and personalization:

Condition: event.properties.amount > 100
Action: Send "high-value-purchase" email

For email personalization, use event. merge tags inside sequence emails:

{{event.amount}}
{{event.product}}
{{event.order.id}}

Sequenzy stores the event snapshot on the sequence run when the subscriber enters the automation. That lets you reference the same event properties in the first, second, or third email without copying them onto the subscriber profile. When you edit an email inside an event-triggered sequence, the editor preview and test sends fill event. merge tags with values from the most recent matching event, so you see what a live send would render. You can override any value in the preview data panel before sending a test.

Commerce Product Matching

Commerce automations use explicit product IDs from event properties. If you trigger commerce events manually, include these fields so Sequenzy can match replenishment and back-in-stock sequences correctly. For order events, send product data in lineItems:

{
  "event": "ecommerce.order_placed",
  "properties": {
    "orderId": "ord_123",
    "orderedAt": "2026-04-02T00:00:00.000Z",
    "lineItems": [
      {
        "provider": "shopify",
        "providerProductId": "788032119674292922",
        "providerVariantId": "45123456789123",
        "title": "Protein Powder",
        "variantTitle": "Vanilla",
        "quantity": 1,
        "priceCents": 8850
      }
    ]
  }
}

For product-triggered events such as ecommerce.replenishment_due, ecommerce.back_in_stock, or ecommerce.back_in_stock_out_of_stock, include product fields at the top level or inside product:

{
  "event": "ecommerce.back_in_stock",
  "properties": {
    "provider": "shopify",
    "providerProductId": "788032119674292922",
    "providerVariantId": "45123456789123",
    "product": {
      "providerId": "788032119674292922",
      "providerVariantId": "45123456789123",
      "title": "Protein Powder",
      "variantTitle": "Vanilla",
      "imageUrl": "https://cdn.example.com/product.png",
      "url": "https://store.example.com/products/protein-powder"
    }
  }
}

Sequenzy checks:

provider - usually shopify or woocommerce
providerProductId or product.providerId
providerVariantId or product.providerVariantId when exact variant matching is needed
lineItems[].providerProductId on purchase events
lineItems[].providerVariantId on purchase events when variant matching is needed

Triggering Events

Single Event

curl -X POST "https://api.sequenzy.com/api/v1/subscribers/events" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "event": "purchase_completed",
    "properties": {
      "orderId": "order_123",
      "amount": 99.99
    }
  }'

Multiple Events (Bulk)

curl -X POST "https://api.sequenzy.com/api/v1/subscribers/events/bulk" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "events": [
      {
        "event": "page_viewed",
        "properties": { "page": "/pricing" }
      },
      {
        "event": "feature_used",
        "properties": { "feature": "calculator" }
      }
    ]
  }'

Auto-Creation

When you trigger an event:

Subscriber is created if they don’t exist
Event definition is created if it’s new
Sync rules are applied (tags added/removed)
Automations are triggered if matching

Dashboard Visibility

In Settings → Events, Sequenzy now shows:

How many unique contacts received each event in the last 24 hours
Which active sequences currently trigger from that event
Which paused sequences would trigger if you reactivate them

This makes it easier to verify that your event naming is correct and to spot when an event is feeding multiple automations.

Events and Sync Rules

Events can automatically modify tags through sync rules:

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

Configure Sync Rules

Set up automatic tagging based on events

Events in Sequences

Trigger: Event Received

Start a sequence when an event occurs:

Trigger: event_received "purchase_completed"
    │
    ▼
┌─────────────────┐
│ Thank You Email │
└─────────────────┘
    │
    ▼
┌─────────────────┐
│ Wait 3 days     │
└─────────────────┘
    │
    ▼
┌─────────────────┐
│ Feedback Email  │
└─────────────────┘

Wait For Event

Pause execution until an event occurs:

┌─────────────────────┐
│ Send Onboarding     │
│ Email #1            │
└─────────────────────┘
    │
    ▼
┌─────────────────────┐
│ Wait for Event:     │
│ "onboarding_done"   │
│ Timeout: 7 days     │
└─────────────────────┘
    │
    ├── Event received ──────┐
    │                        │
    ▼                        ▼
┌─────────────┐      ┌─────────────┐
│ Send Tips   │      │ Send Help   │
│ Email       │      │ Email       │
└─────────────┘      └─────────────┘

Condition: Check Event Properties

Branch based on event data:

┌─────────────────────────┐
│ Condition:              │
│ event.properties.amount │
│ > 500                   │
└─────────────────────────┘
         │
    ┌────┴────┐
    │         │
   Yes        No
    │         │
    ▼         ▼
┌─────────┐ ┌─────────┐
│ VIP     │ │ Standard│
│ Email   │ │ Email   │
└─────────┘ └─────────┘

Integration Examples

E-commerce Purchase

// After successful payment
await fetch("https://api.sequenzy.com/api/v1/subscribers/events", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    email: order.customerEmail,
    event: "saas.purchase",
    properties: {
      orderId: order.id,
      amount: order.total,
      currency: order.currency,
      products: order.items.map((i) => i.name),
      isFirstOrder: customer.orderCount === 1,
    },
    customAttributes: {
      lastOrderDate: new Date().toISOString(),
      totalSpent: customer.totalSpent,
    },
  }),
});

Feature Activation

// When user completes onboarding
await fetch("https://api.sequenzy.com/api/v1/subscribers/events", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    email: user.email,
    event: "onboarding_completed",
    properties: {
      completedSteps: ["profile", "integration", "first-project"],
      timeToComplete: "2 days",
    },
  }),
});

Subscription Lifecycle

// Stripe webhook handler
switch (event.type) {
  case "customer.subscription.created":
    await triggerEvent(email, "saas.purchase", {
      plan: subscription.plan.nickname,
      amount: subscription.plan.amount / 100,
      interval: subscription.plan.interval,
    });
    break;

  case "customer.subscription.deleted":
    await triggerEvent(email, "saas.cancelled", {
      reason: subscription.cancellation_details?.reason,
      feedback: subscription.cancellation_details?.feedback,
    });
    break;

  case "invoice.payment_failed":
    await triggerEvent(email, "saas.payment_failed", {
      invoiceId: invoice.id,
      attemptCount: invoice.attempt_count,
    });
    break;
}

Event Analytics

Events are stored and available for analysis:

Event counts: How many times an event occurred
Time series: Events over time
Subscriber timeline: All events for a subscriber
Funnel analysis: Conversion between events

Best Practices

1. Use Consistent Naming

✓ "order.placed", "order.shipped", "order.delivered"
✓ "feature.used", "feature.activated"

✗ "order_placed", "OrderShipped", "order-delivered"

2. Include Relevant Properties

✓ Event: "purchase_completed"
  Properties: { orderId, amount, products, isFirstOrder }

✗ Event: "purchase_completed"
  Properties: {} (missing context)

3. Don’t Over-Event

Track meaningful actions, not every click:

✓ "checkout_started", "checkout_completed"
✗ "button_clicked", "page_scrolled" (too granular)

4. Use Events for Analytics, Tags for Segmentation

✓ Event: "feature_used" (track usage patterns)
  Tag: "power-user" (segment for campaigns)

✗ Tag: "used-feature-jan", "used-feature-feb" (tag per occurrence)

Sync Rules

Auto-tag based on events

Sequences

Trigger automations with events

Events API

Trigger events via API

​Events

​What Are Events?

​Events vs Tags

​Built-in Events

​SaaS Events

​Contact Events

​Email Events

​Commerce Events

​Custom Events

​Common Custom Events

​Event Properties

​Property Types

​Using Properties in Sequences

​Commerce Product Matching

​Triggering Events

​Single Event

​Multiple Events (Bulk)

​Auto-Creation

​Dashboard Visibility

​Events and Sync Rules

Configure Sync Rules

​Events in Sequences

​Trigger: Event Received

​Wait For Event

​Condition: Check Event Properties

​Integration Examples

​E-commerce Purchase

​Feature Activation

​Subscription Lifecycle

​Event Analytics

​Best Practices

​1. Use Consistent Naming

​2. Include Relevant Properties

​3. Don’t Over-Event

​4. Use Events for Analytics, Tags for Segmentation

​Related

Tags

Sync Rules

Sequences

Events API

Events

What Are Events?

Events vs Tags

Built-in Events

SaaS Events

Contact Events

Email Events

Commerce Events

Custom Events

Common Custom Events

Event Properties

Property Types

Using Properties in Sequences

Commerce Product Matching

Triggering Events

Single Event

Multiple Events (Bulk)

Auto-Creation

Dashboard Visibility

Events and Sync Rules

Events in Sequences

Trigger: Event Received

Wait For Event

Condition: Check Event Properties

Integration Examples

E-commerce Purchase

Feature Activation

Subscription Lifecycle

Event Analytics

Best Practices

1. Use Consistent Naming

2. Include Relevant Properties

3. Don’t Over-Event

4. Use Events for Analytics, Tags for Segmentation

Related