Custom Events

Custom events are event names that YOU define for your workspace, such as quote_requested, size_guide_opened or show_hide_filter. They cover the actions your funnel has that the standard events do not. A custom event flows through the whole AxiTrace pipeline: ingestion, storage, the visitor profile timeline and, if you switch it on, forwarding to your connected ad platforms.

On This Page

1. Where to find Custom Events
2. Availability and plan limits
3. Quick start: a working event in five minutes
4. The definition form, field by field
5. Event key rules and reserved names
6. Kinds: engagement and conversion
7. Throttle modes
8. Properties
9. Sending from the website (JavaScript SDK)
10. No-code triggers
11. The selector tester
12. Sending from your server (HTTP API)
13. Sending from PHP (PHP SDK)
14. Forwarding to ad platforms
15. Checking that it works
16. Editing, disabling and deleting
17. How fast changes take effect
18. Consent and privacy
19. Limits at a glance
20. Error messages
21. Known limitations
22. Troubleshooting

Where to Find Custom Events

Custom events are configured per workspace, in the Custom events module:

1. Sign in at axitrace.com/admin and open your workspace.
2. Click Custom events in the sidebar, in the Data group.
3. The same Custom Events card also appears in Workspace settings → Data collection.

The card shows:

• how many custom events are active and how many your plan allows (for example "2 of 5 active");
• a table of your definitions with their kind, status, the number of events received in the last 7 days;
• the New custom event button;
• the Recently rejected names list: names your site sent in the last 7 days that are not defined, each with an Add as custom event button;
• a link back to this guide.

The full list, including deleted definitions, is at /admin/workspaces/<workspace-id>/custom-events. The card links to it.

You can also let an AI assistant set custom events up for you, for example by asking Claude "Track clicks on the size guide button as a custom event": see Connect Claude, ChatGPT and Cursor. Scripts can do the same through the REST API v1. Both follow the rules on this page and need a permission you grant separately.

Availability and Plan Limits

The plan limit counts ACTIVE definitions. Disabled and deleted definitions do not count, so you can disable one event to make room for another.

Custom event activity is shown as a technical diagnostic. Your plan allowance is measured in visits: multiple custom events in the same session do not create extra billable visits. Review unusually frequent events when tuning triggers and throttles.

Quick Start: a Working Event in Five Minutes

Example: count how often visitors open and close the product filters on a catalog page. The button in the page looks like this:

<button id="toggleFilters" type="button">
    <span id="filterToggleText">Hide Filters</span>
</button>

1. Check the SDK. The AxiTrace JavaScript SDK must already be installed on the site (see JavaScript SDK). No code change is needed for this example.
2. Open the module. Workspace, Custom events in the sidebar, then New custom event.
3. Fill in the details.
   • Event key: show_hide_filter
   • Display name: Show/Hide filters
   • Kind: Engagement (no value)
   • Throttle: Unlimited (every click counts)
4. Add a trigger. In No-code triggers click Add trigger, choose Click and enter the CSS selector #toggleFilters. Use the button, not the inner span: a click trigger matches the element you name AND everything inside it.
5. Leave destinations off and click Create custom event.
6. Test without sending. Open your page with ?axitrace_test=1 added to the URL. The selector tester shows click: #toggleFilters with a match count of 1, and hovering that row outlines the button. Click the button: the "Would fire" log shows custom show_hide_filter (trigger). Nothing is sent from that tab.
7. Test for real. Open the page in a NEW browser session (a private window is easiest, because the website SDK picks up new definitions when a session starts) and click the button.
8. Find the event. Open the Visitors tab, open your own visitor profile and look at the timeline: the event appears with an Engagement badge and the display name Show/Hide filters. The 7-day count on the card grows too.

The Definition Form, Field by Field

Event details

Conversion fallback

Two optional fields for conversion events: Value and Currency (a 3-letter ISO 4217 code such as USD or EUR). They are used ONLY when an event arrives without its own value or currency. Typical use: a "demo booked" conversion that is always worth the same amount, so your code or a trigger never has to send a value.

Declared properties

Up to 10 rows. Each row has a Property name (same rules as the event key), a Type (String, Number or Boolean) and a Label. Declared properties are the ONLY properties forwarded to ad platforms. See Properties.

No-code triggers

Up to 5 rows. Each row has Fires on (Click, Hover or Visible), a CSS selector (up to 300 characters, validated when you save), Hover delay (ms) and Visible for (ms). Under each trigger, Send a property can fill one declared property from the matched element. See No-code triggers.

Destinations

One block per ad platform. Every destination is OFF until you switch it on, and a platform that is not connected in Connections shows a Connect button instead of a switch. See Forwarding to ad platforms.

The side panel of the form shows a ready-to-copy code snippet for the event and, when your workspace has a verified domain, a link that opens your site in the selector tester.

