Send Usage Events

5 min

Stream usage events into Nue for metering. Events are batched, deduplicated by your own id, and durably queued for aggregation and rating.

Endpoint

POST https://metering.nue.io/v1/metering/events

Permission: Gated by the Metering license.

Limits

Up to 1000 events per request.

Up to 256 KB per request.

At least one event per request.

Request body

{ "data": [ <event>, … ] }

Each event:

Field	Type	Required	Notes
transactionId	string	Yes	Your unique id for this event. This is the deduplication key.
subscriptionNumber	string	Identity option A	The subscription the usage belongs to. Do not combine with the customer and product fields.
customerId or customerName	string	Identity option B	The customer, by id or name. Pair with a product field.
sku or productName	string	Identity option B	The product, by SKU or name. Pair with a customer field.
timestamp	string	Yes	RFC3339 with an explicit timezone or UTC offset.
value or quantity	number	Yes, exactly one	Whole numbers only. Supplying both is rejected.
properties	object of strings	Yes	Pricing and usage dimension values. Keys must not reuse reserved field names.
tags	object of strings	No	Filter only labels. Same reserved key rule.
specVersion	string	No	Contract major version. Only major 1 is served.

Identify each event one of two ways: by subscriptionNumber, or by a customer field (customerId or customerName) together with a product field (sku or productName). Do not mix the two ways on one event.

Reserved keys (rejected inside properties or tags): transactionId, subscriptionNumber, customerId, customerName, sku, productName, timestamp, value, quantity.

Response

202 Accepted with an empty body. The batch is durably queued.

Acceptance is not resolution. A 202 means the events are queued, not that they will be priced. An event whose subscription cannot be resolved is discarded downstream. Duplicate transactionIds are accepted here and suppressed at read and rating time: the first event for a transactionId wins, and a resend never double counts and never errors.

A malformed batch returns 400 with the standard error envelope. Per event problems carry codes that name the offending field: MISSING_FIELD, MISSING_IDENTITY, CONFLICTING_IDENTITY, DUPLICATE_VALUE_FIELD, INVALID_TIMESTAMP, INVALID_VALUE, RESERVED_KEY.

Example

curl --request POST \
  --url https://metering.nue.io/v1/metering/events \
  --header 'nue-api-key: <your-key>' \
  --header 'content-type: application/json' \
  --data '{
    "data": [
      {
        "transactionId": "evt_01K5V8N2Q7",
        "subscriptionNumber": "SUB-000042",
        "timestamp": "2026-09-16T14:03:22Z",
        "value": 18432,
        "properties": { "model": "claude-opus", "region": "us-east-1" },
        "tags": { "userId": "u_8814" }
      }
    ]
  }'

202 Accepted

See Realtime Usage Feed to read the rated results as they move, and Metering Overview for auth, hosts, and data conventions.