> ## Documentation Index
> Fetch the complete documentation index at: https://docs.instantcampaign.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Events and goals

> Record what contacts do on your website or in your product, mark conversions as goals with a value, and use them in segments, automations and contact profiles.

An **event** is something a contact did, such as `trial_started` or `order_completed`. A **goal** is an event that counts as a conversion, like a purchase, sign-up or booking. A goal can carry a money value.

Events and goals let you:

* see a contact's **Lifetime value**, **Purchases** and **Last goal** on their contact page
* build [segments](/guides/audience-and-campaigns/segments) such as "bought in the last 30 days" or "spent over 1,000 this year"
* start [automations](/guides/audience-and-campaigns/automation-triggers) when an event happens

## Goal types

| Goal type                                     | Value    |
| --------------------------------------------- | -------- |
| `purchase`                                    | Required |
| `subscription`                                | Required |
| `lead`, `signup`, `booking`, `trial`, `other` | Optional |

A negative value records a refund, which lowers the contact's lifetime value.

## Ways to record events

### From your server (recommended for goals)

Send events to the public API with the contact's email address. Each event can include:

| Field               | Notes                                                                                                                                    |
| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `event`             | Required. Lowercase letters, digits, `.` `_` `/` `-` (for example `order_completed`)                                                     |
| `email`             | Links the event to the contact with this address                                                                                         |
| `goalType`          | Makes the event a goal                                                                                                                   |
| `value`, `currency` | Amount and 3-letter currency code (for example `GBP`)                                                                                    |
| `externalId`        | Your own ID, such as an order number. An event with an `externalId` that was already recorded is ignored, so retries never double-count. |
| `properties`        | Any extra data. Properties can be used in automation emails but don't change totals.                                                     |
| `occurredAt`        | When it happened, if not now                                                                                                             |

You can send up to 50 events in one import call. Endpoints, authentication and examples are in the [API reference](/api-reference/introduction). You need an API key with permission to write events.

<Note>
  An event is linked to a contact only if a contact with that email address already exists. Events for unknown addresses are stored without a contact and don't count towards anyone's lifetime value or segments.
</Note>

### From your website

<Steps>
  <Step title="Create a tracking token">
    Go to **Settings → Tracking Tokens**, click **New Token** and create the token. Tracking tokens (`ict_…`) can only send events, so they are safe to put in public pages.
  </Step>

  <Step title="Add the snippet">
    After you create the token, the dialog shows the token and its **Embed Snippet**. Copy them now: the token is shown only once. Paste the snippet into the `<head>` of your site:

    ```html theme={null}
    <script src="https://instantcampaign.ai/track.js" data-site-id="ict_…"></script>
    ```

    Use the exact snippet from the dialog, as the address may differ for your workspace.
  </Step>

  <Step title="Send events">
    ```html theme={null}
    <script>
      ICTrack.identify("jane@example.com");
      ICTrack.event("pricing_viewed", { plan: "pro" });
      ICTrack.goal("signup", { externalId: "user-123" });
    </script>
    ```
  </Step>
</Steps>

The snippet records a `page_view` event on every page load. `ICTrack.goal(type, { value, currency, externalId })` records a goal named `goal.<type>` unless you pass a `name`.

After `ICTrack.identify("jane@example.com")`, every event and goal sent from that page carries Jane's address, so it is credited to her contact: goals add to her lifetime value and goal segments, and events can start event-triggered automations. To credit one goal to someone else, pass `email` in its options: `ICTrack.goal("lead", { email: "bob@example.com" })`. `ICTrack.reset()` forgets the identified visitor, for example when they log out.

<Note>
  The snippet keeps no cookie or local storage, so it forgets the visitor when the page unloads. Call `ICTrack.identify()` on every page where you know who the visitor is, before the events you want credited. Events sent before `identify()`, or on pages without it, are recorded without a contact: they appear under **Analytics → Website Events** only. As with events from your server, the address must belong to an existing contact.
</Note>

Website events are limited to 100 per minute per workspace.

### From Shopify

With the Shopify integration connected, each paid order is recorded as a `purchase` goal named `order.completed` with the order total. When a cancelled order has refunds, an `order.refunded` goal with the negative refunded amount is recorded. Both use the Shopify order ID for de-duplication, so an order is never counted twice.

## Where events and goals appear

| Place                          | What you see                                                                     |
| ------------------------------ | -------------------------------------------------------------------------------- |
| Contact page header            | **Lifetime value**, **Purchases**, **Last goal**                                 |
| Contact **Activity** tab       | Each goal (`Goal: …`) and event (`Event: …`)                                     |
| **Analytics → Website Events** | Events sent by the website snippet, filterable by name                           |
| Segment builder                | **Goals (purchases, sign-ups…)** and **Custom Event** rules                      |
| Automations                    | Event triggers, with `goalType`, `value` and `currency` available to later steps |

## Troubleshooting

<AccordionGroup>
  <Accordion title="A purchase doesn't show on the contact">
    Check that the event was sent with an `email` that matches an existing contact. From the website snippet, that means `ICTrack.identify()` ran on the same page before `ICTrack.goal()`, or the goal was given its own `email`.
  </Accordion>

  <Accordion title="The API rejects an event">
    Common causes: the event name has capitals or spaces; a `purchase` or `subscription` goal has no `value`; a `value` was sent without a `goalType`; the currency isn't a 3-letter code.
  </Accordion>

  <Accordion title="A Custom Event segment rule doesn't match">
    The rule matches the event name exactly, including dots and capitals. Type it as it appears under **Analytics → Website Events** or on the contact's **Activity** tab, for example `order.completed`.
  </Accordion>
</AccordionGroup>