Event Key Rules and Reserved Names

An event key must:

• start with a lowercase letter;
• contain only lowercase letters a-z, digits 0-9 and underscores _;
• be 1 to 40 characters long.

^[a-z][a-z0-9_]{0,39}$

Reserved names

You cannot use a key that AxiTrace or GA4 already uses:

• Reserved prefixes: ga_, google_, firebase_, axi_, vt_ and a leading underscore.
• AxiTrace standard events and their aliases, for example page_view, product_view, view_item, add_to_cart, begin_checkout, add_payment_info, purchase, transaction, form_submit, lead, subscribe, sign_up, start_trial, search, identify, engagement and error. For these actions use the standard events, which already map to every platform.
• GA4 reserved and automatically collected names, for example session_start, first_visit, user_engagement, screen_view, login, share, generate_lead, refund, view_cart, view_item_list, select_item, remove_from_cart and add_shipping_info.

The form tells you when a key is reserved, so you do not need to memorise the list.

Kinds: Engagement and Conversion

Throttle Modes

The throttle stops a single visitor from sending the same event too often, for example when a visitor hovers over the same element again and again.

A throttled call in the browser is dropped silently. A throttled HTTP API request is answered 202 with {"status": "throttled"}.

Properties

Properties are extra details sent with an event, for example the name of the menu a visitor opened. There are two layers:

1. What you may SEND. Up to 30 properties per event. Names are 1 to 40 characters of letters, digits and underscores. Values must be a string, a number, a boolean or null. Strings are limited to 500 characters. Objects and arrays are not allowed.
2. What is FORWARDED. Only the properties you declared on the definition (up to 10) are sent to ad platforms, converted to the declared type: a Number property is sent as a number, a Boolean as true or false, a String as text. Undeclared properties are stored with the event but never leave AxiTrace.

The conversion never guesses. A Number property receives the number when the value reads as one, including the numeric text "34" a trigger extracts from an attribute; anything else is forwarded as 0, so a Number property holding a price range such as "2000-5000" reaches every platform as zero. Use a String property for a value that is not a plain number, and check the type when a platform reports zeros.

Some names are reserved for the event itself and are never treated as properties: value, currency, transaction_id, trigger_id, source, url and referrer. Pass value, currency and transaction id through the dedicated options described below.

Sending From the Website (JavaScript SDK)

With the JavaScript SDK installed, one call sends a custom event. The signature is:

Axitrace._instance.track(eventKey, properties, options);

Engagement example

document.querySelector('#size-guide').addEventListener('click', function () {
    Axitrace._instance.track('size_guide_opened', {
        product_sku: 'CHAIR-042',
        placement: 'product_page'
    });
});

Conversion example

Axitrace._instance.track('quote_requested', { menu_name: 'Salad' }, {
    value: 149.50,
    currency: 'PLN',
    transaction_id: 'quote-1001'
});

What the SDK does with the call

• Defined and active key: applies the throttle, cleans the properties, attaches the conversion fields, fires the browser pixel bridge (see Meta and TikTok) and sends the event.
• Invalid property: a property with an invalid name, a non-scalar value or beyond the 30th is dropped with a console warning; the rest of the event is still sent. Strings longer than 500 characters are cut to 500.
• Unknown key: the SDK logs "<key>" is not a registered custom event in the console and sends the name ONCE per session, so it appears in your Errors tab and in "Recently rejected names" without flooding them.
• Key of a standard event: names such as add_to_cart are routed to the standard event, not to a custom event.
• Before consent: see Consent and privacy.

No-Code Triggers

A trigger fires the event when a visitor interacts with an element that matches a CSS selector. No code on your site is needed beyond the SDK itself. A definition can have up to 5 triggers, so one event can be fired by several buttons.

Choosing a selector

• Prefer an id: #toggleFilters.
• Next best is a dedicated data attribute: button[data-track="quote"]. Adding one to your template is the most robust option, because designers rarely change it.
• Class names work, but break when styling changes: .product-card .btn-quote.
• A selector may match several elements. For example .faq-item summary fires for every FAQ question.
• Elements added to the page later, such as items loaded by infinite scroll or a popup, are picked up automatically.

What triggers never do

• Triggers never read the text of an element and never read form field values, so they cannot capture what a visitor types.
• Triggers are not loaded at all while your workspace has no trigger defined, so they add nothing to your page weight.

The first one is a deliberate boundary, not a missing feature. A trigger is configured in a panel by whoever runs your marketing, and a selector such as .checkout input matches the fields a visitor types into. If triggers could read text and input values, one selector would be enough to push an e-mail address, a phone number or a full name into your ad platforms, with no code review and no way to take it back. Everything else in AxiTrace works to keep personal data out of forwarding, so triggers do not get to be the way around it. Values that a trigger may read are the ones your own template put there on purpose, as attributes.

