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

# Record bulk usage events

`POST /v1/sdk/usages/bulk`

Same persistence rules as POST /sdk/usages for each item: validate batch first, then one insert per event.

## Request body

- BulkCreateUsageRequest
  - `events` object[], required
    - `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`

Bulk usage events processed

- BulkUsageResponse
  - `inserted` number, required — Number of usage events inserted
  - `results` BulkUsageResultResponse[], required
    - `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)