Subject vs Customer Entitlements

Subject APIs are being deprecated

Subject-based entitlement APIs will be deprecated on September 1, 2025 and removed on November 1, 2025. 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 during the deprecation window 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 (subjects)	Replacement (customers)
`subjects.createEntitlement(...)`	`customers.createEntitlement(...)`
`subjects.getEntitlementValue(...)`	`customers.getEntitlementValue(...)`
`subjects.resetEntitlementUsage(...)`	`customers.resetEntitlementUsage(...)`
`subjects.getEntitlementHistory(...)`	`customers.getEntitlementHistory(...)`
`subjects.createEntitlementGrant(...)`	`customers.createEntitlementGrant(...)`

#Example code migration

// Before
await openmeter.subjects.createEntitlement('customer-1', {
  type: 'metered',
  featureKey: 'gpt_4_tokens',
  usagePeriod: { interval: 'MONTH' },
});

// After (customer id or key)
await openmeter.customers.createEntitlement('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: November 1, 2025

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