---
title: "Record usage (async)"
method: POST
path: "/v1/usage/async"
tags: ["Usage"]
---

# Record usage (async)

`POST /v1/usage/async`

Record a billable usage event and return immediately without waiting for settlement.

> **Requires a secret key (`sk_*`) with at least the `OPERATOR` role.**

The charge will be processed in the background. Subscribe to webhooks
(`charge.succeeded`, `charge.failed`) to get notified of the final status.

Use this endpoint when you need fast response times and can handle
eventual consistency via webhooks.

## Request body

- object
  - `customerId` string — Drip customer ID (cus_*). One of customerId, externalCustomerId, or stripeCustomerId is required.
  - `externalCustomerId` string — Your own database's customer ID. If no Drip customer exists yet for (business, externalCustomerId), one is auto-provisioned as an internal customer on first use.
  - `stripeCustomerId` string — Stripe customer ID (`cus_…`) from your connected Stripe account. If no Drip customer exists yet for (business, stripeCustomerId), one is auto-provisioned and usage is forwarded to Stripe's Billing Meter Events. Intended for merchants who just finished Stripe OAuth, so you can start sending usage against Stripe IDs immediately without waiting for the background customer import.
  - `usageType` string — Usage type matching a pricing plan (defaults to "generic" if omitted)
  - `quantity` number — Quantity of usage (defaults to 1 if omitted)
  - `units` string — Human-readable unit label for display (e.g., "tokens", "API calls", "seconds")
  - `description` string — Human-readable description for support/finance teams (e.g., "Chat completion for Customer XYZ")
  - `idempotencyKey` string, required — Unique key to prevent duplicate charges. Required. Use a stable identifier like `{customerId}_{action}_{timestamp}` so retries produce the same key.
  - `metadata` object — Optional metadata
  - `workflowId` string — Link this usage to a workflow
  - `runId` string — Link this usage to an agent run
  - `eventType` 'USAGE' | 'INFERENCE' | 'TOOL_CALL' | 'DELEGATION' | 'RETRIEVAL' | 'CUSTOM' — Classify the type of usage event
  - `actionName` string — Name of the action performed (e.g., "chat_completion", "image_generation")
  - `outcome` 'SUCCEEDED' | 'FAILED' | 'PENDING' | 'SKIPPED' | 'CANCELLED' — Outcome of the action
  - `explanation` string — Human-readable explanation of what happened
  - `parentEventId` string — ID of the parent event (for building causality trees)
  - `retryOfEventId` string — ID of the event this is retrying (for retry chain tracking)
  - `attemptNumber` integer — Attempt number (1 = first try, 2 = first retry, etc.)
  - `inputHash` string — SHA-256 hash of the input for verification
  - `outputHash` string — SHA-256 hash of the output for verification
  - `input` object — Raw input data (will be hashed for verification)
  - `output` object — Raw output data (will be hashed for verification)

## Response `202`

Usage recorded, charge queued

- object — Usage recorded, charge queued
  - `success` boolean
  - `usageEventId` string — Usage event ID
  - `isDuplicate` boolean — True if this was a duplicate request matched by idempotencyKey
  - `charge` object
    - `id` string — Charge ID
    - `amountUsdc` string — Charge amount in USDC
    - `status` 'PENDING' | 'CONFIRMED'
    - `estimatedConfirmationTime` string, nullable — Human-readable estimate of when the charge will be confirmed (e.g. "~15 seconds", "already confirmed")
  - `message` string

## Other responses

- `400` — Validation error
- `401` — Unauthorized
- `403` — Account paused — usage blocked until balance is restored
- `404` — Customer or pricing plan not found
- `429` — Rate limit exceeded. Retry after the duration specified in the Retry-After header.
- `503` — Billing temporarily paused or dependency unavailable

---

[API](https://skmtc.net/usedrip/apis/drip-api.md) · [All operations](https://skmtc.net/usedrip/apis/drip-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/usedrip/drip-api/revisions/2cb1567969ca/schema)