Events

Use the Node.js, Python, or Go SDK for event ingestion. Each track() or Track() call sends one event; batching is explicit.

See Node.js event tracking, Python event tracking, or Go event tracking for subscription resolution and idempotency behavior.

Event envelope

{
  "event": {
    "transaction_id": "request_0183f",
    "external_customer_id": "customer_123",
    "external_subscription_id": "subscription_123",
    "code": "api_calls",
    "properties": {
      "model": "example-model",
      "tokens": 1500
    },
    "timestamp": 1785839400
  }
}

Field	Required	Description
`transaction_id`	no	Organization-wide identifier for the logical event. Nozle generates and returns a version 7 universally unique identifier when omitted. Preserve the identifier and complete payload on retries.
`external_subscription_id`	one of the two	Subscription the event is billed to. When it is given, `external_customer_id` is ignored.
`external_customer_id`	one of the two	Used only when `external_subscription_id` is blank: the event is billed to the customer’s single active subscription.
`code`	yes	Feature code.
`properties`	no	Aggregation and attribution metadata.
`timestamp`	no	Unix seconds for direct HTTP requests. The SDKs normalize their supported timestamp inputs to this wire format.

A Feature that aggregates a property (sum, max, latest, weighted_sum or a custom aggregation) needs that property in properties as a number or a numeric string. An event whose value is missing, empty or not a number is still accepted, but Nozle skips it for usage limits, revenue and cost instead of counting it as 1 unit. count and unique_count Features do not read a value and count every event. An event needs external_subscription_id or external_customer_id. With only the customer, Nozle looks up that customer’s active subscription and stores the event with its external_subscription_id, as the SDKs do. The customer must have exactly one active subscription; with several, send external_subscription_id. For direct HTTP ingestion, send this envelope to POST https://api.nozle.app/engine/api/v1/events with a secret key. Send batches of 1–100 events to POST https://api.nozle.app/engine/api/v1/events/batch using an events array. Event reads and fee estimates use the Core API. Prefer the SDKs so subscription lookup, UUID generation, timeout handling, and errors remain consistent.

For retry safety, preserve the complete event payload, including timestamp, and reuse the same transaction_id. Never reuse a transaction_id for a different event: on the standard event store the first accepted event owns that identifier, the same event returns the stored one, and a different one (another code, subscription, properties or sent timestamp) gets 409 transaction_id_conflict. On the high-volume event store the repeat is accepted with 200, which does not tell you how it is counted; a repeat is deduplicated only when transaction_id and timestamp both match. Without a timestamp, each attempt is stamped when it arrives, so send one and reuse it. See deduplication.

Responses and limits

Case	Result
Accepted	`200` with the event under `event`. A batch returns the events under `events`.
Batch size	1 to 100 events. An empty array returns `422` with `events: ["no_events"]`, and more than 100 returns `422` with `events: ["too_many_events"]`.
An invalid event in a batch	The whole batch is rejected with `422 validation_errors` and nothing is stored. `error_details` is keyed by the position of the event in the array, for example `{"0": {"external_customer_id": ["active_subscription_ambiguous"]}}`.
A `transaction_id` already used, same payload	Standard event store: `200` with the stored event, and nothing new is stored. High-volume event store: `200`, and billing removes the repeat.
A `transaction_id` already used, different payload	Standard event store: `409 transaction_id_conflict` with `error_details` `{"transaction_id": ["value_already_exist"]}`, and nothing is stored. High-volume event store: `200`, and billing counts one copy. See deduplication.
The same `transaction_id` twice in one batch, or a reused one with a different payload	Standard event store: the batch is rejected with `422 validation_errors` and `transaction_id: ["value_already_exist"]` for that event. High-volume event store: `200`.
A `timestamp` that is not a number	`422` with `timestamp: ["invalid_format"]`.
Neither `external_subscription_id` nor `external_customer_id`	`422 validation_errors` with `external_subscription_id: ["value_is_mandatory"]`.
Only `external_customer_id`, and the customer is unknown or has no active subscription	`422 active_subscription_not_found` with `error_details` `{"external_customer_id": ["active_subscription_not_found"]}`.
Only `external_customer_id`, and the customer has several active subscriptions	`422 active_subscription_ambiguous` with `error_details` `{"external_customer_id": ["active_subscription_ambiguous"]}`. Send `external_subscription_id`.
A `pk_` key	`403 publishable_key_not_allowed`.
No key, or an unknown key	`401`.

Nozle does not reject events for being old or in the future. A feature code that matches no feature is accepted but never counted, so check the event name against the feature code.

Retrying

Retry a network error, a timeout or a 5xx with the same transaction_id and the same payload.
Do not retry a 4xx. Fix the event first, because the same request gets the same answer.
For a batch, resend the whole batch after a failure you cannot read: a batch is either stored or rejected.

See idempotency and errors.

Overview

Application Workflows

Billing Resources

Usage & Metering

Invoicing & Payments

Platform & Operations

Event envelope

Responses and limits

Retrying

​Event envelope

​Responses and limits

​Retrying

Event envelope

Responses and limits

Retrying