Pre-1.0 · one maintainer · Stripe and cards only · no SDKs (client libraries) yet · no production users yet. Docs describe v0.9.1 (29 Oct 2026) · What’s new →

Batch ingest usage events (max 1000, all-or-nothing)

POST

/v1/usage-events/batch

const url = 'http://localhost:8080/v1/usage-events/batch';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '[{"external_customer_id":"example","event_name":"example","quantity":1,"dimensions":{},"idempotency_key":"example","timestamp":"2026-04-15T12:00:00Z"}]'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request POST \
  --url http://localhost:8080/v1/usage-events/batch \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '[ { "external_customer_id": "example", "event_name": "example", "quantity": 1, "dimensions": {}, "idempotency_key": "example", "timestamp": "2026-04-15T12:00:00Z" } ]'

The batch is atomic: every event validates, then all of them commit in one transaction. On any validation failure nothing is ingested. Every event must carry its own idempotency_key; an event without one fails validation, so the whole batch is refused. Retrying the whole batch is safe because of those keys: events already stored are counted in deduplicated, not stored again, and are not errors. A deduplicated count above zero on a batch you never sent before means some keys were already used, by an earlier event or by another event in the batch. Those events were not stored.

Authorizations

BearerAuth

Request Body^required

application/json

Array<object>

object

external_customer_id

required

The customer’s external_id (your identifier), not the internal hc_cus_ id.

string

event_name

required

The meter’s event_name (e.g. “tokens”).

string

quantity

required

One of:

number
string

number

dimensions

object

key

additional properties

any

idempotency_key

required

Your unique ID for this event. Pick it once, before the first send, and send the same key on every retry of the event. Keys are unique per tenant and mode (live or test), forever. An event whose key was already used is not stored again: the first event wins and the new body is discarded. So never reuse a key for a different event, such as a batch index or a timestamp that can repeat, or that usage is lost. Empty or whitespace-only keys are refused with 422, and so are keys longer than 255 characters. This is the only dedup key: the usage routes ignore the Idempotency-Key header.

string

<= 255 characters

timestamp

string format: date-time

Example ^generated

[
  {
    "external_customer_id": "example",
    "event_name": "example",
    "quantity": 1,
    "dimensions": {},
    "idempotency_key": "example",
    "timestamp": "2026-04-15T12:00:00Z"
  }
]

Responses

201

Batch committed

application/json

object

ingested

required

Newly written events.

integer

deduplicated

required

Idempotency replays — already ingested, counted as success.

integer

total

required

Events in the request.

integer

after_close

required

Of ingested, the events answered billing_status after_close.

integer

no_price

required

Of ingested, the events answered billing_status no_price.

integer

not_on_plan

required

Of ingested, the events answered billing_status not_on_plan.

integer

outside_subscription

required

Of ingested, the events answered billing_status outside_subscription.

integer

results

required

One entry per event, in the order sent: results[i] is the request’s event i.

Array<object>

object

status

required

ingested: the batch wrote the event. deduplicated: an event with its idempotency_key was already stored, earlier or in this batch, so it was not stored again.

string

Allowed values: ingested deduplicated

billing_status

What Hardcount found when the event arrived. It checked the event against the customer’s subscriptions, the plans and prices in force, and the invoices already built at that moment. Sent only on the answer that wrote the event; the event is stored all the same.

A status that is present was true at that moment:

after_close: the event’s time is already invoiced. A spend-threshold invoice counts only once it is paid. Bill the event with a one-off invoice if it should be charged.
not_on_plan: a billing period not invoiced yet holds the event’s time, but its plan has no price for this meter.
outside_subscription: no active or trialing subscription of the customer bills the event’s time. For example, it has none, or the time is before one starts, in a free trial, or after one ends or its scheduled cancel.
no_price: the plan that bills the event’s time prices this meter, but no price of that plan takes the event’s dimensions. A price takes an event whose dimensions include all of its dimension_match, compared as strings: the number 1 is not the string "1".

No billing_status means Hardcount found no reason then. It is not a promise that the event will be billed. Hardcount checks only the customer’s current billing periods: time after a period end whose invoice is not built yet is not checked, nor is time after a trial’s end before Hardcount ends the trial. A later change can change the outcome either way: a subscription created, activated or changed, a trial extended, a scheduled cancel undone, or a price added. The invoice is the final answer.

Two cases can make a present status wrong: a price change whose save began before a billing period started and finished after the request read the prices, and a subscription change saved while the request is in flight. Absent on a replay and on a read.

string

Allowed values: after_close no_price not_on_plan outside_subscription

Example

{
  "results": [
    {
      "status": "ingested",
      "billing_status": "after_close"
    }
  ]
}

413

Request body over the 1MB cap — send smaller batches.

422

Batch rejected — one or more events failed validation and NOTHING was ingested. The body is the error envelope (code batch_rejected) plus errors[], which names every failing index (event[i]: reason), ingested: 0 and total. Fix them and retry the whole batch.

503

ingest_unavailable: a customer or meter lookup, or the read of the customer’s billing periods, could not be answered. Nothing was recorded; retry the whole batch.

application/json

object

error

object

type

One of invalid_request_error, authentication_error, rate_limit_error or api_error. Every error the API answers has this shape, including an unknown path (404, code route_not_found) and a method the path does not take (405, code method_not_allowed, with an Allow header). The few exceptions are listed in docs/api-surface.md.

string

code

string

message

string

request_id

string

param

The request field the error is about. Sent only when the error names one. A request body may hold only the fields its operation lists, spelled and cased as listed: any other field, or one the server sets (such as id), is refused with 422 and param naming it. An operation with no request body lists no fields: send no body, {} or null. The Stripe and Postmark webhooks and the LiteLLM callback take their sender’s body as it comes.

string

Example

{
  "error": {
    "type": "invalid_request_error"
  }
}

Batch ingest usage events (max 1000, all-or-nothing)

Authorizations

Request Bodyrequired

Example generated

Responses

201

Example

413

422

503

Example

Request Body^required

Example ^generated