Meter Events

Ingest usage data for metering, entitlements, and analytics without automatically triggering billing

Meter events let you record what your customers consume — tokens, API calls, storage, compute — without triggering a payment or requiring a billing plan. Once ingested, this data powers metered entitlements, usage analytics, and internal rate limiting.

Unlike usage events, meter events are fire-and-forget: the API always responds 202 Accepted and never rejects a well-formed event. There are no billing side-effects, no subscription requirements, and no timing constraints.

How it works

When you send an event to POST /v0/events, Paygentic:

1. Validates that the type field matches a billable metric configured in your organization
2. Returns 202 Accepted immediately
3. Paygentic deduplicates and stores the event

The stored events are then available for aggregation — either to enforce metered entitlement quotas or for your own analytics.

Before you begin

• At least one billable metric with an eventType configured
• An API key with events:create permission

Setting up a billable metric for metering

A billable metric becomes a meter definition by configuring three fields:

Field	Required	Description
eventType	Yes	The type value your events will carry. Events with a non-matching type are rejected with 422.
valueProperty	No	JSONPath expression into the event data payload. Extracts the numeric value to aggregate (e.g., $.tokens). Required for aggregations other than count.
groupBy	No	A map of dimension names to JSONPath expressions. Allows slicing usage by properties like model or region.
aggregation	Yes	How to combine values: sum, count, avg, min, max, unique_count, or latest.

One billable metric = one measurement. To track multiple values from the same event (e.g., input tokens and output tokens separately), create multiple billable metrics pointing to the same eventType with different valueProperty paths.

Example: billable metric for AI inference tokens

{
  "name": "AI Tokens",
  "unit": "tokens",
  "eventType": "ai.inference",
  "valueProperty": "$.tokens",
  "aggregation": "SUM",
  "groupBy": {
    "model": "$.model"
  }
}

Sending events

Send a POST request to /v0/events for each unit of consumption:

cURL

curl -X POST "https://api.paygentic.io/v0/events" \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "ai.inference",
    "source": "https://api.myapp.com",
    "subject": "cus_abc123",
    "data": {
      "tokens": 1500,
      "model": "gpt-4o",
      "region": "us-east-1"
    },
    "idempotencyKey": "req_xyz789",
    "externalId": "txn_456"
  }'

const response = await fetch('https://api.paygentic.io/v0/events', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer sk_live_YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    type: 'ai.inference',
    source: 'https://api.myapp.com',
    subject: 'cus_abc123',
    data: {
      tokens: 1500,
      model: 'gpt-4o',
      region: 'us-east-1',
    },
    idempotencyKey: 'req_xyz789',
    externalId: 'txn_456',
  }),
});
// Always 202 for a valid, well-formed event

import requests

response = requests.post(
    "https://api.paygentic.io/v0/events",
    headers={"Authorization": "Bearer sk_live_YOUR_API_KEY"},
    json={
        "type": "ai.inference",
        "source": "https://api.myapp.com",
        "subject": "cus_abc123",
        "data": {
            "tokens": 1500,
            "model": "gpt-4o",
            "region": "us-east-1",
        },
        "idempotencyKey": "req_xyz789",
        "externalId": "txn_456",
    },
)
# response.status_code == 202

Event fields

