Sign in

v51

latestOpenAPI 3.0.0Apache 2.0raw.githubusercontent.com2026-08-011534301009.2 KB
Entitlements
Customers

Create a customer entitlement

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.

post/api/v2/customers/{customerIdOrKey}/entitlements

Path parameters

string required

ULID (Universally Unique Lexicographically Sortable Identifier).

OR
string required

ExternalKey is a looser version of key.

Example:01G65Z755AFWAKHE12NY0CQ9FH

Request body

OR
OR

Example request

{
  "featureKey": "example-feature-key",
  "featureId": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
  "metadata": {
    "externalId": "019142cc-a016-796a-8113-1a942fecd26d"
  },
  "usagePeriod": {
    "interval": "DAY",
    "anchor": "2023-01-01T01:01:01.001Z"
  },
  "measureUsageFrom": "2023-01-01T01:01:01.001Z",
  "grants": [
    {
      "amount": 100,
      "priority": 1,
      "effectiveAt": "2023-01-01T01:01:01.001Z",
      "minRolloverAmount": 100,
      "metadata": {
        "externalId": "019142cc-a016-796a-8113-1a942fecd26d"
      },
      "recurrence": {
        "interval": "DAY",
        "anchor": "2023-01-01T01:01:01.001Z"
      },
      "maxRolloverAmount": 100,
      "expiration": {
        "count": 12
      },
      "annotations": {
        "externalId": "019142cc-a016-796a-8113-1a942fecd26d"
      }
    }
  ]
}

Response

The request has succeeded and a new resource has been created as a result.

OR
OR

Example response

{
  "createdAt": "2024-01-01T01:01:01.001Z",
  "updatedAt": "2024-01-01T01:01:01.001Z",
  "deletedAt": "2024-01-01T01:01:01.001Z",
  "metadata": {
    "externalId": "019142cc-a016-796a-8113-1a942fecd26d"
  },
  "activeFrom": "2023-01-01T01:01:01.001Z",
  "activeTo": "2023-01-01T01:01:01.001Z",
  "annotations": {
    "externalId": "019142cc-a016-796a-8113-1a942fecd26d"
  },
  "id": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
  "featureKey": "example-feature-key",
  "featureId": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
  "lastReset": "2023-01-01T01:01:01.001Z",
  "currentUsagePeriod": {
    "from": "2023-01-01T01:01:01.001Z",
    "to": "2023-02-01T01:01:01.001Z"
  },
  "measureUsageFrom": "2023-01-01T01:01:01.001Z",
  "usagePeriod": {
    "interval": "DAY",
    "intervalISO": "P1D",
    "anchor": "2023-01-01T01:01:01.001Z"
  },
  "customerKey": "customer-1",
  "customerId": "01ARZ3NDEKTSV4RRFFQ69G5FAV"
}