Create or update custom event

Creates a new custom event, or updates an existing one by passing back its id. customEvent accepts either a single event object, or an array of event objects (up to 50) to create/update several in one request.

Custom events let you define client-side behaviors (clicks, scroll depth, page views, etc.) that can be tracked as goals or triggers on experiences.

This is a full PUT replacement — when updating an existing event, the entire event configuration is replaced with the provided data. Any optional fields omitted from the request are reset to their defaults, not preserved from the previous version.

Required Fields (inside each event object)

• type - The kind of custom event (see supported types above)
• name - A name for the custom event
• settings - Type-specific configuration (e.g. CSS selectors for clickEvent, scroll percentages for scrollDepth)
• applyToUrls - Required only for pageView (at least one rule); has no effect and is ignored for productPageView/collectionPageView

Optional Fields (inside each event object)

• id (UUID) - Pass back the id from a previous create/update response to update that event in place instead of creating a new one. Omit to create a new event. Supplying an id that doesn't belong to your organization creates a new event rather than adopting or overwriting it.
• description (string) - Description of the custom event

Important Notes

• customEvent must be either a single event object or an array of up to 50 event objects — not a mix of anything else.
• identifier is server-generated and read-only; it is not guaranteed to stay the same across updates to the same event. Use id as the stable reference for an event, not identifier.
• Returns a 403 if your organization's plan does not include custom events tracking. This applies to both creating a new event and updating an existing one.

Rate Limit: 50 requests per 30s window, refilling 25 tokens every 30s.