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 →

Backfill a past usage event

POST

/v1/usage-events/backfill

const url = 'http://localhost:8080/v1/usage-events/backfill';
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/backfill \
  --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" }'

Records one usage event with a past timestamp. Same body as POST /v1/usage-events, but timestamp is required and must not be after the customer’s current time (a test clock’s time when the customer is on one). The event is marked origin: backfill and an audit log entry is written.

The event counts toward the billing period its timestamp falls in only if that period’s invoice has not been built yet. An event for an already-invoiced period is stored, but that invoice does not bill it; bill it with a one-off invoice if needed. Its 201 carries the billing_status Hardcount found (see UsageBillingStatus): after_close while the subscription that invoiced the period is active or trialing, outside_subscription once it has ended. A billing period of another subscription that is not invoiced yet and holds the event’s time decides the status instead.

Shares idempotency keys with live ingest: a repeated idempotency_key returns 200 with the original event and an Idempotent-Replayed: true header, and writes nothing. Requires usage write permission.

Authorizations

BearerAuth

Request Body^required

application/json

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

Scalar labels of the event. A price takes an event whose labels include the price’s dimension_match.

object

<= 16 properties

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

required

RFC 3339. Must not be in the future.

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

200

Idempotency replay. The original event, unchanged, with an Idempotent-Replayed header.

application/json

object

required

string

tenant_id

string

customer_id

required

string

meter_id

required

string

quantity

required

Exact quantity as a decimal string (e.g. “1.5”).

string

dimensions

The dimension values sent with the event. Absent when none were sent.

object

key

additional properties

any

idempotency_key

string

timestamp

required

string format: date-time

origin

How the event arrived. backfill means POST /v1/usage-events/backfill.

string

Allowed values: api backfill

provider_cost_cents

What serving this event cost you at your provider, in US cents as a decimal string (e.g. “0.45”), set when the event arrived: from your provider cost rates, or the cost the sender reported (see provider_cost_source). Absent when the cost is unknown or the event has no costed dimensions.

string

provider_cost_source

Where provider_cost_cents came from: table (your provider cost rates), observed (the cost the sender reported), or not_applicable (the meter has no costed dimensions). Absent when the cost is unknown.

string

Allowed values: table not_applicable observed

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

{
  "origin": "api",
  "provider_cost_source": "table",
  "billing_status": "after_close"
}

Headers

Idempotent-Replayed

string

Allowed values: true

201

Event recorded. A billing_status is what Hardcount found when the event arrived (see UsageBillingStatus); the event is stored all the same.

application/json

object

required

string

tenant_id

string

customer_id

required

string

meter_id

required

string

quantity

required

Exact quantity as a decimal string (e.g. “1.5”).

string

dimensions

The dimension values sent with the event. Absent when none were sent.

object

key

additional properties

any

idempotency_key

string

timestamp

required

string format: date-time

origin

How the event arrived. backfill means POST /v1/usage-events/backfill.

string

Allowed values: api backfill

provider_cost_cents

string

provider_cost_source

string

Allowed values: table not_applicable observed

billing_status

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".

string

Allowed values: after_close no_price not_on_plan outside_subscription

Example

{
  "origin": "api",
  "provider_cost_source": "table",
  "billing_status": "after_close"
}

400

invalid_request: the body is not valid JSON.

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"
  }
}

422

validation_error: a missing, empty or whitespace-only idempotency_key, or one longer than 255 characters (param idempotency_key); missing external_customer_id, event_name or timestamp; unknown customer or meter; a future or badly formatted timestamp; more than 16 dimensions or a non-scalar dimension value; a missing or malformed quantity, one with more than 12 decimal places, one of 10^26 or more, or one longer than 100 characters; a properties field with a key (it was renamed dimensions).

application/json

object

error

object

type

string

code

string

message

string

request_id

string

param

string

Example

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

503

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

application/json

object

error

object

type

string

code

string

message

string

request_id

string

param

string

Example

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

Backfill a past usage event

Authorizations

Request Bodyrequired

Example generated

Responses

200

Example

Headers

201

Example

400

Example

422

Example

503

Example

Request Body^required

Example ^generated