--- title: "Bulk create custom events" method: POST path: "/stores/{storeId}/events/bulk" tags: ["Custom Events"] --- # Bulk create custom events `POST /stores/{storeId}/events/bulk` Create multiple custom events in a single request. Accepts up to 100 events per request. Each event is validated independently. The response includes per-event results, allowing partial failures — some events may be accepted while others are rejected due to validation errors. ## Identity Resolution Each event resolves customers independently using the same priority order as the single-event endpoint: 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 per event. If no matching customer is found, one will be created automatically. ## 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 - BulkCustomEventRequestSchema — Request body for sending multiple custom events in a single request. - `events` CustomEventRequestSchema[], required — Array of custom events to create. - `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` Bulk request accepted and queued for processing. No response body is returned. ## Other responses - `400` — Invalid request body (e.g., events array missing or exceeds 100 items) - `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)