Updates to the Subject APIsDeprecating the subject API and consolidating with customer entity

OpenMeter separates usage metering (subjects) from billing (customers). This design choice remains, but we are deprecating the subject API while enabling to assign multiple subjects to a customer.

To reduce complexity, usage sent with a Customer ID or Key is now automatically mapped to that customer.

#🔄 Key Changes

1. Subjects → Customers (automatic mapping)

• If an event's subject property matches a Customer ID or Key, usage is auto-attributed to that customer.
• Any subject without a linked customer will become a customer.
• These customers stay in sync with their original subjects (name, key, etc.).

2. Multiple subjects per customer

• You can assign multiple subjects to a single customer for consolidated billing.

3. Deprecating subject APIs

• All /api/v*/subjects... endpoints will be deprecated on September 1, 2025.
• All /api/v*/subjects... endpoints will be removed on November 1, 2025.
• Use /api/v*/customers... equivalents instead at entitlements

4. Stripe meter sync → Customers

• We'll automatically migrate your existing Stripe integration to the new OpenMeter Stripe App.
• Stripe Customer IDs will be copied to the corresponding customers.
• This enables multiple Stripe accounts and customer-level control.

#🗓 Deprecation Timeline

#🔗 Auto Subject to Customer Mapping

Mapping subjects to customers is becoming optional. When you send an event where the subject field is a Customer ID or Customer Key, OpenMeter will automatically attribute the usage to the customer.

Manual subject to customer mapping remains functional but is now optional. This change doesn't impact the ingest API and the subject field on the usage event.

Before:

const customer = await openmeter.customers.create({
  name: 'ACME, Inc.',
  key: 'my-identifier',
  usageAttribution: { subjects: ['my-identifier'] },
});

await openmeter.events.ingest({
  type: 'api-request',
  // customer.usageAttribution.subjects
  subject: 'my-identifier',
  data: { … }
})

After September 01, 2025:

const customer = await openmeter.customers.create({
  name: 'ACME, Inc.',
  key: 'my-identifier',
  // optional: customer.usageAttribution.subjects
});


await openmeter.events.ingest({
  type: 'api-request',
  // customer.id or customer.key or customer.usageAttribution.subjects
  subject: 'my-identifier',
  data: { … }
})

Any subject without a linked customer will be turned into a customer automatically. These customers stay in sync with their original subjects (name, key, etc.) until November 1st, 2025.

#👥 Allow assigning multiple subjects to a customer

After this change, you can assign multiple subjects to a customer, which is helpful to model advanced scenarios where multiple consumers need to be billed together.

const customer = await openmeter.customers.create({
  name: 'ACME, Inc.',
  key: 'my-identifier',
  usageAttribution: {
    subjects: ['my-identifier-1', 'my-identifier-2', 'my-identifier-3'],
  },
});

#➡️ Deprecating Subject APIs

→ Use customer APIs instead of subject APIs.

Before:

const entitlement = await openmeter.subjects.createEntitlement(
  'my-identifier',
  { … },
)

After September 01, 2025:

const entitlement = await openmeter.customers.createEntitlement(
  'my-identifier',
  { … },
)

#📝 Migration Guide

Who should act? Anyone calling /api/v*/subjects APIs or relying on subject-level entitlements.

• 1. Switch to customer APIs
  • Find all calls to /api/v*/subjects*.
  • Entitlements → Use customer APIs
  • Notifications → Use customer field in events
• 2. Decide your attribution strategy
  • Easiest: Start sending subject = customer.key (or customer.id) in new events.
  • Custom subjects: Keep your own subject strings and add them to customer.usageAttribution.subjects.

#📚 Frequently Asked Questions

#What is a subject?

A subject is any entity that generates metered usage in OpenMeter — for example, a customer, user, server, service, or device. Subjects exist only in the context of usage events and metering, representing the consumers of your service.

#What is a customer?

A customer is the individual or organization that uses your service and is billed for the usage. One customer can have one or more subjects assigned to it to track usage for these consumers and bill them together.

#Will my existing integrations break after the migration?

No. Existing subject-based APIs will continue to work until the final deprecation date. However, we recommend updating to customer APIs as soon as possible.

#Will you create customers from my subjects?

Yes. All subjects not assigned to customers will be turned into customers on OpenMeter Cloud. These customers remain in sync with the subjects they were created from.

#Can I assign multiple subjects to the same customer?

Yes, this is supported natively after September 1, 2025. You can assign multiple subjects to a single customer via the usageAttribution API property.

#Can I assign the same subject to multiple customers?

No, like before one subject can only belong to a single customer.

#Can I still assign subjects to customers later?

Yes. You can still ingest usage with unassigned subjects, and later link them to customers. You can also assign multiple subjects to customers after September 1, 2025.

#Can I mix customer IDs and subject IDs in ingestion?

Yes. You can use Customer ID, Customer Key or manually assigned subjects as the subject field in the usage event.

#Can I have customer-level entitlements?

Yes. This change introduces customer-level entitlements, which combine usage from all subjects assigned to a customer when calculating balances.

#Can I still create subject-level entitlements?

For now, yes. But subject level entitlements APIs will eventually be deprecated. In the future, use customer-level entitlements, with single or multiple subjects as needed.

#Can I revert back to using subjects APIs only?

No. After the final removal date, the subject APIs like subject-level entitlements will no longer be available.