Subjects | OpenMeter

Subjects in OpenMeter are entities that consume metered resources. A subject can range from users, servers, and services to devices. The design of subjects is intentionally generic, enabling flexible application across various metering scenarios. Typically, a subject acts as a unique identifier within your system for a user or customer.

Example subjects include:

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

#Subjects in OpenMeter

OpenMeter leverages subjects to establish connections with external systems (e.g., Stripe) and to maintain relevant metadata.

Key: The subject's unique identifier.
Display Name: The subject's human-readable name is displayed within the user interface.
Metadata: You can store additional details about the subject using key-value pairs.

#Subjects and Customers

For most use cases subjects and customers are the same.

Subjects: Metering concept, the entity that produces the usage.
Customers: Billing concept, the entitity that pays for the usage.

In some cases, you may want more flexibility in how you track usage and assign customers.

You can read more about customer and subject mapping under subject assignment.

#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 others will choose subjects to represent, devices or services.

#Lifecycle of a Subject

We recommend creating a subject when a new customer or user is created in your system and deleting a subject when a customer or user is deleted. Keeping the subjects in sync in OpenMeter is necessary if you synchronize usage to external systems, such as Stripe billing or CRMs, as OpenMeter knows the mapping between the subject and the external system.

OpenMeter Cloud will also automatically create a subject for you when you ingest an usage event for a new subject.

#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": {...}
}

#The Subject API

The Subject API facilitates the upsertion and deletion of subjects in OpenMeter. Additionally, subjects can be managed via our SDKs or directly through the OpenMeter Cloud Subject Dashboard.

#Upsert a Subject

When adding a new customer or user to your system, we recommend upserting the corresponding subject.

import { OpenMeter } from '@openmeter/sdk';

const openmeter = new OpenMeter({
  baseUrl: 'http://localhost:3000',
  token: '<API_TOKEN>',
});

const subjects = await openmeter.subjects.upsert([
  {
    key: 'customer-1',
    displayName: 'ACME',
    metadata: {},
  },
]);

#Delete a Subject

We recommend deleting a subject when a customer or user is deleted in your system. Deleting a subject won't delete the usage data associated with the subject.

await openmeter.subjects.delete('customer-1');