Subjects

Subjects in OpenMeter are entities that consume resources you wish to meter. These 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.

• 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.
• Stripe Customer ID: The Stripe Customer ID should be associated with the subject for integration with Stripe billing.

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

#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: {},
    stripeCustomerId: 'cus_xxx',
  },
]);

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