> For the complete documentation index, see [llms.txt](https://docs.chord.co/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.chord.co/collect-data/everyone-else/sdk-reference/custom-events.md).

# Custom events

A custom event is any event that isn't in the Chord [tracking plan](/collect-data/tracking-plan.md). That covers events with names the plan doesn't define, and plan events that carry extra properties.

## Sending a custom event

Use `chord.track()`:

```typescript
chord.track('Gift Wrap Selected', {
  wrap_style: 'holiday',
  order_value: 120,
})
```

`chord.track()` doesn't run your formatters or rename properties, so use snake\_case property names. When a tracking plan event fits, use its own method instead, such as `chord.trackProductAdded()`. See [Methods](/collect-data/everyone-else/sdk-reference.md#methods).

## What Chord does with them

Chord doesn't check events against the tracking plan. It never rejects, holds back or strips an event for not matching. Custom events go through the same processing as plan events, and are sent on to your destinations.

An event is only ever dropped for one of these reasons:

* a filter rule on the connection
* the shopper's consent choices
* a function on the connection that drops it
* deduplication
* the destination itself skipping it (see below)

## How destinations handle them

What happens next depends on the destination.

**Most cloud-mode destinations pass custom events through** under their own name. Warehouses get a table named after the event. Webhook, Mixpanel, PostHog, Heap and similar tools receive it as-is. GA4 and Meta Conversions API translate plan events into their own standard events, and send anything else under its own name.

**Some destinations only act on events you map.** Amplitude, Braze, Klaviyo and similar tools treat plan events specially, and handle other events as generic tracks or according to your mapping.

**Browser (device-mode) destinations fall into three groups:**

* **Pass through.** The event goes to the vendor under its own name: Meta Pixel, TikTok Pixel, Pinterest Tag, Insider, Bing Ads, StackAdapt, Dotdigital and Google Tag Manager (pushed to the data layer).
* **Fixed events only.** The vendor only recognizes its own set of conversion events, so Chord skips anything else and logs a warning in the browser console: Snap Pixel, Northbeam, Reddit, Retention.com, Postie, Spotify Ad Analytics, OpenAI Ads and Nosto.
* **Mapped events only.** The destination fires only for events you've mapped in its settings: X (Twitter) Ads and Google Ads.

{% hint style="info" %}
To send custom events to an ad platform, choose one that passes them through, or map the event in the destination's settings.
{% endhint %}

## Practical guidance

* **Sending to a warehouse or a pass-through destination?** The event arrives with its original name and properties.
* **Want a custom event to look like a plan event at a destination?** Reshape it with a property mapping or a function on the connection.
* **Want to keep a custom event away from a destination?** Add a filter rule to the connection, or drop it in a function. Nothing removes it automatically.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.chord.co/collect-data/everyone-else/sdk-reference/custom-events.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.