Chargly.ai

Docs / Events & Metering

Events & Metering

Define billable AI actions, assign credit costs, and meter usage consistently across your product.

What is a usage event?

A usage event represents one billable AI action. Examples: chat.reply, image.generate, ai.summary, agent.run. Each event maps to a credit cost.

Event naming

Use stable, descriptive names that align with product behavior. Avoid dynamic or inconsistent names.

chat.replyimage.generatedoc.analyzeagent.runworkflow.step

Credit cost mapping

chat.reply→8 credits
image.generate→40 credits
ai.summary→12 credits
agent.run→25 credits
workflow.step→6 credits

Define costs based on compute, user value, or pricing strategy — but keep the model consistent and easy for users to understand.

Pricing Advisor

Stable event names and clear credit mappings improve Pricing Advisor recommendation quality. The advisor evaluates provider cost, margin targets, and usage to suggest rule changes.

Metering an event

app.js
await chargly.meterEvent({
  customerId: "user_123",
  event: "image.generate",
  credits: 40
})

Chargly records the event, deducts credits from the wallet, and updates the balance in real time.

Best practices

  • Keep event names stable across releases
  • Meter one meaningful user action at a time
  • Avoid exposing token counts directly to users
  • Avoid over-fragmenting simple actions
  • Keep credit pricing understandable

Granularity guidance

Chargly works best when one event maps to one user-visible action.

Good default rule

If a user experiences it as one action, meter it as one event.

Good

image.generate

Avoid

prompt.encode
model.sample
image.postprocess

Events like prompt.encode or model.sample are implementation details, not user actions. Prefer image.generate over splitting into sub-steps.

Next

SDK Reference

Methods, types, and examples.

Pricing Advisor

Decide what AI actions should cost.

Core Concepts

Credits, wallets, usage events.

Stripe Integration

Connect Stripe for credit top-ups.