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

# The Event object

> Data model and reference for customer usage events and identity signals driving usage metering and credit consumption.

The Events API ingests two event types from your product: `track` events (usage and behavior, with optional entitlement enforcement) and `identify` events (company/user upserts). It is the same API the React SDK's `useTrack` and the Node SDK's `track()`/`identify()` methods call.

## Ingest an event

`POST /api/v1/events` accepts a single event object with an `event_type` of `track` or `identify`.

### Auth

* `Authorization: Bearer api_…` (legacy key) — for server-side ingestion
* Embed access token — for browser-side ingestion from an identified session
* Dashboard session cookie — for listing (see below)

<Note>
  The event ingestion endpoint does not currently accept `sk_…`/`rk_…` prefixes. Use a legacy `api_…` key or an embed access token. See the [endpoint auth matrix](/api/authentication#which-key-works-where--the-endpoint-auth-matrix).
</Note>

### Track event

```bash theme={null}
curl -X POST https://api.arcenpay.com/api/v1/events \
  -H "Authorization: Bearer api_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "event_type": "track",
    "name": "scan_completed",
    "company": { "id": "company_123", "wallet": "0xabc..." },
    "user": { "id": "user_123" },
    "traits": { "pages": 3, "model": "gpt-4o" },
    "idempotencyKey": "scan-2026-09-17-001"
  }'
```

<ParamField body="event_type" type="string" required>
  Must be `track` or `identify`.
</ParamField>

<ParamField body="name" type="string" required>
  Event name. If it matches a configured feature flag's `featureKey` or `eventKey`, ArcenPay enforces the flag's entitlement rules against the company (see below).
</ParamField>

<ParamField body="company" type="object">
  Resolves the company for the event. At least one of `id`, `wallet`, or `email` required to associate usage. Unknown companies are upserted.
</ParamField>

<ParamField body="user" type="object">
  Resolves the user for the event. At least one of `id`, `clerk_user_id`, `wallet`, or `email` required.
</ParamField>

<ParamField body="traits" type="object">
  Arbitrary key-value properties attached to the event.
</ParamField>

<ParamField body="idempotencyKey" type="string">
  Unique key for the logical event. Prevents double-counting on retries. Maximum 128 characters.
</ParamField>

#### Entitlement enforcement on track

When the event `name` matches a feature flag's `featureKey` or `eventKey`, ArcenPay runs the resolved entitlement check before recording the event:

* **Metered features** (credit-backed or with an allocation) consume one unit via `consumeMeteredEntitlement`. If the company is out of quota or credits, the request returns `402` ("Insufficient credits") or `429` ("Limit reached").
* **Boolean features** block the event with `429` if the feature is not enabled.

This turns `track` into a **billable usage call**: your server can fire usage events and ArcenPay meters them against the customer's plan.

### Identify event

```bash theme={null}
curl -X POST https://api.arcenpay.com/api/v1/events \
  -H "Authorization: Bearer api_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "event_type": "identify",
    "company": { "id": "company_123", "name": "Acme Corp", "wallet": "0xabc..." },
    "user": { "id": "user_123", "name": "Jane" },
    "traits": { "plan": "pro" }
  }'
```

An `identify` event upserts the company and user records (merging `traits`) without recording a track event or consuming anything.

### Success response

```json theme={null}
{ "ok": true, "data": { "companyId": "cm_abc123", "userId": "us_abc123" } }
```

## List events

`GET /api/v1/events` lists ingested track events for the active dashboard environment. Auth: dashboard session with `catalog:read` role.

| Query       | Type   | Description                           |
| ----------- | ------ | ------------------------------------- |
| `limit`     | number | Results per page, max 200, default 50 |
| `eventType` | string | Filter by event type                  |
| `companyId` | string | Filter events for a company           |

## Event object

| Field       | Type              | Description                 |
| ----------- | ----------------- | --------------------------- |
| `id`        | string            | Internal event ID           |
| `eventType` | string            | `track` or `identify`       |
| `name`      | string            | Event name                  |
| `companyId` | string \| null    | Associated company          |
| `userId`    | string \| null    | Associated user             |
| `traits`    | object            | Event properties            |
| `sentAt`    | string (ISO 8601) | When the event was received |

## Using events with SDKs

```typescript theme={null}
import { ArcenClient } from "@arcenpay/node";

const client = new ArcenClient({ apiKey: process.env.ARCENPAY_API_KEY });

// Identify (creates session token; subsequent calls use it)
await client.identify({
  company: { id: "company_123" },
  user: { id: "user_123" },
});

// Track a metered usage event
await client.track({
  name: "scan_completed",
  company: { id: "company_123" },
  traits: { pages: 3 },
  idempotencyKey: "scan-2026-09-17-001",
});
```

## Related

* [Entitlements & flags API](/api/entitlements-flags) — the underlying enforcement engine
* [Feature flags](/concepts/feature-flags) — how track events map to feature checks
* [React SDK hooks](/sdk/react/hooks) — `useTrack` and `useConsumeEntitlement`