---
title: "Create custom event"
method: POST
path: "/stores/{storeId}/events"
tags: ["Custom Events"]
---

# Create custom event

`POST /stores/{storeId}/events`

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`](/docs/api-reference/scopes) scope.

## Path parameters

- `storeId` string, required

## Request body

- CustomEventRequestSchema — Custom event to trigger flows with merchant-defined event names and properties.
  - `eventName` string, required — The name of the custom event (e.g., 'User Registered', 'Loyalty Reward Earned').
  - `customer` union, required — Customer identity and profile fields. At least one of `id`, `email`, or `phoneNumber` is required for identity resolution.
    - object
      - `id` string, required — Redo customer ObjectId. Used for identity resolution. Takes priority over email and phoneNumber when provided.
      - `email` string, email — Customer email address. Used for identity resolution.
      - `phoneNumber` string — Customer phone number in E.164 format. Used for identity resolution.
      - `firstName` string — Customer first name. Applied with patch semantics — does not erase existing value if omitted.
      - `lastName` string — Customer last name. Applied with patch semantics — does not erase existing value if omitted.
      - `location` object — Customer location for profile enrichment. All fields are optional.
        - `street1` string — Primary street address.
        - `street2` string — Secondary address line (apartment, suite, etc.).
        - `city` string — City name.
        - `state` string — State or province name.
        - `stateCode` string — State or province abbreviation (e.g., "CA", "NY").
        - `postalCode` string — Postal or ZIP code.
        - `country` string — Country name.
        - `countryCode` string — ISO 3166-1 alpha-2 country code (e.g., "US", "GB").
        - `ianaTimeZoneName` string — IANA time zone identifier (e.g., "America/New_York").
        - `latitude` number — Geographic latitude coordinate.
        - `longitude` number — Geographic longitude coordinate.
      - `customFields` object — Merchant-defined customer attributes as key-value pairs. Values can be strings, numbers, or booleans. Date values should be passed as ISO 8601 strings (e.g., "2026-04-02T12:00:00Z") and are automatically detected and indexed as dates.
    - object
      - `id` string — Redo customer ObjectId. Used for identity resolution. Takes priority over email and phoneNumber when provided.
      - `email` string, email, required — Customer email address. Used for identity resolution.
      - `phoneNumber` string — Customer phone number in E.164 format. Used for identity resolution.
      - `firstName` string — Customer first name. Applied with patch semantics — does not erase existing value if omitted.
      - `lastName` string — Customer last name. Applied with patch semantics — does not erase existing value if omitted.
      - `location` object — Customer location for profile enrichment. All fields are optional.
        - `street1` string — Primary street address.
        - `street2` string — Secondary address line (apartment, suite, etc.).
        - `city` string — City name.
        - `state` string — State or province name.
        - `stateCode` string — State or province abbreviation (e.g., "CA", "NY").
        - `postalCode` string — Postal or ZIP code.
        - `country` string — Country name.
        - `countryCode` string — ISO 3166-1 alpha-2 country code (e.g., "US", "GB").
        - `ianaTimeZoneName` string — IANA time zone identifier (e.g., "America/New_York").
        - `latitude` number — Geographic latitude coordinate.
        - `longitude` number — Geographic longitude coordinate.
      - `customFields` object — Merchant-defined customer attributes as key-value pairs. Values can be strings, numbers, or booleans. Date values should be passed as ISO 8601 strings (e.g., "2026-04-02T12:00:00Z") and are automatically detected and indexed as dates.
    - object
      - `id` string — Redo customer ObjectId. Used for identity resolution. Takes priority over email and phoneNumber when provided.
      - `email` string, email — Customer email address. Used for identity resolution.
      - `phoneNumber` string, required — Customer phone number in E.164 format. Used for identity resolution.
      - `firstName` string — Customer first name. Applied with patch semantics — does not erase existing value if omitted.
      - `lastName` string — Customer last name. Applied with patch semantics — does not erase existing value if omitted.
      - `location` object — Customer location for profile enrichment. All fields are optional.
        - `street1` string — Primary street address.
        - `street2` string — Secondary address line (apartment, suite, etc.).
        - `city` string — City name.
        - `state` string — State or province name.
        - `stateCode` string — State or province abbreviation (e.g., "CA", "NY").
        - `postalCode` string — Postal or ZIP code.
        - `country` string — Country name.
        - `countryCode` string — ISO 3166-1 alpha-2 country code (e.g., "US", "GB").
        - `ianaTimeZoneName` string — IANA time zone identifier (e.g., "America/New_York").
        - `latitude` number — Geographic latitude coordinate.
        - `longitude` number — Geographic longitude coordinate.
      - `customFields` object — Merchant-defined customer attributes as key-value pairs. Values can be strings, numbers, or booleans. Date values should be passed as ISO 8601 strings (e.g., "2026-04-02T12:00:00Z") and are automatically detected and indexed as dates.
  - `data` object — Custom properties for this event (must not exceed 400 properties). The size of the event payload must not exceed 5 MB, and each string cannot be larger than 100 KB. For a full list of data limits on event payloads, see [Limitations](/docs/guides/integrations/custom-events#rate-limits). Note any top-level property that is not an object can be used to create segments. The `$extra` property records any non-segmentable values that can be referenced later, e.g., HTML templates are useful on a segment but are not used to create a segment.
    - `$extra` object — Non-segmentable metadata bucket. Values inside `$extra` are stored on the event but excluded from segmentation indexes. Unlike top-level data properties, values of 0, null, and empty string are NOT stripped inside `$extra`. Use this for large text, debug info, nested objects, arrays, or any data you want to reference in templates but not segment on.
  - `eventTimestamp` string, date-time — ISO 8601 timestamp when the event occurred. Defaults to current time if not provided.
  - `value` number — Monetary or conversion value associated with the event (e.g., purchase amount).
  - `valueCurrency` string — ISO 4217 currency code for the value field (e.g., "USD", "EUR").
  - `uniqueId` string — Merchant-controlled deduplication key (1-255 characters). If provided, subsequent events with the same uniqueId for the same store are silently deduplicated. Use this for safe retries and at-least-once delivery patterns.

## Response `202`

Event accepted and queued for processing. No response body is returned.

## Other responses

- `400` — Invalid request body or missing required customer identifier
- `404` — Store not found
- `429` — Rate limit exceeded
- `default` — Error

---

[API](https://skmtc.dev/redoapp/apis/redo-api.md) · [All operations](https://skmtc.dev/redoapp/apis/redo-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/redoapp/redo-api/revisions/119714540a45/schema)