Entitlements & Usage Metering

Entitlements define what features and resource limits a tenant has access to based on their subscription plan. Usage metering tracks consumption against those limits.

Entitlement Types

Type	Description	Example
boolean	Feature on/off toggle	api_access: true, webhooks: true
metered	Numeric limit with usage tracking	max_products: 5, api_calls_monthly: 100000
plan	Plan-specific entitlement from plan_entitlements table	Seeded during provisioning

How Entitlements Are Assigned

1. During provisioning (Stage 6): Default entitlements are seeded from the plan's plan_entitlements records plus config defaults
2. On plan change: Entitlements are recalculated based on the new plan
3. Admin override: Tenant-specific overrides can be applied via feature flags

Checking Entitlements

API Endpoint: POST /v1/integration/entitlements/check

curl -X POST https://api.validonx.com/api/v1/integration/entitlements/check \
  -H "X-API-Key: VX-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"entitlement_codes": ["webhooks", "api_access"]}'

Response:

{
  "data": {
    "webhooks": { "entitled": true, "type": "boolean", "value": true },
    "api_access": { "entitled": true, "type": "boolean", "value": true }
  },
  "meta": { "request_id": "uuid", "api_version": "1" }
}

Usage Metering

Recording usage: POST /v1/integration/usage/record

curl -X POST https://api.validonx.com/api/v1/integration/usage/record \
  -H "X-API-Key: VX-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"metric": "api_calls", "value": 1}'

Usage events are stored in the tenant database (usage_events table) and aggregated into usage_snapshots for reporting.

Plan Limits

Feature	Starter	Pro	Enterprise
Products	1	5	Unlimited
License keys	100	Unlimited	Unlimited
Activations	500	Unlimited	Unlimited
API calls/month	10,000	100,000	Unlimited
Webhooks	1 endpoint	5 endpoints	Unlimited

Rate Limiting Integration

Usage-based rate limits (Layer 4) enforce plan quotas. When a tenant approaches their monthly limit:

• At 80%: notification triggered (if configured)
• At 100%: requests return 429 RATE_LIMIT.EXCEEDED

Enterprise plans with unlimited quotas bypass usage-based rate limiting.