---
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
  - `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 (credits are USD-pegged at 100 credits per minor unit, so a 1¢/unit charge debits 100 credits/unit)
      - `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

## Changes

- **2026-07-30** `8578b7536a9f` — 1 info
  - the request property `metadata` became optional
- **2026-07-17** `bbc2ff2bc849` — 3 warning
  - the `customerRef` request property's maxLength was set to `20`
  - the `productRef` request property's maxLength was set to `20`
  - the `purchaseRef` request property's maxLength was set to `20`
- **2026-07-04** `a30b6aef464d` — 5 info
  - the endpoint scheme security `SecretKey` was added to the API
  - the endpoint scheme security `bearer` was removed from the API
  - added the optional property `creditDebit` to the response with the `200` status
  - the response property `reference` became required for the status `200`
  - …1 more
- **2026-04-08** `052cc028fdfa` — 1 breaking, 1 warning
  - added the new required request property `customerRef`
  - removed the request property `customerId`
- **2026-04-07** `d69c95d790d2` — 2 warning, 2 info
  - removed the request property `productReference`
  - removed the request property `purchaseReference`
  - added the new optional request property `productRef`
  - added the new optional request property `purchaseRef`

[Full history](https://skmtc.dev/solvapay/apis/solvapay-rest-api/changes/v1/sdk/usages/post.md)

---

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