Create custom event

Create a custom event to trigger flows with merchant-defined event names and properties.

Custom events allow merchants to trigger flows based on events from their own systems. Events can include custom properties that are accessible in email and SMS templates, and are persisted for segmentation and historical queries.

Identity Resolution

The API resolves customers using the following priority order:

1. customer.id — Redo customer ObjectId (highest priority)
2. customer.email — customer email address
3. customer.phoneNumber — customer phone number

At least one identifier must be provided. If no matching customer is found, one will be created automatically. If customer.id is provided but not found, the API falls back to email/phone rather than returning 404.

Datetime Formatting

All datetime values must be formatted as ISO 8601 (RFC 3339) strings, e.g., 2026-04-02T12:00:00Z. This applies to eventTimestamp, any date-valued properties in data, and any date-valued customFields. Strings matching this format are automatically detected and indexed as dates for segmentation.

Rate Limiting

This endpoint is rate-limited to 100 requests per second per store.

Requires the customer_events_write scope.