--- title: "Create a customer entitlement" method: POST path: "/api/v2/customers/{customerIdOrKey}/entitlements" tags: ["Entitlements", "Customers"] --- # Create a customer entitlement `POST /api/v2/customers/{customerIdOrKey}/entitlements` 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 customer 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. ## Path parameters - `customerIdOrKey` union, required — ULID (Universally Unique Lexicographically Sortable Identifier) or external unique key. - string — ULID (Universally Unique Lexicographically Sortable Identifier). - string — ExternalKey is a looser version of key. ## Request body - union — Create inputs for entitlement - object — Create inputs for metered entitlement - `featureId` string — The feature the subject is entitled to use. Either featureKey or featureId is required. - `featureKey` string — The feature the subject is entitled to use. Either featureKey or featureId is required. - `grants` EntitlementGrantCreateInputV2[] — Grants - `amount` number, double, required — The amount to grant. Should be a positive number. - `annotations` Annotations — Set of key-value pairs managed by the system. Cannot be modified by user. - `effectiveAt` string, date-time, required — Effective date for grants and anchor for recurring grants. Provided value will be ceiled to metering windowSize (minute). - `expiration` ExpirationPeriod — The grant expiration definition - `count` integer, required — The number of time units in the expiration period. - `duration` 'HOUR' | 'DAY' | 'WEEK' | 'MONTH' | 'YEAR', required — The expiration duration enum - `maxRolloverAmount` number, double — Grants are rolled over at reset, after which they can have a different balance compared to what they had before the reset. The default value equals grant amount. Balance after the reset is calculated as: Balance_After_Reset = MIN(MaxRolloverAmount, MAX(Balance_Before_Reset, MinRolloverAmount)) - `metadata` Metadata — Set of key-value pairs. Metadata can be used to store additional information about a resource. - `minRolloverAmount` number, double — Grants are rolled over at reset, after which they can have a different balance compared to what they had before the reset. Balance after the reset is calculated as: Balance_After_Reset = MIN(MaxRolloverAmount, MAX(Balance_Before_Reset, MinRolloverAmount)) - `priority` integer — The priority of the grant. Grants with higher priority are applied first. Priority is a positive decimal numbers. With lower numbers indicating higher importance. For example, a priority of 1 is more urgent than a priority of 2. When there are several grants available for the same subject, the system selects the grant with the highest priority. In cases where grants share the same priority level, the grant closest to its expiration will be used first. In the case of two grants have identical priorities and expiration dates, the system will use the grant that was created first. - `recurrence` RecurringPeriodCreateInput — Recurring period with an interval and an anchor. - `anchor` string, date-time — A date-time anchor to base the recurring period on. - `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`. - `isSoftLimit` boolean — If softLimit=true the subject can use the feature even if the entitlement is exhausted, hasAccess will always be true. - `issue` IssueAfterReset — Issue after reset - `amount` number, double, required — The initial grant amount - `priority` integer — The priority of the issue after reset - `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. - `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. - `metadata` Metadata — Set of key-value pairs. Metadata can be used to store additional information about a resource. - `preserveOverageAtReset` boolean — If true, the overage is preserved at reset. If false, the usage is reset to 0. - `type` 'metered', required - `usagePeriod` RecurringPeriodCreateInput, required — Recurring period with an interval and an anchor. - `anchor` string, date-time — A date-time anchor to base the recurring period on. - `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`. - object — Create inputs for static entitlement - `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. - `featureId` string — The feature the subject is entitled to use. Either featureKey or featureId is required. - `featureKey` 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` 'static', required - `usagePeriod` RecurringPeriodCreateInput — Recurring period with an interval and an anchor. - `anchor` string, date-time — A date-time anchor to base the recurring period on. - `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`. - object — Create inputs for boolean entitlement - `featureId` string — The feature the subject is entitled to use. Either featureKey or featureId is required. - `featureKey` 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` 'boolean', required - `usagePeriod` RecurringPeriodCreateInput — Recurring period with an interval and an anchor. - `anchor` string, date-time — A date-time anchor to base the recurring period on. - `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`. ## 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). - `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. - `createdAt` string, date-time, required — Timestamp of when the resource was created. - `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. - `customerId` string, required — The identifier unique to the customer - `customerKey` string — The identifier key unique to the customer - `deletedAt` string, date-time — Timestamp of when the resource was permanently deleted. - `featureId` string, required — The feature the subject is entitled to use. - `featureKey` string, required — The feature the subject is entitled to use. - `id` string, required — Readonly unique ULID identifier. - `isSoftLimit` boolean — If softLimit=true the subject can use the feature even if the entitlement is exhausted, hasAccess will always be true. - `issue` IssueAfterReset — Issue after reset - `amount` number, double, required — The initial grant amount - `priority` integer — The priority of the issue after reset - `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. - `lastReset` string, date-time, required — The time the last reset happened. - `measureUsageFrom` string, date-time, required — The time from which usage is measured. If not specified on creation, defaults to entitlement creation time. - `metadata` Metadata — Set of key-value pairs. Metadata can be used to store additional information about a resource. - `preserveOverageAtReset` boolean — If true, the overage is preserved at reset. If false, the usage is reset to 0. - `type` 'metered', required - `updatedAt` string, date-time, required — Timestamp of when the resource was last updated. - `usagePeriod` RecurringPeriod, required — Recurring period with an interval and an anchor. - `anchor` string, date-time, required — A date-time anchor to base the recurring period on. - `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`. - `intervalISO` string, duration, required — The unit of time for the interval in ISO8601 format. - object — A static entitlement. - `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. - `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. - `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. - `customerId` string, required — The identifier unique to the customer - `customerKey` string — The identifier key unique to the customer - `deletedAt` string, date-time — Timestamp of when the resource was permanently deleted. - `featureId` string, required — The feature the subject is entitled to use. - `featureKey` string, required — The feature the subject is entitled to use. - `id` string, required — Readonly unique ULID identifier. - `metadata` Metadata — Set of key-value pairs. Metadata can be used to store additional information about a resource. - `type` 'static', required - `updatedAt` string, date-time, required — Timestamp of when the resource was last updated. - `usagePeriod` RecurringPeriod — Recurring period with an interval and an anchor. - `anchor` string, date-time, required — A date-time anchor to base the recurring period on. - `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`. - `intervalISO` string, duration, required — The unit of time for the interval in ISO8601 format. - object — Entitlement template of a boolean entitlement. - `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. - `createdAt` string, date-time, required — Timestamp of when the resource was created. - `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. - `customerId` string, required — The identifier unique to the customer - `customerKey` string — The identifier key unique to the customer - `deletedAt` string, date-time — Timestamp of when the resource was permanently deleted. - `featureId` string, required — The feature the subject is entitled to use. - `featureKey` string, required — The feature the subject is entitled to use. - `id` string, required — Readonly unique ULID identifier. - `metadata` Metadata — Set of key-value pairs. Metadata can be used to store additional information about a resource. - `type` 'boolean', required - `updatedAt` string, date-time, required — Timestamp of when the resource was last updated. - `usagePeriod` RecurringPeriod — Recurring period with an interval and an anchor. - `anchor` string, date-time, required — A date-time anchor to base the recurring period on. - `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`. - `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.dev/openmeter/apis/openmeter-cloud-api.md) · [All operations](https://skmtc.dev/openmeter/apis/openmeter-cloud-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/openmeter/openmeter-cloud-api/revisions/c9c0ec9cffe9/schema)