Every metered feature has an event code. Your application sends events with that code, and Commet aggregates them for billing at the end of the period.

Usage event components

Component	Description	Example
Feature	Event code of a metered feature	`api_calls`, `storage_gb`
Value	Quantity consumed	`1`, `0.5`, `100`
Customer	Who consumed it	`customerId: "user_123"`
Idempotency Key	Prevents duplicate events	`"req_abc123"`
Timestamp	When it happened (defaults to now)	`"2026-01-15T10:00:00Z"`

Setting up event codes

When you create a metered feature in the dashboard, you define its event code. Go to Features, click Create Feature, select Metered, and enter the event code.

Event code conventions

Good Event Codes	Bad Event Codes
`api_calls`	`feature1`
`storage_gb`	`metric`
`emails_sent`	`usage`
`compute_minutes`	`x`

Use snake_case. Be descriptive — this is what appears in code.

Track a single event

await commet.usage.track({
  customerId: "user_123",
  feature: "api_calls",
  value: 1,
})

commet.usage.track(
    customer_id="user_123",
    feature="api_calls",
    value=1,
)

value := 1
client.Usage.Track(ctx, &commet.TrackUsageParams{
    Feature:    "api_calls",
    CustomerID: "user_123",
    Value:      &value,
})

commet.usage().track(
    TrackParams.builder("api_calls")
        .customerId("user_123")
        .value(1)
        .build()
);

$commet->usage->track(
    customerId: 'user_123',
    feature: 'api_calls',
    value: 1,
);

curl -X POST https://commet.co/api/usage/events \
  -H "x-api-key: $COMMET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "feature": "api_calls",
    "customerId": "user_123",
    "value": 1
  }'

Pass either a Commet ID (cus_xxx) or your external ID as customerId.

Parameters

Parameter	Type	Required	Description
`feature`	`string`	Yes	Event code of a metered feature. Only lowercase letters, numbers, and underscores (`a-z0-9_`)
`customerId`	`string`	Yes	Commet customer ID (`cus_xxx`) or your external ID
`value`	`number`	No	Quantity consumed. Must be >= 0. Defaults to `1`
`idempotencyKey`	`string`	No	Prevents duplicate events
`timestamp`	`string`	No	ISO 8601 datetime. Defaults to now
`properties`	`object`	No	Key-value metadata for debugging. Shape: `{ [key: string]: string }`

Idempotency

Prevent duplicate charges by passing an idempotencyKey. Commet rejects events with a key that was already recorded for the same customer.

await commet.usage.track({
  customerId: "user_123",
  feature: "api_calls",
  value: 1,
  idempotencyKey: "req_abc123",
})

commet.usage.track(
    customer_id="user_123",
    feature="api_calls",
    value=1,
    idempotency_key="req_abc123",
)

value := 1
client.Usage.Track(ctx, &commet.TrackUsageParams{
    Feature:        "api_calls",
    CustomerID:     "user_123",
    Value:          &value,
    IdempotencyKey: "req_abc123",
})

commet.usage().track(
    TrackParams.builder("api_calls")
        .customerId("user_123")
        .value(1)
        .idempotencyKey("req_abc123")
        .build()
);

$commet->usage->track(
    customerId: 'user_123',
    feature: 'api_calls',
    value: 1,
    idempotencyKey: 'req_abc123',
);

curl -X POST https://commet.co/api/usage/events \
  -H "x-api-key: $COMMET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "feature": "api_calls",
    "customerId": "user_123",
    "value": 1,
    "idempotencyKey": "req_abc123"
  }'

AI Token Billing — Automatically track and charge for AI model tokens
Configure Features — Create metered features and event codes
Consumption Models — How usage is billed across metered, credits, and balance

Every metered feature has an event code. Your application sends events with that code, and Commet aggregates them for billing at the end of the period.

Usage event components

Component	Description	Example
Feature	Event code of a metered feature	`api_calls`, `storage_gb`
Value	Quantity consumed	`1`, `0.5`, `100`
Customer	Who consumed it	`customerId: "user_123"`
Idempotency Key	Prevents duplicate events	`"req_abc123"`
Timestamp	When it happened (defaults to now)	`"2026-01-15T10:00:00Z"`

Setting up event codes

When you create a metered feature in the dashboard, you define its event code. Go to Features, click Create Feature, select Metered, and enter the event code.

Event code conventions

Good Event Codes	Bad Event Codes
`api_calls`	`feature1`
`storage_gb`	`metric`
`emails_sent`	`usage`
`compute_minutes`	`x`

Use snake_case. Be descriptive — this is what appears in code.

Track a single event

await commet.usage.track({
  customerId: "user_123",
  feature: "api_calls",
  value: 1,
})

commet.usage.track(
    customer_id="user_123",
    feature="api_calls",
    value=1,
)

value := 1
client.Usage.Track(ctx, &commet.TrackUsageParams{
    Feature:    "api_calls",
    CustomerID: "user_123",
    Value:      &value,
})

commet.usage().track(
    TrackParams.builder("api_calls")
        .customerId("user_123")
        .value(1)
        .build()
);

$commet->usage->track(
    customerId: 'user_123',
    feature: 'api_calls',
    value: 1,
);

curl -X POST https://commet.co/api/usage/events \
  -H "x-api-key: $COMMET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "feature": "api_calls",
    "customerId": "user_123",
    "value": 1
  }'

Pass either a Commet ID (cus_xxx) or your external ID as customerId.

Parameters

Parameter	Type	Required	Description
`feature`	`string`	Yes	Event code of a metered feature. Only lowercase letters, numbers, and underscores (`a-z0-9_`)
`customerId`	`string`	Yes	Commet customer ID (`cus_xxx`) or your external ID
`value`	`number`	No	Quantity consumed. Must be >= 0. Defaults to `1`
`idempotencyKey`	`string`	No	Prevents duplicate events
`timestamp`	`string`	No	ISO 8601 datetime. Defaults to now
`properties`	`object`	No	Key-value metadata for debugging. Shape: `{ [key: string]: string }`

Idempotency

Prevent duplicate charges by passing an idempotencyKey. Commet rejects events with a key that was already recorded for the same customer.

await commet.usage.track({
  customerId: "user_123",
  feature: "api_calls",
  value: 1,
  idempotencyKey: "req_abc123",
})

commet.usage.track(
    customer_id="user_123",
    feature="api_calls",
    value=1,
    idempotency_key="req_abc123",
)

value := 1
client.Usage.Track(ctx, &commet.TrackUsageParams{
    Feature:        "api_calls",
    CustomerID:     "user_123",
    Value:          &value,
    IdempotencyKey: "req_abc123",
})

commet.usage().track(
    TrackParams.builder("api_calls")
        .customerId("user_123")
        .value(1)
        .idempotencyKey("req_abc123")
        .build()
);

$commet->usage->track(
    customerId: 'user_123',
    feature: 'api_calls',
    value: 1,
    idempotencyKey: 'req_abc123',
);

curl -X POST https://commet.co/api/usage/events \
  -H "x-api-key: $COMMET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "feature": "api_calls",
    "customerId": "user_123",
    "value": 1,
    "idempotencyKey": "req_abc123"
  }'

AI Token Billing — Automatically track and charge for AI model tokens
Configure Features — Create metered features and event codes
Consumption Models — How usage is billed across metered, credits, and balance

Track Usage

Usage event components

Setting up event codes

Event code conventions

Track a single event

Parameters

Idempotency

On this page

Track Usage

Usage event components

Setting up event codes

Event code conventions

Track a single event

Parameters

Idempotency

On this page