Skip to content

Customers and events

Your application tells Customer.lite who its users are and what they do. Workflows react to both.

A customer is one of your users, identified by your ID for them: the id you pass to customers.upsert (1 to 256 characters). Use the same ID your application already uses, so you never need to store a Customer.lite ID.

Terminal window
curl -X PUT <app-origin>/api/customers/user_123 \
-H "Authorization: Bearer $CUSTOMER_LITE_API_KEY" \
-H "content-type: application/json" \
-d '{"email": "ada@example.com", "attributes": {"plan": "trial", "seats": 3}}'
  • email is where messages go. A customer without one is never sent email: its send is skipped with the reason no_address.
  • attributes are your data about the customer: keys up to 128 characters, values that are strings (up to 10,000 characters), numbers, booleans, or null. Workflow conditions read them. An upsert replaces the attributes you send and keeps the others.
  • unsubscribed says whether the customer has unsubscribed (Sending).

customers.upsert is idempotent: sending the same call again leaves the same customer.

An event is something a customer did, such as user.signed_up or project.created. Record it with events.track:

Terminal window
curl -X POST <app-origin>/api/events \
-H "Authorization: Bearer $CUSTOMER_LITE_API_KEY" \
-H "content-type: application/json" \
-d '{
"customerId": "user_123",
"name": "project.created",
"properties": { "projectName": "Demo" },
"idempotencyKey": "project-created-42"
}'
  • The customer must exist first; an unknown customerId answers not_found.
  • An event is stamped with the time it is received. Back-dated events are not supported.
  • name is up to 128 characters. Each live workflow whose trigger names this event starts a run for the customer.
  • Retries. If your client may retry, send an idempotencyKey. A repeated call with the same key records nothing new: it returns the first call’s eventId with duplicate: true, and starts no second run.

Deleting a customer and their data through the API, inbound webhooks from other services (with signature verification and a payload mapping), and conditions over a customer’s event history, are planned. Today a workflow condition reads the customer’s attributes.