Sending a property from a trigger

Under each trigger row, Send a property fills ONE declared property from the element the trigger matched. Declare the property first under Declared properties.

Be aware of what this costs. A trigger fires on its own against the page as it already is, but a property has to come from somewhere, and the only places a trigger looks are the link address and data- attributes. Unless those attributes are already in your markup, someone has to add them to your theme: one attribute per element, no script and no tracking code, but still an edit to the template. A trigger with no property needs nothing at all.

Example: one trigger for every "Request a quote" button in a menu list.

<li data-menu-name="Salad">
    <button class="btn-quote">Request a quote</button>
</li>

• Declared property: menu_name, type String.
• Trigger: Click, selector .btn-quote.
• Send a property: A data attribute of a parent, data attribute menu-name, into declared property menu_name.

A click on the button sends menu_name: "Salad". When the attribute is missing or empty, the event is still sent, without that property. Values longer than 500 characters are cut. To send more than one property, call track() from your code.

Throttle and triggers

The throttle applies to trigger fires exactly like it applies to code calls. A Hover or Visible trigger on an element visitors see often should normally use Once per page view or Every N seconds.

The Selector Tester

Add ?axitrace_test=1 to any page of your own site, for example https://www.example.com/catalog?axitrace_test=1. The definition form links to your verified domain with the flag already set.

In that browser tab:

• Nothing is sent to AxiTrace. The tab runs in dry-run mode, so testing never pollutes your data.
• A panel in the top-right corner lists every trigger as type: selector (event: key) with the number of elements it matches on this page. 0 means the selector finds nothing here; invalid means the selector has a syntax error.
• Hovering a row outlines the matching elements in orange.
• Your triggers are armed. The Would fire log shows every event that would have been sent, with its properties, instead of sending it: trigger fires are marked (trigger), and calls from your own code appear too.
• Clicking any element on the page proposes a selector for it: its id first, then a data attribute, then a short class path. Copy it into the trigger row.

The tester uses the definitions your browser session already loaded. After you save a change, open the test URL in a new private window to see it.

Sending From Your Server (HTTP API)

Use the HTTP API when the action happens on your server: a quote stored in your CRM, a subscription renewed by a webhook, a phone call logged by your call-tracking tool. Send requests to https://stat.axitrace.com or to your own tracking subdomain.

Authentication

Use HTTP Basic authentication with your SECRET key as the username and an empty password, exactly like the other server endpoints. See Authentication. Never put the secret key in browser code.

Request body

Example

curl -X POST https://stat.axitrace.com/v1/custom-events \
  -u "sk_live_YOUR_SECRET_KEY:" \
  -H "Content-Type: application/json" \
  -d '{
    "event_name": "quote_requested",
    "event_id": "5f0c7a52-8a4e-4a53-9a3e-0f1d2c3b4a51",
    "properties": { "menu_name": "Salad", "guests": 12 },
    "value": 149.50,
    "currency": "PLN",
    "transaction_id": "quote-1001",
    "client_id": "value-of-the-vt_vid-cookie",
    "session_id": "value-of-the-vt_sid-cookie",
    "ip": "203.0.113.24",
    "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) ..."
  }'

Responses

Sending From PHP (PHP SDK)

The AxiTrace PHP SDK provides the CustomEvent model from version 1.7.0. It sends to /v1/custom-events and generates the event_id for you when you do not pass one.

use AxiTrace\Model\Event\CustomEvent;

$event = new CustomEvent(
    'quote_requested',          // event key
    ['menu_name' => 'Salad'],   // properties
    149.50,                     // value (conversion events only, or null)
    'PLN',                      // currency, or null
    'quote-1001',               // transaction id, or null
    $quote->getUuid()           // event id, or null to generate one
);

// Link the event to the visitor who made the request.
$event->setClientId($_COOKIE['vt_vid'] ?? null);
$event->setSessionId($_COOKIE['vt_sid'] ?? '');

$axiTrace->events()->send($event);

Pass a stable event id, such as the id of the record you just stored, if the same code path can run twice. Then a repeated call within 5 minutes is answered as a duplicate instead of counting twice.

Custom events as leads

A registered custom event can count as a lead: switch it on in Settings > Leads and its occurrences appear in Leads. Choosing it changes only what Leads shows, never how the event is tracked or forwarded. Any custom event can carry the products it is about as a root products array (in the JavaScript SDK, options.products), anchored on the event's currency. Products are optional; an invalid line is dropped and the event is still stored. From PHP SDK 1.12.0, CustomEvent has addProduct() and setProducts():

