GitHub
DocsCloudCollectorsGlossaryAPI

Subjects

A subject is a string key that identifies the consumer of metered usage. You send it in the subject field of every usage event, and OpenMeter aggregates usage per subject. Typically, the subject is a unique identifier from your own system, such as a user ID or customer ID.

Subjects are not managed entities

There is no subject object in OpenMeter and no API to create, update, or delete subjects. A subject exists only as the key in your usage events — nothing needs to be provisioned before sending events and nothing needs to be cleaned up. The managed, billable entity in OpenMeter is the Customer.

Example subject keys:

  • Customer ID or User ID
  • Hostname or IP address
  • Service or Application name
  • Device ID

Subjects and Customers

For most use cases the subject key and the customer are the same. The difference is their role:

 SubjectCustomer
ConceptMetering: identifies who produced the usage.Billing: the entity that subscribes, pays, and has entitlements.
RepresentationA key in usage events.A managed entity with its own API and lifecycle.
Created byNothing to create; any event value is valid.You, via the API or the OpenMeter dashboard.

To attribute usage to a billable customer, either send the customer's key or ID as the event subject (OpenMeter attributes the usage to that customer automatically), or map custom subject keys to the customer via usage attribution. A customer can have multiple subject keys attributed to it, and usage across all of them counts toward the customer — but a given subject key can belong to only one customer.

Avoid key collisions

Make sure custom subject values don't collide with any existing customer.key or customer.id. Because customer keys and IDs are attributed automatically, a colliding subject value attributes usage to the wrong customer.

Why Subject?

The concept of subjects is carried over from the CloudEvents specification, that OpenMeter uses for data ingestion:

{
  "specversion": "1.0",
  "type": "api-calls",
  "id": "00001",
  "time": "2025-01-01T00:00:00.001Z",
  "source": "my-service",
  "subject": "my-user-id-1",
  "data": {...}
}

We choose subjects as they are generic. This allows OpenMeter to be flexible and applicable across various metering scenarios.

For example, some OpenMeter users will choose subjects to represent users, organizations, and companies, while others will choose subjects to represent devices or services.

Subjects at Data Ingestion

When submitting data to OpenMeter, you must include the subject within your data payload. OpenMeter adopts the CloudEvents format for data ingestion, incorporating the subject in the subject field:

{
  "specversion": "1.0",
  "type": "api-calls",
  "id": "00002",
  "time": "2023-01-01T00:00:00.001Z",
  "source": "service-0",
  "subject": "customer-1",
  "data": {...}
}

Any non-empty string you send becomes a valid subject key immediately; usage for a new key is queryable as soon as its first event is ingested.

Last updated on