Overview

Entitlements define which features each subscription plan includes. They work alongside feature flags to control commercial access to features.

Base URL

/api/platform/entitlements

NOTE

These endpoints require authentication with a Super Admin account.

---

Endpoints

List Entitlement Features

GET /api/platform/entitlements/features

Returns all defined entitlement features.

Response 200 OK

[
  {
    "id": "ai_generation",
    "name": "AI Content Generation",
    "type": "BOOLEAN",
    "category": null,
    "defaultEnabled": false,
    "defaultValue": null
  },
  {
    "id": "ai_website_analysis",
    "name": "Website Analysis",
    "type": "NUMBER",
    "category": "ai_refinement",
    "defaultEnabled": false,
    "defaultValue": 0
  }
]

---

Create Entitlement Feature

POST /api/platform/entitlements/features

Request Body

{
  "id": "custom_branding",
  "name": "Custom Branding",
  "description": "Allow custom logo and colors",
  "type": "boolean",
  "category": "appearance",
  "defaultEnabled": false,
  "defaultValue": null
}

Field	Type	Required	Description
id	string	✅	Code-defined ID (used in code checks)
name	string	✅	Human-readable name
description	string	❌	Feature description
type	string	❌	boolean or number (default: boolean)
category	string	❌	Grouping category
defaultEnabled	boolean	❌	Default enabled state
defaultValue	number	❌	Default numeric value

Response 201 Created

---

List Packages

GET /api/platform/entitlements/packages

Returns all subscription packages for the entitlements matrix.

Response 200 OK

[
  { "id": "pkg-1", "name": "free" },
  { "id": "pkg-2", "name": "starter" },
  { "id": "pkg-3", "name": "professional" },
  { "id": "pkg-4", "name": "enterprise" }
]

---

List Plan Entitlements

GET /api/platform/entitlements/plans

Returns the full entitlements matrix (all package-feature mappings).

Response 200 OK

[
  {
    "id": "pe-123",
    "packageId": "pkg-1",
    "featureId": "ai_generation",
    "enabled": true,
    "value": -1
  },
  {
    "id": "pe-456",
    "packageId": "pkg-1",
    "featureId": "ai_website_analysis",
    "enabled": true,
    "value": 1
  }
]

Field	Type	Description
enabled	boolean	Whether feature is enabled for this plan
value	number	Numeric limit. -1 = unlimited, 0 = disabled

---

Update Plan Entitlement

PUT /api/platform/entitlements/plans/:packageId/:featureId

Parameters

Name	Type	Description
packageId	string	Package/plan ID
featureId	string	Entitlement feature ID

Request Body

{
  "enabled": true,
  "value": 50
}

Field	Type	Required	Description
enabled	boolean	✅	Whether feature is enabled
value	number	❌	Numeric limit (default: -1 for unlimited)

Response 200 OK - Updated entitlement object

---

Checking Entitlements in Code

Boolean Entitlements

import { FeatureAccessService } from '../services/featureAccessService.js';

const hasAccess = await FeatureAccessService.checkEntitlement(
  'advanced_analytics',
  companyId
);

Numeric Entitlements (AI Usage)

import { entitlementsService } from '../services/entitlements.service.js';

// Check if action is allowed and get remaining usage
const result = await entitlementsService.checkAIAction(
  companyId,
  'WEBSITE_ANALYSIS'
);
// Returns: { allowed: true, remaining: 5, limit: 10, used: 5 }

// Get complete usage summary
const summary = await entitlementsService.getUsageSummary(companyId);

---

Entitlement Value Conventions

Value	Meaning
-1	Unlimited
0	Disabled / No access
1	Enabled (for boolean types)
> 1	Numeric limit (for number types)

---

Seeded Entitlement Features

The following entitlements are seeded by default:

ID	Name	Type
ai_generation	AI Content Generation	boolean
advanced_analytics	Advanced Analytics	boolean
team_collaboration	Team Collaboration	boolean
ai_posts_limit	Monthly AI Posts Limit	number
social_accounts_limit	Social Accounts Limit	number
docs.client	Docs: Client	boolean
docs.api	Docs: API	boolean
docs.internal	Docs: Internal	boolean
docs.ai	Docs: AI	boolean
ai_website_analysis	Website Analysis	number
ai_field_analysis	Field Analysis	number
ai_one_shot_refinement	One-Shot Refinement	number
ai_chat_sessions	Chat Sessions	number
ai_chat_messages_per_session	Messages Per Chat Session	number

---

See Also

• Platform Console Overview
• Feature Flags API
• Segments API