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

# Record internal usage (no billing)

`POST /v1/usage/internal`

Record a usage event for internal visibility tracking only. No billing or charges are created.

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

**Use cases:**
- Track internal team usage without charging
- Pilot programs where you want visibility before billing
- Usage tracking before customer has on-chain wallet setup

This endpoint:
- Does NOT create a Charge record
- Does NOT require customer balance
- Does NOT require blockchain/wallet setup for internal customers
- Works with both internal and regular customers

For billing customers, use `POST /v1/usage` or `POST /v1/usage/async` instead.

## 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 `201`

Internal usage recorded

- object — Internal usage recorded
  - `success` boolean
  - `usageEventId` string — Usage event ID
  - `customerId` string — Customer ID
  - `usageType` string — Type of usage
  - `quantity` number — Quantity recorded
  - `units` string, nullable — Human-readable unit label
  - `description` string, nullable — Human-readable event description
  - `isInternal` boolean — Whether customer is internal-only
  - `message` string

## Other responses

- `400` — Validation error
- `401` — Unauthorized
- `404` — Customer 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)