---
title: "Record a usage event"
method: POST
path: "/v1/sdk/usages"
tags: ["Usage"]
---

# Record a usage event

`POST /v1/sdk/usages`

Records a usage event into the Usage timeseries collection.

## Request body

- CreateUsageRequest
  - `actionType` 'transaction' | 'api_call' | 'hour' | 'email' | 'storage' | 'custom'
  - `customerRef` string, required
  - `description` string
  - `duration` number
  - `errorMessage` string
  - `idempotencyKey` string
  - `metadata` object, required
  - `outcome` 'success' | 'paywall' | 'fail'
  - `productRef` string
  - `purchaseRef` string
  - `timestamp` string, date-time, required
  - `units` integer

## Response `200`

Usage recorded successfully

- UsageRecordResponse
  - `creditDebit` union
    - CreditDebitSuccessResponse
      - `amount` number, required — Credits debited for this usage event
      - `autoRecharge` AutoRechargeTriggeredResponse
        - `triggered` boolean, required — Whether the server initiated an auto-recharge charge after this debit (TOPUP credit lands via webhook)
      - `debited` number, required
      - `unitsRemaining` number, required — Estimated remaining units after debit
    - CreditDebitSkippedResponse
      - `debited` number, required
      - `reason` 'duplicate' | 'no_product_ref' | 'customer_not_found' | 'no_active_purchase' | 'plan_not_credit_based', required — Reason no credit debit was recorded
  - `reference` string, required
  - `success` boolean, required

## Other responses

- `400` — Validation failed

---

[API](https://skmtc.net/solvapay/apis/solvapay-rest-api.md) · [All operations](https://skmtc.net/solvapay/apis/solvapay-rest-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/solvapay/solvapay-rest-api/versions/bbc2ff2bc849/schema)