> For the complete documentation index, see [llms.txt](https://docs.intelligems.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.intelligems.io/developer-resources/external-api/create-or-update-custom-events.md). # Create Or Update Custom Events The following custom event types are supported by the Intelligems Custom Events API: * `clickEvent` — Fires when a visitor clicks an element matching one or more CSS selectors * `scrollDepth` — Fires when a visitor scrolls past a configured percentage of the page (separate thresholds for mobile and desktop) * `pageView` — Fires when a visitor views a page matching `applyToUrls` * `productPageView` — Fires when a visitor views one of a specific set of product pages * `collectionPageView` — Fires when a visitor views one of a specific set of collection pages * `elementViewed` — Fires when an element matching one or more CSS selectors enters the viewport * `javascriptEvent` — Fires from a custom JavaScript snippet Each type has its own `settings` shape — see the request schema for the full set of fields per type. ## 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. ```json {"openapi":"3.1.0","info":{"title":"Intelligems External API v25-10-beta","version":"v25-10-beta"},"tags":[{"name":"Create or Update Custom Events","description":"The following custom event types are supported by the Intelligems Custom Events API:\n\n- `clickEvent` — Fires when a visitor clicks an element matching one or more CSS selectors\n- `scrollDepth` — Fires when a visitor scrolls past a configured percentage of the page (separate thresholds for mobile and desktop)\n- `pageView` — Fires when a visitor views a page matching `applyToUrls`\n- `productPageView` — Fires when a visitor views one of a specific set of product pages\n- `collectionPageView` — Fires when a visitor views one of a specific set of collection pages\n- `elementViewed` — Fires when an element matching one or more CSS selectors enters the viewport\n- `javascriptEvent` — Fires from a custom JavaScript snippet\n\nEach type has its own `settings` shape — see the request schema for the full set of fields per type."}],"servers":[{"url":"https://api.intelligems.io","description":"Production"}],"security":[{"intelligems_access_token":[]}],"components":{"securitySchemes":{"intelligems_access_token":{"type":"apiKey","in":"header","name":"intelligems-access-token","description":"Intelligems external API access token."}}},"paths":{"/v25-10-beta/custom-events":{"put":{"operationId":"putCustomEvent","summary":"Create or update custom event","tags":["Create or Update Custom Events"],"description":"Creates a new custom event, or updates an existing one by passing back its `id`.\n`customEvent` accepts either a single event object, or an array of event\nobjects (up to 50) to create/update several in one request.\n\nCustom events let you define client-side behaviors (clicks, scroll depth,\npage views, etc.) that can be tracked as goals or triggers on experiences.\n\nThis is a full PUT replacement — when updating an existing event, the entire\nevent configuration is replaced with the provided data. Any optional fields\nomitted from the request are reset to their defaults, not preserved from the\nprevious version.\n\n### Required Fields (inside each event object)\n\n- `type` - The kind of custom event (see supported types above)\n- `name` - A name for the custom event\n- `settings` - Type-specific configuration (e.g. CSS selectors for `clickEvent`, scroll percentages for `scrollDepth`)\n- `applyToUrls` - Required only for `pageView` (at least one rule); has no effect and is ignored for `productPageView`/`collectionPageView`\n\n### Optional Fields (inside each event object)\n\n- `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.\n- `description` (string) - Description of the custom event\n\n### Important Notes\n\n- `customEvent` must be either a single event object or an array of up to 50 event objects — not a mix of anything else.\n- `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`.\n- 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.\n\n**Rate Limit:** 50 requests per 30s window, refilling 25 tokens every 30s.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"customEvent":{"anyOf":[{"oneOf":[{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"name":{"type":"string","description":"Display name shown in the Events Manager and when selecting metrics for an experience."},"description":{"description":"Internal note explaining what this event tracks.","anyOf":[{"type":"string"},{"type":"null"}]},"applyToUrls":{"minItems":1,"type":"array","items":{"type":"object","properties":{"matchBy":{"type":"string","enum":["equals","contains","startsWith","endsWith","doesNotEqual","doesNotContain","doesNotStartWith","doesNotEndWith","isNull","isNotNull","regex"]},"value":{"type":"string"},"error":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["matchBy","value"]},"description":"Optional URL rules restricting which pages this event fires on. Omit to track on all pages. For 'equals', 'doesNotEqual', 'startsWith', and 'doesNotStartWith' match types, `value` must not start with a '/'."},"type":{"type":"string","const":"pageView","description":"Determines which visitor behavior is tracked and which `settings` shape is required. Use pageView for any page visit, productPageView/collectionPageView for specific product or collection pages, clickEvent/elementViewed for CSS-selector-targeted DOM interactions, scrollDepth for scroll-percentage milestones, and javascriptEvent for a custom JS snippet that fires the event."},"settings":{"type":"object","properties":{}}},"required":["name","applyToUrls","type","settings"]},{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"name":{"type":"string","description":"Display name shown in the Events Manager and when selecting metrics for an experience."},"description":{"description":"Internal note explaining what this event tracks.","anyOf":[{"type":"string"},{"type":"null"}]},"type":{"type":"string","const":"productPageView","description":"Determines which visitor behavior is tracked and which `settings` shape is required. Use pageView for any page visit, productPageView/collectionPageView for specific product or collection pages, clickEvent/elementViewed for CSS-selector-targeted DOM interactions, scrollDepth for scroll-percentage milestones, and javascriptEvent for a custom JS snippet that fires the event."},"settings":{"minItems":1,"type":"array","items":{"type":"object","properties":{"productId":{"type":"string","description":"Shopify product ID to track page views for."},"handle":{"type":"string","description":"Shopify product handle to track page views for."}},"required":["productId","handle"]}}},"required":["name","type","settings"]},{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"name":{"type":"string","description":"Display name shown in the Events Manager and when selecting metrics for an experience."},"description":{"description":"Internal note explaining what this event tracks.","anyOf":[{"type":"string"},{"type":"null"}]},"type":{"type":"string","const":"collectionPageView","description":"Determines which visitor behavior is tracked and which `settings` shape is required. Use pageView for any page visit, productPageView/collectionPageView for specific product or collection pages, clickEvent/elementViewed for CSS-selector-targeted DOM interactions, scrollDepth for scroll-percentage milestones, and javascriptEvent for a custom JS snippet that fires the event."},"settings":{"minItems":1,"type":"array","items":{"type":"object","properties":{"handle":{"type":"string","description":"Shopify collection handle to track page views for."}},"required":["handle"]}}},"required":["name","type","settings"]},{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"name":{"type":"string","description":"Display name shown in the Events Manager and when selecting metrics for an experience."},"description":{"description":"Internal note explaining what this event tracks.","anyOf":[{"type":"string"},{"type":"null"}]},"applyToUrls":{"description":"Optional URL rules restricting which pages this event fires on. Omit to track on all pages. For 'equals', 'doesNotEqual', 'startsWith', and 'doesNotStartWith' match types, `value` must not start with a '/'.","anyOf":[{"type":"array","items":{"type":"object","properties":{"matchBy":{"type":"string","enum":["equals","contains","startsWith","endsWith","doesNotEqual","doesNotContain","doesNotStartWith","doesNotEndWith","isNull","isNotNull","regex"]},"value":{"type":"string"},"error":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["matchBy","value"]}},{"type":"null"}]},"type":{"type":"string","const":"clickEvent","description":"Determines which visitor behavior is tracked and which `settings` shape is required. Use pageView for any page visit, productPageView/collectionPageView for specific product or collection pages, clickEvent/elementViewed for CSS-selector-targeted DOM interactions, scrollDepth for scroll-percentage milestones, and javascriptEvent for a custom JS snippet that fires the event."},"settings":{"type":"object","properties":{"selectors":{"minItems":1,"type":"array","items":{"type":"string","minLength":1},"description":"CSS selectors identifying the elements whose clicks should be tracked."}},"required":["selectors"]}},"required":["name","type","settings"]},{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"name":{"type":"string","description":"Display name shown in the Events Manager and when selecting metrics for an experience."},"description":{"description":"Internal note explaining what this event tracks.","anyOf":[{"type":"string"},{"type":"null"}]},"applyToUrls":{"description":"Optional URL rules restricting which pages this event fires on. Omit to track on all pages. For 'equals', 'doesNotEqual', 'startsWith', and 'doesNotStartWith' match types, `value` must not start with a '/'.","anyOf":[{"type":"array","items":{"type":"object","properties":{"matchBy":{"type":"string","enum":["equals","contains","startsWith","endsWith","doesNotEqual","doesNotContain","doesNotStartWith","doesNotEndWith","isNull","isNotNull","regex"]},"value":{"type":"string"},"error":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["matchBy","value"]}},{"type":"null"}]},"type":{"type":"string","const":"elementViewed","description":"Determines which visitor behavior is tracked and which `settings` shape is required. Use pageView for any page visit, productPageView/collectionPageView for specific product or collection pages, clickEvent/elementViewed for CSS-selector-targeted DOM interactions, scrollDepth for scroll-percentage milestones, and javascriptEvent for a custom JS snippet that fires the event."},"settings":{"type":"object","properties":{"selectors":{"minItems":1,"type":"array","items":{"type":"string","minLength":1},"description":"CSS selectors identifying the elements whose visibility in the viewport should be tracked."}},"required":["selectors"]}},"required":["name","type","settings"]},{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"name":{"type":"string","description":"Display name shown in the Events Manager and when selecting metrics for an experience."},"description":{"description":"Internal note explaining what this event tracks.","anyOf":[{"type":"string"},{"type":"null"}]},"applyToUrls":{"description":"Optional URL rules restricting which pages this event fires on. Omit to track on all pages. For 'equals', 'doesNotEqual', 'startsWith', and 'doesNotStartWith' match types, `value` must not start with a '/'.","anyOf":[{"type":"array","items":{"type":"object","properties":{"matchBy":{"type":"string","enum":["equals","contains","startsWith","endsWith","doesNotEqual","doesNotContain","doesNotStartWith","doesNotEndWith","isNull","isNotNull","regex"]},"value":{"type":"string"},"error":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["matchBy","value"]}},{"type":"null"}]},"type":{"type":"string","const":"scrollDepth","description":"Determines which visitor behavior is tracked and which `settings` shape is required. Use pageView for any page visit, productPageView/collectionPageView for specific product or collection pages, clickEvent/elementViewed for CSS-selector-targeted DOM interactions, scrollDepth for scroll-percentage milestones, and javascriptEvent for a custom JS snippet that fires the event."},"settings":{"type":"object","properties":{"mobile":{"type":"object","properties":{"percentage":{"type":"number","minimum":0,"maximum":100,"description":"Percentage of page height scrolled (0-100) that triggers the event."}},"required":["percentage"],"description":"Scroll depth threshold to track on mobile viewports."},"desktop":{"type":"object","properties":{"percentage":{"type":"number","minimum":0,"maximum":100,"description":"Percentage of page height scrolled (0-100) that triggers the event."}},"required":["percentage"],"description":"Scroll depth threshold to track on desktop viewports."}},"required":["mobile","desktop"]}},"required":["name","type","settings"]},{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"name":{"type":"string","description":"Display name shown in the Events Manager and when selecting metrics for an experience."},"description":{"description":"Internal note explaining what this event tracks.","anyOf":[{"type":"string"},{"type":"null"}]},"applyToUrls":{"description":"Optional URL rules restricting which pages this event fires on. Omit to track on all pages. For 'equals', 'doesNotEqual', 'startsWith', and 'doesNotStartWith' match types, `value` must not start with a '/'.","anyOf":[{"type":"array","items":{"type":"object","properties":{"matchBy":{"type":"string","enum":["equals","contains","startsWith","endsWith","doesNotEqual","doesNotContain","doesNotStartWith","doesNotEndWith","isNull","isNotNull","regex"]},"value":{"type":"string"},"error":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["matchBy","value"]}},{"type":"null"}]},"type":{"type":"string","const":"javascriptEvent","description":"Determines which visitor behavior is tracked and which `settings` shape is required. Use pageView for any page visit, productPageView/collectionPageView for specific product or collection pages, clickEvent/elementViewed for CSS-selector-targeted DOM interactions, scrollDepth for scroll-percentage milestones, and javascriptEvent for a custom JS snippet that fires the event."},"settings":{"type":"object","properties":{"code":{"type":"string","description":"JavaScript snippet injected into a