Subject vs Customer Entitlements

Subject APIs are deprecated

Subject-based entitlement APIs are deprecated since September 1, 2025; the removal date will be announced. Prefer customer-based entitlement APIs (v2). See the API reference and migration notes in the Open Source API docs.

#TL;DR

Prefer customer APIs for all new work. They aggregate usage from all subjects assigned to a customer and can be referenced by id or key.
Subject APIs continue to function while deprecated but will be removed. Plan your migration.

#Conceptual differences

Aspect	Subject-based (legacy)	Customer-based (v2)
Entity in API path	`/subjects/{id\|key}/...`	`/customers/{id\|key}/...`
Reference identifier	Subject `id` or `key`	Customer `id` or `key`
Usage aggregation	Customer based	Customer based
Entitlement ownership	Tied to a customer, resolved by subject	Tied to a customer
Migration status	Supported until removal	Recommended, long-term supported

#Endpoint mapping

Legacy (subject-based)	Replacement (customers)
`entitlementsV1.create(...)`	`customers.entitlements.create(...)`
`entitlementsV1.value(...)`	`customers.entitlements.value(...)`
`entitlementsV1.reset(...)`	`customers.entitlements.resetUsage(...)`
`entitlementsV1.history(...)`	`customers.entitlements.history(...)`
`grants.create(...)`	`customers.entitlements.createGrant(...)`

#Example code migration

// Before (subject-based)
await openmeter.entitlementsV1.create('customer-1', {
  type: 'metered',
  featureKey: 'gpt_4_tokens',
  usagePeriod: { interval: 'MONTH' },
});

// After (customer id or key)
await openmeter.customers.entitlements.create('customer-1', {
  type: 'metered',
  featureKey: 'gpt_4_tokens',
  usagePeriod: { interval: 'MONTH' },
});

#When to use which

New implementations: Use customer APIs.
Existing subject-based implementations: Keep running, schedule migration.

#Deprecation timeline

Subject APIs deprecated: September 1, 2025
Subject APIs removed: to be announced

For more context on the change, see the announcement blog post and API reference in the Open Source API docs.