Field	Required	Description
type	Yes	Must match an eventType on one of your billable metrics.
source	Yes	URI identifying the system sending the event (e.g., https://api.myapp.com).
subject	Unless externalSubject is set	The customer or entity the event relates to — typically a customerId. Prefer this when you know the Paygentic customer ID.
externalSubject	Unless subject is set	Your own customer identifier, matched against the customer’s externalId. Fallback for when you don’t know the Paygentic customer ID — see Reporting with your own customer ID. Alphanumeric characters, hyphens, and underscores only; max 255 characters.
data	Yes	Arbitrary JSON object containing the metering payload.
idempotencyKey	No	Your own deduplication key. If omitted, a unique key is generated.
externalId	No	Your own identifier for cross-referencing the event with external systems. Alphanumeric characters, hyphens, and underscores only; max 255 characters. Searchable when listing events.
namespace	No	Organization ID. Defaults to your authenticated organization.
timestamp	No	ISO 8601 event timestamp. Defaults to server receipt time.

Response

{
  "id": "evt_abc123",
  "object": "event",
  "type": "ai.inference",
  "source": "https://api.myapp.com",
  "subject": "cus_abc123",
  "namespace": "org_xyz",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "idempotencyKey": "req_xyz789",
  "externalId": "txn_456"
}

Reporting with your own customer ID (externalSubject)

If you don’t know — or don’t yet have — a Paygentic customer ID, report events with externalSubject set to your own customer identifier instead of subject:

{
  "type": "ai.inference",
  "source": "https://api.myapp.com",
  "externalSubject": "acct-4521",
  "data": { "tokens": 1500 }
}

Paygentic resolves externalSubject against the externalId field on your customers (scoped to your organization):

• Customer already exists with externalId: "acct-4521" — the event is linked to that customer at ingestion, exactly as if you had sent its subject.
• Customer doesn’t exist yet — the event is accepted and stored unlinked. When you later create a customer with externalId: "acct-4521" (or set that externalId on an existing customer), the stored events are linked to it retroactively. Linked events are invoiced normally as long as their timestamps fall within a billing period of the customer’s subscription.

This means you can start metering before customer records exist: send events with externalSubject, then create the customer and subscription — usage reported before the customer existed is picked up at invoicing.

Notes and caveats:

• subject is preferred when you know the Paygentic customer ID; externalSubject is a fallback.
• Resolution by externalSubject is eventually consistent. After a customer’s externalId is removed or reassigned, events may still resolve to the previous customer for up to one hour. Use subject when immediate, unambiguous attribution is required.
• Once an event is linked to a subject, it is never re-linked. Changing a customer’s externalId only affects unlinked and future events, subject to the one-hour grace period above.
• You can send both subject and externalSubject; subject wins and they must refer to the same customer. Sending a subject of one customer with another customer’s externalSubject will misattribute usage.
• Retroactive linking completes within seconds of the customer being created/updated. In rare cases an event that was in flight at exactly that moment can remain unlinked; re-saving the customer’s externalId re-triggers linking.

Multi-dimensional metering

The data payload can carry as many fields as you need. Use groupBy on your billable metric to slice usage by dimension.

Example: track tokens per model

Billable metric configuration:

{
  "eventType": "ai.inference",
  "valueProperty": "$.tokens",
  "aggregation": "sum",
  "groupBy": {
    "model": "$.model",
    "region": "$.region"
  }
}

Every event with type: "ai.inference" contributes to the aggregate, and usage can be broken down by model or region when checking entitlement balances or querying analytics.

The groupBy paths use JSONPath notation. $.model extracts the top-level model field from the event data object. Nested fields use dot notation: $.request.metadata.tier.

Multiple metrics from one event stream

Multiple billable metrics can read from the same eventType. This lets you track different aspects of the same operation without sending separate events.

Example: track input and output tokens separately from one AI inference event

Event payload:

{
  "type": "ai.inference",
  "subject": "cus_abc123",
  "source": "https://api.myapp.com",
  "data": {
    "inputTokens": 800,
    "outputTokens": 700,
    "model": "gpt-4o"
  }
}

Billable metric 1 — Input Tokens:

{
  "name": "Input Tokens",
  "eventType": "ai.inference",
  "valueProperty": "$.inputTokens",
  "aggregation": "sum"
}

Billable metric 2 — Output Tokens:

{
  "name": "Output Tokens",
  "eventType": "ai.inference",
  "valueProperty": "$.outputTokens",
  "aggregation": "sum"
}

One event ingested, two metrics updated. Both can have independent pricing, quotas, and entitlement limits.

Standalone metering (no plan required)

Meter events do not require a billing plan, a subscription, or even a customer account. The only requirement is a billable metric with a matching eventType.

This makes meter events suitable for:

• Internal analytics — Track usage across your infrastructure before you’ve set up billing
• Rate limiting — Enforce per-customer limits without any billing integration
• Capacity planning — Instrument your system to understand consumption patterns
• Usage dashboards — Give customers visibility into their own usage

You can add billing later by creating a plan with a price linked to your billable metric — the same events you’re already ingesting will feed into billing automatically.

Using meters with metered entitlements

Meter events are the data source for metered entitlements. When a customer has a metered entitlement, the grant engine reads their aggregated meter data to determine how much quota they have remaining.

To check whether a customer has remaining quota, use GET /v1/entitlements/{entitlementId}. For metered entitlements, this endpoint returns balance, usage, and period data inline. The entitlementId comes from the list entitlements response.

See Features and Entitlements — Metered Features for code examples, the full balance response schema, and hard vs soft limit configuration.

Idempotency

Use idempotencyKey to prevent duplicate events when retrying failed requests:

• If you send two events with the same idempotencyKey, only the first is recorded
• The deduplication window is 24 hours
• If you omit idempotencyKey, the API generates a unique key for you (retries will create duplicate events)

Best practice: Generate idempotency keys deterministically from your internal identifiers:

const idempotencyKey = `${requestId}-${customerId}-${eventType}`;

Error handling

Status	Condition
202 Accepted	Event accepted and queued for processing
400 Bad Request	Malformed request (e.g., invalid timestamp format, externalId/externalSubject with disallowed characters, or neither subject nor externalSubject provided)
422 Unprocessable Entity	The type field does not match any billable metric in your organization
401 Unauthorized	Missing or invalid API key
403 Forbidden	API key lacks events:create permission for the target namespace

A 422 response means you need to create a billable metric with the matching eventType before sending events of that type. Events with an unrecognized type are not queued.

Next steps

• Billable Metrics — Configure eventType, valueProperty, groupBy, and aggregation
• Features and Entitlements — Enforce usage quotas with metered entitlements
• Usage Events — Billing-first event model that triggers immediate payment