Events & Automation

Events let you automate your loyalty program. Instead of manually awarding points, send events when things happen and let rules do the work.

---

The Event-Driven Model

Why Events?

Approach	How It Works	Best For
Manual points	You calculate and award points	One-off bonuses, adjustments
Event-driven	You send events, rules calculate points	Scalable automation

The Flow

Customer makes purchase → You send "purchase" event → Rules evaluate → Points awarded automatically

Benefits:

• ✅ No code changes when rules change
• ✅ Consistent point calculations
• ✅ Full audit trail of all activity
• ✅ Analytics on customer behavior

---

Event Types

Define what actions you want to track and reward.

Common Event Types

Event	When to Send	Typical Points Logic
purchase	Order completed	1 point per dollar spent
signup	Account created	Fixed 100 points
review	Review submitted	Fixed 25-50 points
referral	Friend signs up	Fixed 500 points
social_share	Shared on social	Fixed 10-25 points
profile_complete	All fields filled	Fixed 50 points
app_download	Mobile app installed	Fixed 100 points
birthday	Customer's birthday	Fixed bonus (or automated)

Event Properties

Events can include properties that rules use for calculations:

Event Type	Useful Properties
purchase	amount, category, product_count, order_id
review	rating, has_photo, product_id
referral	referred_email, signup_completed
checkin	location, visit_count

---

Points Rules

Rules define how events translate into points. They're configured in the Dashboard and evaluate automatically.

Rule Anatomy

Component	Description	Example
Condition	When the rule applies	properties.amount > 0
Formula	How points are calculated	properties.amount * 1
Multiplier	Tier bonuses applied	Automatic based on tier

Example Rules

Simple: 1 point per dollar

Formula: properties.amount × 1
$125 purchase = 125 points

Tiered: Bonus for big orders

Formula: properties.amount × 1 + (properties.amount > 100 ? 50 : 0)
$50 purchase = 50 points
$150 purchase = 150 + 50 bonus = 200 points

Category bonus: 2x on electronics

Condition: properties.category == "electronics"
Formula: properties.amount × 2

---

Event Processing

What Happens When You Send an Event

1. Validation — Is the customer valid? Is the event type defined?
2. Rule Matching — Which rules apply to this event?
3. Point Calculation — Apply formulas and tier multipliers
4. Point Award — Add to customer's balance and lifetime total
5. Response — Return points awarded and rules applied

Idempotency & Duplicates

Problem: What if you accidentally send the same purchase event twice?

Solution: Use the reference field. Events with the same reference return the existing result instead of creating duplicates.

First call:  reference: "order_123" → Creates event, awards 100 pts
Second call: reference: "order_123" → Returns existing event, no new points

Always include a reference for any event tied to a transaction in your system.

---

Automation Strategies

Purchase Integration

For ecommerce, trigger events from your order webhook:

Order completed webhook fires
    ↓
Send "purchase" event with amount and order_id
    ↓
Points awarded automatically
    ↓
Customer sees new balance

Engagement Automation

Award points for non-purchase activities:

Trigger	Event to Send
User leaves a review	review event
User refers a friend	referral event
User completes profile	profile_complete event
User uses mobile app	app_engagement event
User visits store	checkin event

Scheduled Events

Some events happen on a schedule:

Event	Trigger
Birthday bonus	Cron job on customer birthday
Anniversary	Account creation anniversary
Inactivity reminder	X days since last activity

---

Events vs Direct Points

When to Use Events

✅ Points depend on transaction details (amount, category) ✅ You want automatic calculation with rules ✅ You need analytics on customer activity ✅ Rules might change over time ✅ High volume (purchases, engagement)

When to Use Direct Points

✅ One-off manual awards ✅ Customer service adjustments ✅ Fixed bonuses where events are overkill ✅ External integrations that calculate their own points ✅ Data migrations

---

Event Analytics

What You Can Learn

Metric	What It Tells You
Events per customer	Engagement level
Events by type	Which activities drive engagement
Points per event	Value of different activities
Event frequency	Customer behavior patterns

Segmentation by Behavior

Use event data to segment:

• High engagers — 10+ events per month
• Purchasers — Have purchase events
• Advocates — Have referral or review events
• At risk — No events in 30+ days

---

Bulk Events

For high-volume scenarios or data migrations:

When to Use Bulk

• Importing historical transactions
• Syncing large batches of orders
• Event replay after system issues
• End-of-day batch processing

Bulk Best Practices

• Up to 1,000 events per request
• Include unique references for each event
• Handle partial failures gracefully
• Consider rate limits on large imports

---

Common Mistakes

❌ Don't Do This

Mistake	Problem	Better Approach
No reference field	Duplicate points on retries	Always include unique reference
Sending without validation	Bad data causes errors	Validate before sending
Hardcoding point values	Can't change without deploy	Use rules in Dashboard
Ignoring responses	Missing failed events	Log and handle errors
No testing	Prod surprises	Test in dev environment first

---

Dashboard vs API

Task	Dashboard	API
Create event types	✅ Visual editor	✅ CRUD endpoints
Configure rules	✅ Rule builder	✅ Rule endpoints
Send events	❌ Not practical	✅ Automated sending
View event history	✅ Activity log	✅ History endpoints
Bulk processing	❌	✅ Bulk endpoint

---

Next Steps

• API Reference → — Full technical documentation for event endpoints
• Webhooks — React to events in your system
• Points Guide — Understand point mechanics