The Event object

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)

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.

Track event

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"
  }'

string

required

Must be track or identify.

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).

object

Resolves the company for the event. At least one of id, wallet, or email required to associate usage. Unknown companies are upserted.

object

Resolves the user for the event. At least one of id, clerk_user_id, wallet, or email required.

object

Arbitrary key-value properties attached to the event.

string

Unique key for the logical event. Prevents double-counting on retries. Maximum 128 characters.

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

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

{ "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

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",
});

Entitlements & flags API — the underlying enforcement engine
Feature flags — how track events map to feature checks
React SDK hooks — useTrack and useConsumeEntitlement

Get started

Credentials

Companies

Users

Events

Access control

Features

Subscriptions

Checkout sessions

Payment links

Autonomous agents

Escrow

Mandates

Coupons

zkTLS proofs

Public specs

Ingest an event

Auth

Track event

Entitlement enforcement on track

Identify event

Success response

List events

Event object

Using events with SDKs

​Ingest an event

​Auth

​Track event

​Entitlement enforcement on track

​Identify event

​Success response

​List events

​Event object

​Using events with SDKs

​Related

Ingest an event

Auth

Track event

Entitlement enforcement on track

Identify event

Success response

List events

Event object

Using events with SDKs

Related