Usage events

Record metered customer usage, debit credits, grant credits, and read balances from your application.

What are usage events?

A usage event is one recorded data point against a meter — an API request, token spend, or document generation. The HTTP path stays POST /v1/sdk/meter-events. See Plans and billing glossary for the meter noun and credit peg.

Record usage

import { createSolvaPay } from '@solvapay/server'

const solvaPay = createSolvaPay({
  apiKey: process.env.SOLVAPAY_SECRET_KEY,
})

const result = await solvaPay.trackUsage({
  customerRef: 'cus_3C4D5E6F',
  productRef: 'prd_api',
  actionType: 'api_call',
  units: 1,
  outcome: 'success',
  idempotencyKey: 'request_123',
})

if (result.creditDebit?.debited) {
  console.log(`Debited ${result.creditDebit.amount} credits`)
}

Event fields

Field	Type	Required	Description
customerRef	string	Yes	Customer reference this event belongs to
productRef	string	No	Product scope for the event
actionType	string	No	Usage category, such as api_call or custom
units	number	No	Quantity consumed. Defaults to 1
outcome	string	No	success, paywall, or fail. Credit debit only applies to successful usage
idempotencyKey	string	No	Retry-safe key for duplicate usage submissions

Common types

• api_call
• transaction
• email
• storage
• custom

Record usage in bulk

trackUsageBulk submits many events in one request — useful for flushing a buffered queue or backfilling. The batch is validated first, then each event is inserted individually:

const result = await solvaPay.trackUsageBulk({
  events: [
    { customerRef: 'cus_3C4D5E6F', productRef: 'prd_api', actionType: 'api_call', units: 3 },
    { customerRef: 'cus_9A8B7C6D', productRef: 'prd_api', actionType: 'api_call', units: 1 },
  ],
})

console.log(`Inserted ${result.inserted} events`)
for (const entry of result.results) {
  if (entry.creditDebit?.debited) {
    console.log(`${entry.reference}: debited ${entry.creditDebit.amount} credits`)
  }
}

The response is { success, inserted, results }, where each results entry carries the event reference and its per-event creditDebit outcome (same shape as the single-event response).

Credit debit results

When the customer is on a credit-based (usage-based) plan, trackUsage debits credits and reports what happened in creditDebit:

// Debited
{
  debited: true,
  amount: 10,            // credits debited
  unitsRemaining: 240,   // units the remaining balance still covers
  autoRecharge?: { triggered: boolean },
}

// Skipped
{
  debited: false,
  reason: 'duplicate' | 'no_product_ref' | 'customer_not_found'
        | 'no_active_purchase' | 'plan_not_credit_based',
}

autoRecharge.triggered: true means an off-session recharge was initiated because the balance crossed the customer’s auto-recharge threshold — the credits arrive when that charge succeeds, not in this response. See the Auto-recharge guide.

Grant credits

Assign credits to a customer without collecting payment — sign-up bonuses, goodwill credits, or enterprise allotments. Grants are idempotent when you supply an idempotencyKey, so retries are safe:

const grant = await solvaPay.assignCredits({
  customerRef: 'cus_3C4D5E6F',
  credits: 500,
  reason: 'Sign-up bonus',
  idempotencyKey: 'signup-bonus-user_123',
})

console.log(`New balance: ${grant.balance}`)

The response includes { success, customerRef, credits, balance, reason }. Each grant emits a customer.credit.granted webhook. Credits can also be granted from the customer detail page in the SolvaPay Console.

Read a customer’s balance

const balance = await solvaPay.getCustomerBalance({ customerRef: 'cus_3C4D5E6F' })

console.log(balance.credits)          // credit units
console.log(balance.displayCurrency)  // for presentation

The response also carries creditsPerMinorUnit and a display exchange rate for rendering the balance in the provider’s display currency. Credit balances are USD-normalized internally; the display fields are for presentation only.

Relationship to meters

Use both when needed:

• trackUsage() / trackUsageBulk() for customer-level usage and credit debit
• Meter events for named meter ingestion and aggregation

Next steps

• Core concepts
• Auto-recharge — automatic balance refills when credits run low
• Plans and billing glossary
• Webhook handling — customer.credit.* and usage.* events