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

# Events reference

> Profound Pixel events, their fields, and usage

## Standard events

Profound Pixel recognizes the following standard events. Each event accepts a set of optional fields. See [Field sets](#field-sets) for what each set accepts.

| Event                    | When to send it                                                    | Field set         |
| ------------------------ | ------------------------------------------------------------------ | ----------------- |
| `page_viewed`            | A visitor views a page                                             | `contents`        |
| `contents_viewed`        | A visitor views a product, listing, article, or other content unit | `contents`        |
| `items_added`            | A visitor adds items to a cart or selection                        | `contents`        |
| `checkout_started`       | A visitor begins checkout                                          | `contents`        |
| `order_created`          | A purchase completes                                               | `contents`        |
| `subscription_created`   | A paid subscription starts                                         | `plan_enrollment` |
| `trial_started`          | A free trial starts                                                | `plan_enrollment` |
| `lead_created`           | A visitor submits a lead form or requests contact                  | `customer_action` |
| `registration_completed` | A visitor finishes account or event registration                   | `customer_action` |
| `appointment_scheduled`  | A visitor books a meeting, demo, or consultation                   | `customer_action` |

### Field sets

| Field set         | Recognized fields                             |
| ----------------- | --------------------------------------------- |
| `contents`        | `amount`, `currency`, `contents[]`            |
| `plan_enrollment` | `plan_id`, `amount`, `currency`, `contents[]` |
| `customer_action` | `amount`, `currency`                          |

<Accordion title="contents set properties">
  | Property     | Type   | Required                    | Description                                                                                                                                  |
  | ------------ | ------ | --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
  | `amount`     | number | no                          | A whole number in minor units for the given currency (cents for US dollars). For example, \$129.99 = `12999`. Always pair it with `currency` |
  | `currency`   | string | yes, if `amount` is present | An [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency code, such as `USD`                                                           |
  | `contents[]` | array  | no                          | A list of items involved in the event. Each entry takes `id`, `name`, `content_type`, `quantity` (a whole number), `amount`, and `currency`  |

  ```javascript Example event theme={null}
    pfq('track', 'order_created', {
      amount: 12999, currency: 'USD',
      contents: [
        {
          id: 'SKU123',
          name: 'Widget',
          content_type: 'product',
          quantity: 1,
          amount: 12999,
          currency: 'USD'
        }
      ]
    });
  ```
</Accordion>

<Accordion title="plan_enrollment set properties">
  | Property     | Type   | Required                    | Description                                                                                                                                   |
  | ------------ | ------ | --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
  | `plan_id`    | string | no                          | Your internal plan identifier                                                                                                                 |
  | `amount`     | number | no                          | A whole number in minor units for the given currency (cents for US dollars). For example, \$129.99 = `12999`. Always pair it with `currency`. |
  | `currency`   | string | yes, if `amount` is present | An [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency code, such as `USD`                                                            |
  | `contents[]` | array  | no                          | A list of items involved in the event. Each entry takes `id`, `name`, `content_type`, `quantity` (a whole number), `amount`, and `currency`   |

  ```javascript Example event theme={null}
    pfq('track', 'subscription_created', {
      plan_id: 'pro-monthly',
      amount: 4900,
      currency: 'USD',
      contents: [
        {
          id: 'pro-monthly',
          name: 'Pro plan, monthly billing',
          content_type: 'plan',
          quantity: 1,
          amount: 4900,
          currency: 'USD'
        }
      ]
    });
  ```
</Accordion>

<Accordion title="customer_action set properties">
  | Property   | Type   | Required                    | Description                                                                                                                                   |
  | ---------- | ------ | --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
  | `amount`   | number | no                          | A whole number in minor units for the given currency (cents for US dollars). For example, \$129.99 = `12999`. Always pair it with `currency`. |
  | `currency` | string | yes, if `amount` is present | An [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency code, such as `USD`.                                                           |

  ```javascript Example event theme={null}
    pfq('track', 'lead_created', {
      amount: 50000,
      currency: 'USD',
      form: 'contact-sales'
    });
  ```
</Accordion>

### Custom properties

Add your own custom properties (such as `order_id` or `product_id`) alongside the recognized fields. Two limits apply: up to 128 properties per event, and up to 64 KiB per request body. An event that exceeds either limit is rejected with a `400` error.

## Custom events

For anything outside the standard set, send a custom event: call `pfq('trackCustom', …)` with any event name and any properties you choose.

```javascript theme={null}
  pfq('trackCustom', 'requested_demo', { plan: 'enterprise' });
```

Maximum length for event names is 128 characters. The suggested naming convention is lowercase letters, numbers, underscores or dashes, and a name that doesn't match a [standard event](#standard-events) name, so your custom events are easy to tell apart in reporting.

<Warning>
  **Never send customers' personal data in events.** This includes emails, phone numbers, names, government IDs, payment data, street addresses, and special-category data, such as health, financial account details, or biometrics. As a safety measure, Profound drops personal data keys and redacts values that look like personal data.
</Warning>

## Tie events to your own user IDs

If you need to match conversions to records in your own systems, make an `identify` call with your internal identifiers after the customer logs in and before any events are sent:

```javascript theme={null}
  pfq('identify', {
    external_user_id: 'u_123',
    external_account_id: 'acct_456'
  });
```

The following fields are accepted:

| Field                 | Type   | Required |
| --------------------- | ------ | -------- |
| `external_user_id`    | string | no       |
| `external_account_id` | string | no       |

Any other fields are silently ignored.

The pixel holds the IDs in memory until your consent signal allows sending, then attaches them to the events that follow.

<Warning>
  Send internal IDs only, never customers' names, emails, phone numbers, or other identifiers. Personal data in the `identify` fields causes the whole event to be rejected with a `400` error.
</Warning>