---
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 (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-17** `bbc2ff2bc849` — 3 warning
  - the `events/items/customerRef` request property's maxLength was set to `20`
  - the `events/items/productRef` request property's maxLength was set to `20`
  - the `events/items/purchaseRef` request property's maxLength was set to `20`
- **2026-07-04** `a30b6aef464d` — 3 info
  - the endpoint scheme security `SecretKey` was added to the API
  - the endpoint scheme security `bearer` was removed from the API
  - added the media type `application/json` for the response with the status `200`
- **2026-04-08** `052cc028fdfa` — 1 breaking, 1 warning
  - added the new required request property `events/items/customerRef`
  - removed the request property `events/items/customerId`
- **2026-04-07** `d69c95d790d2` — 2 warning, 2 info
  - removed the request property `events/items/productReference`
  - removed the request property `events/items/purchaseReference`
  - added the new optional request property `events/items/productRef`
  - added the new optional request property `events/items/purchaseRef`
- **2026-04-04** `88abf6f50f11` — 4 breaking, 5 warning, 6 info
  - the request property `events/items/timestamp` became required
  - the `events` request property's minItems was increased to `1`
  - the `events/items/customerId` request property's minLength was increased from `0` to `1`
  - the `events/items/units` request property type changed from `number` to `integer`
  - …11 more

[Full history](https://skmtc.dev/solvapay/apis/solvapay-rest-api/changes/v1/sdk/usages/bulk/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)