$event = (new CustomEvent('quote_requested', ['menu_name' => 'Salad'], 149.50, 'PLN', null, $quote->getUuid()))
    ->addProduct(['sku' => 'MENU-SALAD', 'name' => 'Salad menu', 'finalUnitPrice' => 14.95, 'quantity' => 10]);

$axiTrace->events()->send($event);

The full rules for lead products are on the Leads page.

Forwarding to Ad Platforms

General rules for every platform:

• Forwarding is configured per definition, in the Destinations section of the form. The per-event checkboxes of a connection in Connections do not apply to custom events.
• A destination can only be switched on when the platform is connected in Connections.
• Only declared properties are forwarded, converted to their declared type.
• For a conversion event, the conversion fallback value and currency fill in what the event does not carry.
• Names of purchase-type standard events (such as Meta Purchase or GA4 purchase) cannot be used for custom events, so a custom event can never inflate your revenue reporting.
• An engagement event that carries no identity signal at all (no cookie, no click id, no user id) is not forwarded, because the platform could not match it to a person. It is still stored and visible on the profile.
• Every forwarding attempt, successful or not, appears in the connection's integration log.

Checking That It Works

1. Selector tester: every trigger shows a match count above 0 on the pages where it should fire, and interacting with the element adds a line to the "Would fire" log. See The selector tester.
2. Browser console (code calls): no [AxiTrace] warning about an unregistered event or a dropped property. In the Network tab, the request to /track carries "event": "custom" and your key in event_name.
3. Visitor profile: open the Visitors tab and then the visitor. The timeline shows the event with an Engagement or Conversion badge and the display name. Events usually appear within a few seconds; a conversion can take a little longer.
4. The Custom Events card: the 7-day count of the definition grows.
5. Event feed → Errors: rejected events are listed with the reason. See Error messages.
6. Ad platform: the connection's integration log shows each forwarding attempt; the platform's own test or events screen shows the event after its usual delay.

Editing, Disabling and Deleting

How Fast Changes Take Effect

• Server side (HTTP API, PHP SDK and the ingestion of browser events): a NEW definition is accepted within seconds. A disabled or deleted definition stops being accepted within 10 seconds.
• Website SDK: trigger, throttle and pixel bridge changes reach NEW visitor sessions within 5 minutes. A visitor whose session already loaded the configuration keeps it until their next session.

If saving shows the warning "Saved. The ingestion registry could not be updated", your change is stored and the registry repairs itself automatically within 20 minutes. You do not need to save again.

Consent and Privacy

• Custom events follow the same consent rules as every other event of the website SDK (see Cookie consent). While the SDK waits for consent, calls and trigger fires are held in a short in-memory buffer and sent with their original time once consent is granted. If consent is never granted, nothing is sent.
• When the SDK is disabled for a visitor, for example by Do Not Track where your workspace respects it, custom events are not sent.
• Triggers never read element text or form field values.
• Only declared properties leave AxiTrace, and only to destinations you switched on.
• For server calls you are responsible for sending events only for visitors who consented, like for any other server event.

Limits at a Glance

Error Messages

These messages appear in HTTP API responses and in Event feed → Errors.

Known Limitations

• The visitor profile timeline shows the most recent 100 events across ALL event types; custom events share that window.
• There are no per-event trend charts or dashboard widgets for custom events yet. Use the 7-day count on the card and the visitor profiles.
• A trigger configured in the panel fills at most one property. Send more from your code.

Troubleshooting

The event does not appear on the profile

1. Look in Event feed → Errors for unknown custom event or a validation message.
2. Check that the definition is Active on the card.
3. For a trigger or a throttle change, start a NEW browser session: existing sessions keep the configuration they loaded, for up to the session length.
4. Check the throttle: with Once per page view a second click on the same page is not sent.
5. Check consent: while the visitor has not consented, nothing is sent.
6. Make sure you are looking at the right profile: in a private window you are a new visitor.

The tester shows 0 matches

• The element may not exist on this page, or it is rendered later (open the menu or scroll first, then hover the row again).
• Click the element with the tester open to get a proposed selector and compare it with yours.

The tester shows matches but nothing arrives

• The tester tab never sends anything, by design. Test in a normal tab without ?axitrace_test=1, in a new session.

The console says the event is not registered

• The key in your code differs from the defined key, or the definition was created after this session started. Open a new session.

The event is on the profile but not on the ad platform

• Check that the destination is switched on in the definition, not only connected.
• Check the connection's integration log for the platform's answer.
• For Microsoft Advertising, LinkedIn and Google Ads, the goal, rule or conversion action must exist on the platform side.
• For GA4, register the custom dimensions; parameters are invisible in reports until you do.
• An engagement event without any identity signal is not forwarded, see Forwarding.

An HTTP API retry is answered "duplicate"

• That is the deduplication working: an event with this event_id was accepted in the last 5 minutes. Use a new id only for a genuinely new occurrence.