Events

Events are the heart of the engagement platform. The model is simple — Event → Programme → Reward: you tell us what happened, you configure a programme that listens for it, and we issue a reward. This guide covers the two halves of the event surface: event definitions (describing the events you emit) and event submission (sending them).

1. Define an event

An event definition is a tenant-scoped description of something that happens in your product. It has a stable key (e.g. purchase.completed), a name, and a JSON-Schema properties document that submitted payloads are validated against. identityProperty names the payload field carrying the member identifier (defaults to customerId).

curl -X POST https://loyalty-engine-production-e5cb.up.railway.app/v1/tenants/YOUR_TENANT_ID/event-definitions \
  -H "X-API-Key: sk_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "key":  "purchase.completed",
    "name": "Purchase Completed",
    "identityProperty": "customerId",
    "properties": {
      "customerId": { "type": "string" },
      "amount":     { "type": "number" },
      "storeId":    { "type": "string" }
    }
  }'

Manage definitions with GET/PATCH /event-definitions. Changing properties bumps the definition version and re-compiles the payload validator. Archive a definition to stop accepting new events for its key.

2. Submit an event

Once a definition exists, submit events against it. We validate the payload against the schema, resolve (and auto-create) the member from the identity property, then fire any matching programmes — all in one idempotent call. Replaying the same ref returns the original result, so it is safe to retry.

curl -X POST https://loyalty-engine-production-e5cb.up.railway.app/v1/tenants/YOUR_TENANT_ID/events \
  -H "X-API-Key: sk_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "eventKey": "purchase.completed",
    "ref":      "order-10293",
    "payload":  { "customerId": "cust-abc", "amount": 750, "storeId": "store-1" }
  }'

Unlike the fixed lifecycle endpoint (POST /members/:id/events, test-key only), this generic endpoint accepts both sk_test_* and sk_live_* keys — production integrations submit domain events here.

3. Query event activity

Inspect the event feed, filtered by member and/or event key. Newest first, keyset-paginated via nextCursor.

curl "https://loyalty-engine-production-e5cb.up.railway.app/v1/tenants/YOUR_TENANT_ID/events?eventKey=purchase.completed&limit=50" \
  -H "X-API-Key: sk_test_YOUR_KEY"

Stamp a card from an event

A STAMP_CARD programme whose earningRule.triggerEventKey matches the submitted event key records one stamp per matching event. On the Nth stamp it issues the card's rewardOnCompletion (points or a tangible reward) and fires member.stamp_card_completed — the same completion behaviour as a till-driven card. See Campaigns.