Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.sequenzy.com/llms.txt

Use this file to discover all available pages before exploring further.

​
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

AspectEventsTags
PurposeTrack occurrencesCategorize subscribers
MultipleCan have many of same eventOnly one instance per tag
TimeTimestampedNo timestamp
DataCan carry propertiesNo 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

EventDescription
saas.purchaseCustomer made a purchase
saas.payment_failedPayment attempt failed
saas.cancelledSubscription cancelled
saas.churnCustomer churned (end of cancelled period)
saas.refundRefund processed
saas.upgradePlan upgraded
saas.downgradePlan downgraded
saas.trial_startedTrial period started
saas.trial_endedTrial period ended

​
Contact Events

EventDescription
contact.subscribedSubscribed to communications
contact.unsubscribedUnsubscribed from communications

​
Email Events

EventDescription
email.openedOpened an email
email.clickedClicked a link in email
email.repliedReplied to an email
email.bouncedEmail bounced

​
Commerce Events

EventDescription
ecommerce.order_placedCustomer placed an order
ecommerce.order_cancelledOrder was cancelled
ecommerce.order_fulfilledOrder was fulfilled
ecommerce.order_refundedRefund was created
ecommerce.customer_createdStore customer was created
ecommerce.checkout_startedCheckout started
ecommerce.replenishment_dueA product-specific replenishment reminder is due
ecommerce.back_in_stock_requestedCustomer requested a back-in-stock notification
ecommerce.back_in_stockRequested product or variant returned to stock
ecommerce.back_in_stock_out_of_stockRequested 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.

​
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:
  1. Subscriber is created if they don’t exist
  2. Event definition is created if it’s new
  3. Sync rules are applied (tags added/removed)
  4. 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)

Tags

Use tags with events for segmentation

Sync Rules

Auto-tag based on events

Sequences

Trigger automations with events

Events API

Trigger events via API