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

# Customers and events

> Choose stable customer, lead, sale, money, time, and idempotency values.

All Biqli tracking paths use the same event meanings. A good data contract makes reports accurate and retries safe.

## Customers

`customerExternalId` is required for leads and sales. It identifies one customer inside one workspace.

Use a durable value from your system:

```text theme={null}
customer_1842
```

Optional profile fields are `customerName`, `customerEmail`, and `customerAvatar`. These fields improve the Customers interface but do not replace the external ID.

## Leads

A lead is a meaningful action before or outside revenue, such as a signup, trial, qualified demo, or application.

```json theme={null}
{
  "clickId": "qPa4lSpsKj3B",
  "eventId": "signup:customer_1842",
  "eventName": "Signed up",
  "customerExternalId": "customer_1842",
  "eventQuantity": 1
}
```

Use a stable `eventId` for the logical action. Do not add a timestamp or random value when retrying the same lead.

## Sales

A sale is confirmed revenue, such as an order, subscription, or renewal.

```json theme={null}
{
  "clickId": "qPa4lSpsKj3B",
  "customerExternalId": "customer_1842",
  "amount": 1299,
  "currency": "usd",
  "eventName": "Purchase",
  "paymentProcessor": "stripe",
  "invoiceId": "in_1842"
}
```

### Money uses minor units

`amount` is a non-negative integer in the currency's minor unit.

| Displayed amount | Payload                            |
| :--------------- | :--------------------------------- |
| \$12.99 USD      | `{"amount":1299,"currency":"usd"}` |
| EUR 25.00        | `{"amount":2500,"currency":"eur"}` |

Use a lowercase three-letter ISO currency code. Biqli returns `amountUsd` in USD cents when conversion is available.

## Event time

Omit `occurredAt` to use the time Biqli receives the event. For delayed processing, send an ISO 8601 timestamp, for example:

```text theme={null}
2026-09-12T22:35:02Z
```

The public API accepts times up to seven days in the past and five minutes in the future.

## Metadata

Metadata is optional JSON for useful business context, such as a plan or campaign name.

```json theme={null}
{
  "metadata": {
    "plan": "pro",
    "billingInterval": "monthly"
  }
}
```

Do not store passwords, credentials, card details, or unnecessary personal data in metadata. The API limits metadata size, keys, values, and nesting; see the endpoint reference for exact limits.

## Idempotency rules

One logical event must keep one identity:

* Lead: stable `eventId`
* Sale: stable `paymentProcessor` plus `invoiceId`
* REST transport: stable `Idempotency-Key`

Exact retries return the first result and do not repeat realtime or webhook side effects. Changed data with a reused identifier returns `409 idempotency_conflict`.