> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.solvimon.com/platform-guides/pricing-use-cases/configuring-entitlements-for-ai-products/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.solvimon.com/_mcp/server.

# Configuring entitlements for AI products

Entitlements define what a customer is allowed to do on their plan — which models they can access, how many tokens they can consume per month, and whether premium features are enabled. This guide covers how to configure and enforce entitlements for AI products.

---

## How entitlements work

An entitlement is a feature value assigned to a customer via their pricing plan or subscription. Features are defined once and then assigned per plan tier with different values.

Solvimon stores the entitlement values and makes them queryable. Your application is responsible for reading those values and enforcing them — Solvimon doesn't block requests at runtime.

The pattern is:

1. Define features in Solvimon (once)
2. Assign feature values to pricing plan versions (per tier)
3. Before executing a customer request, query their entitlements and meter usage
4. Allow or block the request based on what you find

---

## Rate limits

Rate limits (requests per minute, requests per day) are a common entitlement for AI APIs.

### Define the feature

Use [POST /v1/features](https://docs.solvimon.com/api-docs/configuration-api/features/post-features):

```bash
curl -X POST https://test.api.solvimon.com/v1/features \
  -H "X-API-KEY: <apiKey>" \
  -H "Content-Type: application/json" \
  -d '{
    "reference": "requests_per_minute",
    "name": "Requests Per Minute",
    "type": "NUMBER"
  }'
```

### Assign different values per plan

When configuring a pricing plan version in Desk or via the API, set the `requests_per_minute` entitlement to:

* Starter: `60`
* Pro: `600`
* Enterprise: `6000`

### Enforce at runtime

Query the customer's entitlements via [GET /v1/customers/\{ref}/entitlements](https://docs.solvimon.com/api-docs/configuration-api/customers/get-customers-by-resource-id-or-reference-entitlements) before accepting a request:

```bash
curl "https://test.api.solvimon.com/v1/customers/acme-corp/entitlements" \
  -H "X-API-KEY: <apiKey>"
```

```json
{
  "entitlements": [
    {
      "feature_reference": "requests_per_minute",
      "number": "600"
    }
  ]
}
```

Cache this value at session start (e.g., when a user authenticates). Enforce it in your rate-limiting middleware using a token bucket or sliding window counter in Redis or similar.

> **Note**
>
> Solvimon provides the entitlement value. Rate limit enforcement, counting requests, maintaining state, returning `429`, happens in your application. For soft caps on billed usage, Solvimon can also store [usage limits](/platform-guides/meter-and-event-design/usage-limits) per customer and fire threshold webhooks as consumption approaches them.

---

## Monthly token budgets

A monthly token budget limits how many tokens a customer can consume per billing period before being blocked or charged an overage rate.

### Define the feature

```bash
curl -X POST https://test.api.solvimon.com/v1/features \
  -H "X-API-KEY: <apiKey>" \
  -H "Content-Type: application/json" \
  -d '{
    "reference": "monthly_token_budget",
    "name": "Monthly Token Budget",
    "type": "NUMBER"
  }'
```

Assign per plan: Starter → `1000000`, Pro → `10000000`.

### Check usage and budget before each request

Query both the entitlement (the limit) and the current meter usage (what they've consumed so far):

```bash
# Get the entitlement value — GET /v1/customers/{ref}/entitlements
curl "https://test.api.solvimon.com/v1/customers/acme-corp/entitlements" \
  -H "X-API-KEY: <apiKey>"

# Get current period usage — GET /v1/ingest/meter-data
curl "https://test.api.solvimon.com/v1/ingest/meter-data?customer_reference=acme-corp&meter_reference=completion_tokens" \
  -H "X-API-KEY: <apiKey>"
```

Compare the two values. If usage ≥ budget, block the request and prompt the customer to upgrade.

---

## Model access tiers

Control which models are available on each plan using an `ENUM` type feature.

### Define the feature

```bash
curl -X POST https://test.api.solvimon.com/v1/features \
  -H "X-API-KEY: <apiKey>" \
  -H "Content-Type: application/json" \
  -d '{
    "reference": "available_models",
    "name": "Available Models",
    "type": "ENUM",
    "enum_values": [
      "gpt-4o",
      "gpt-4o-mini",
      "claude-3-5-sonnet",
      "claude-3-5-haiku"
    ]
  }'
```

### Assign per plan

* Starter: `["gpt-4o-mini", "claude-3-5-haiku"]`
* Pro: `["gpt-4o", "gpt-4o-mini", "claude-3-5-sonnet", "claude-3-5-haiku"]`

### Enforce at runtime

Query [GET /v1/customers/\{ref}/entitlements](https://docs.solvimon.com/api-docs/configuration-api/customers/get-customers-by-resource-id-or-reference-entitlements):

```bash
curl "https://test.api.solvimon.com/v1/customers/acme-corp/entitlements" \
  -H "X-API-KEY: <apiKey>"
```

```json
{
  "entitlements": [
    {
      "feature_reference": "available_models",
      "enums": ["gpt-4o-mini", "claude-3-5-haiku"]
    }
  ]
}
```

If the customer requests a model not in `enums`, return a `403` with a message indicating which plan tier includes that model.

---

## Feature flags (SWITCH type)

Use `SWITCH` features for binary capabilities: priority queue access, early access to new models, dedicated support.

```bash
curl -X POST https://test.api.solvimon.com/v1/features \
  -H "X-API-KEY: <apiKey>" \
  -H "Content-Type: application/json" \
  -d '{
    "reference": "priority_queue",
    "name": "Priority Queue",
    "type": "SWITCH"
  }'
```

Assign: Starter → `false`, Pro → `true`.

In your application:

```json
{
  "feature_reference": "priority_queue",
  "switch": true
}
```

Route requests to a high-priority queue if `switch: true`, otherwise to the standard queue.

---

## Overriding entitlements per customer

Enterprise customers often negotiate custom limits. You can override the plan default for a specific customer directly on their subscription without changing the pricing plan.

Use [PATCH /v1/pricing-plan-subscriptions/\{id}](https://docs.solvimon.com/api-docs/configuration-api/pricing-plan-subscriptions/patch-pricing-plan-subscriptions-by-resource-id) to set custom entitlement values on the subscription:

```bash
curl -X PATCH https://test.api.solvimon.com/v1/pricing-plan-subscriptions/<subscription_id> \
  -H "X-API-KEY: <apiKey>" \
  -H "Content-Type: application/json" \
  -d '{
    "entitlements": [
      {
        "feature_reference": "monthly_token_budget",
        "number": "100000000",
        "override": true
      }
    ]
  }'
```

Setting `override: true` means the subscription value takes precedence over the pricing plan default. The customer stays on their existing plan — only their entitlement values change.

---

## Summary

| Feature type | Use case                                         | Enforced by      |
| ------------ | ------------------------------------------------ | ---------------- |
| `NUMBER`     | Token budget, rate limit, max file size          | Your application |
| `ENUM`       | Model access tier, available regions             | Your application |
| `SWITCH`     | Priority queue, beta features, dedicated support | Your application |
| `AMOUNT`     | Dollar credit allowance                          | Your application |

All entitlement enforcement happens in your code. Solvimon provides a single endpoint to query what a customer is entitled to; your application decides what to do with that information. For billed usage, [usage limits](/platform-guides/meter-and-event-design/usage-limits) complement entitlements: Solvimon tracks consumption against a per-customer limit and fires threshold webhooks, so you don't have to poll to know when a customer approaches their cap.