--- title: "Create a subject entitlement" method: POST path: "/api/v1/subjects/{subjectIdOrKey}/entitlements" tags: ["Entitlements"] deprecated: true --- # Create a subject entitlement `POST /api/v1/subjects/{subjectIdOrKey}/entitlements` > **Deprecated.** OpenMeter has three types of entitlements: metered, boolean, and static. The type property determines the type of entitlement. The underlying feature has to be compatible with the entitlement type specified in the request (e.g., a metered entitlement needs a feature associated with a meter). - Boolean entitlements define static feature access, e.g. "Can use SSO authentication". - Static entitlements let you pass along a configuration while granting access, e.g. "Using this feature with X Y settings" (passed in the config). - Metered entitlements have many use cases, from setting up usage-based access to implementing complex credit systems. Example: The customer can use 10000 AI tokens during the usage period of the entitlement. A given subject can only have one active (non-deleted) entitlement per featureKey. If you try to create a new entitlement for a featureKey that already has an active entitlement, the request will fail with a 409 error. Once an entitlement is created you cannot modify it, only delete it. ⚠️ __Deprecated__: Use [`POST /api/v2/customers/{customerIdOrKey}/entitlements`](#tag/entitlements/post/api/v2/customers/{customerIdOrKey}/entitlements) instead. ## Path parameters - `subjectIdOrKey` string, required ## Request body - union — Create inputs for entitlement - object — Create inpurs for metered entitlement - `featureKey` string — The feature the subject is entitled to use. Either featureKey or featureId is required. - `featureId` string — The feature the subject is entitled to use. Either featureKey or featureId is required. - `metadata` Metadata — Set of key-value pairs. Metadata can be used to store additional information about a resource. - `type` 'metered', required - `isSoftLimit` boolean — If softLimit=true the subject can use the feature even if the entitlement is exhausted, hasAccess will always be true. - `isUnlimited` boolean — Deprecated, ignored by the backend. Please use isSoftLimit instead; this field will be removed in the future. - `usagePeriod` RecurringPeriodCreateInput, required — Recurring period with an interval and an anchor. - `interval` union, required — Period duration for the recurrence - string - 'DAY' | 'WEEK' | 'MONTH' | 'YEAR' — The unit of time for the interval. One of: `day`, `week`, `month`, or `year`. - `anchor` string, date-time — A date-time anchor to base the recurring period on. - `measureUsageFrom` union — Measure usage from - 'CURRENT_PERIOD_START' | 'NOW' — Start of measurement options - string, date-time — [RFC3339](https://tools.ietf.org/html/rfc3339) formatted date-time string in UTC. - `issueAfterReset` number, double — You can grant usage automatically alongside the entitlement, the example scenario would be creating a starting balance. If an amount is specified here, a grant will be created alongside the entitlement with the specified amount. That grant will have it's rollover settings configured in a way that after each reset operation, the balance will return the original amount specified here. Manually creating such a grant would mean having the "amount", "minRolloverAmount", and "maxRolloverAmount" fields all be the same. - `issueAfterResetPriority` integer — Defines the grant priority for the default grant. - `preserveOverageAtReset` boolean — If true, the overage is preserved at reset. If false, the usage is reset to 0. - object — Create inputs for static entitlement - `featureKey` string — The feature the subject is entitled to use. Either featureKey or featureId is required. - `featureId` string — The feature the subject is entitled to use. Either featureKey or featureId is required. - `metadata` Metadata — Set of key-value pairs. Metadata can be used to store additional information about a resource. - `usagePeriod` RecurringPeriodCreateInput — Recurring period with an interval and an anchor. - `interval` union, required — Period duration for the recurrence - string - 'DAY' | 'WEEK' | 'MONTH' | 'YEAR' — The unit of time for the interval. One of: `day`, `week`, `month`, or `year`. - `anchor` string, date-time — A date-time anchor to base the recurring period on. - `type` 'static', required - `config` string, json, required — The JSON parsable config of the entitlement. This value is also returned when checking entitlement access and it is useful for configuring fine-grained access settings to the feature, implemented in your own system. Has to be an object. - object — Create inputs for boolean entitlement - `featureKey` string — The feature the subject is entitled to use. Either featureKey or featureId is required. - `featureId` string — The feature the subject is entitled to use. Either featureKey or featureId is required. - `metadata` Metadata — Set of key-value pairs. Metadata can be used to store additional information about a resource. - `usagePeriod` RecurringPeriodCreateInput — Recurring period with an interval and an anchor. - `interval` union, required — Period duration for the recurrence - string - 'DAY' | 'WEEK' | 'MONTH' | 'YEAR' — The unit of time for the interval. One of: `day`, `week`, `month`, or `year`. - `anchor` string, date-time — A date-time anchor to base the recurring period on. - `type` 'boolean', required ## Response `201` The request has succeeded and a new resource has been created as a result. - union — Entitlement templates are used to define the entitlements of a plan. Features are omitted from the entitlement template, as they are defined in the rate card. - object — Metered entitlements are useful for many different use cases, from setting up usage based access to implementing complex credit systems. Access is determined based on feature usage using a balance calculation (the "usage allowance" provided by the issued grants is "burnt down" by the usage). - `type` 'metered', required - `isSoftLimit` boolean — If softLimit=true the subject can use the feature even if the entitlement is exhausted, hasAccess will always be true. - `isUnlimited` boolean — Deprecated, ignored by the backend. Please use isSoftLimit instead; this field will be removed in the future. - `issueAfterReset` number, double — You can grant usage automatically alongside the entitlement, the example scenario would be creating a starting balance. If an amount is specified here, a grant will be created alongside the entitlement with the specified amount. That grant will have it's rollover settings configured in a way that after each reset operation, the balance will return the original amount specified here. Manually creating such a grant would mean having the "amount", "minRolloverAmount", and "maxRolloverAmount" fields all be the same. - `issueAfterResetPriority` integer — Defines the grant priority for the default grant. - `preserveOverageAtReset` boolean — If true, the overage is preserved at reset. If false, the usage is reset to 0. - `createdAt` string, date-time, required — Timestamp of when the resource was created. - `updatedAt` string, date-time, required — Timestamp of when the resource was last updated. - `deletedAt` string, date-time — Timestamp of when the resource was permanently deleted. - `metadata` Metadata — Set of key-value pairs. Metadata can be used to store additional information about a resource. - `activeFrom` string, date-time, required — The cadence start of the resource. - `activeTo` string, date-time — The cadence end of the resource. - `annotations` Annotations — Set of key-value pairs managed by the system. Cannot be modified by user. - `id` string, required — Readonly unique ULID identifier. - `subjectKey` string, required — The identifier key unique to the subject. NOTE: Subjects are being deprecated, please use the new customer APIs. - `featureKey` string, required — The feature the subject is entitled to use. - `featureId` string, required — The feature the subject is entitled to use. - `lastReset` string, date-time, required — The time the last reset happened. - `currentUsagePeriod` Period, required — A period with a start and end time. - `from` string, date-time, required — Period start time. - `to` string, date-time, required — Period end time. - `measureUsageFrom` string, date-time, required — The time from which usage is measured. If not specified on creation, defaults to entitlement creation time. - `usagePeriod` RecurringPeriod, required — Recurring period with an interval and an anchor. - `interval` union, required — Period duration for the recurrence - string - 'DAY' | 'WEEK' | 'MONTH' | 'YEAR' — The unit of time for the interval. One of: `day`, `week`, `month`, or `year`. - `anchor` string, date-time, required — A date-time anchor to base the recurring period on. - `intervalISO` string, duration, required — The unit of time for the interval in ISO8601 format. - object — A static entitlement. - `type` 'static', required - `config` string, json, required — The JSON parsable config of the entitlement. This value is also returned when checking entitlement access and it is useful for configuring fine-grained access settings to the feature, implemented in your own system. Has to be an object. - `createdAt` string, date-time, required — Timestamp of when the resource was created. - `updatedAt` string, date-time, required — Timestamp of when the resource was last updated. - `deletedAt` string, date-time — Timestamp of when the resource was permanently deleted. - `metadata` Metadata — Set of key-value pairs. Metadata can be used to store additional information about a resource. - `activeFrom` string, date-time, required — The cadence start of the resource. - `activeTo` string, date-time — The cadence end of the resource. - `annotations` Annotations — Set of key-value pairs managed by the system. Cannot be modified by user. - `id` string, required — Readonly unique ULID identifier. - `subjectKey` string, required — The identifier key unique to the subject. NOTE: Subjects are being deprecated, please use the new customer APIs. - `featureKey` string, required — The feature the subject is entitled to use. - `featureId` string, required — The feature the subject is entitled to use. - `currentUsagePeriod` Period — A period with a start and end time. - `from` string, date-time, required — Period start time. - `to` string, date-time, required — Period end time. - `usagePeriod` RecurringPeriod — Recurring period with an interval and an anchor. - `interval` union, required — Period duration for the recurrence - string - 'DAY' | 'WEEK' | 'MONTH' | 'YEAR' — The unit of time for the interval. One of: `day`, `week`, `month`, or `year`. - `anchor` string, date-time, required — A date-time anchor to base the recurring period on. - `intervalISO` string, duration, required — The unit of time for the interval in ISO8601 format. - object — Entitlement template of a boolean entitlement. - `type` 'boolean', required - `createdAt` string, date-time, required — Timestamp of when the resource was created. - `updatedAt` string, date-time, required — Timestamp of when the resource was last updated. - `deletedAt` string, date-time — Timestamp of when the resource was permanently deleted. - `metadata` Metadata — Set of key-value pairs. Metadata can be used to store additional information about a resource. - `activeFrom` string, date-time, required — The cadence start of the resource. - `activeTo` string, date-time — The cadence end of the resource. - `annotations` Annotations — Set of key-value pairs managed by the system. Cannot be modified by user. - `id` string, required — Readonly unique ULID identifier. - `subjectKey` string, required — The identifier key unique to the subject. NOTE: Subjects are being deprecated, please use the new customer APIs. - `featureKey` string, required — The feature the subject is entitled to use. - `featureId` string, required — The feature the subject is entitled to use. - `currentUsagePeriod` Period — A period with a start and end time. - `from` string, date-time, required — Period start time. - `to` string, date-time, required — Period end time. - `usagePeriod` RecurringPeriod — Recurring period with an interval and an anchor. - `interval` union, required — Period duration for the recurrence - string - 'DAY' | 'WEEK' | 'MONTH' | 'YEAR' — The unit of time for the interval. One of: `day`, `week`, `month`, or `year`. - `anchor` string, date-time, required — A date-time anchor to base the recurring period on. - `intervalISO` string, duration, required — The unit of time for the interval in ISO8601 format. ## Other responses - `400` — The server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing). - `401` — The request has not been applied because it lacks valid authentication credentials for the target resource. - `403` — The server understood the request but refuses to authorize it. - `409` — The request could not be completed due to a conflict with the current state of the target resource. - `412` — One or more conditions given in the request header fields evaluated to false when tested on the server. - `500` — The server encountered an unexpected condition that prevented it from fulfilling the request. - `503` — The server is currently unable to handle the request due to a temporary overload or scheduled maintenance, which will likely be alleviated after some delay. - `default` — An unexpected error response. --- [API](https://skmtc.net/openmeterio/apis/openmeter-api.md) · [All operations](https://skmtc.net/openmeterio/apis/openmeter-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/openmeterio/openmeter-api/versions/927d82ffe647/schema)