Entitlements & Plans

Endpoints for managing AI entitlements, subscription plans, and billing information.

GET /api/ai-entitlements

Get comprehensive AI entitlements for the tenant, including plans, seats, and usage.

Authentication: permission.tenant.superuser

Response:

{
  "plans": [
    {
      "id": "everyday-123",
      "name": "Everyday AI",
      "slug": "everyday",
      "tier": "everyday",
      "weeklyBudget": 0.50,
      "sessionBudget": 0.10,
      "purchasable": true,
      "seats": {
        "total": 25,
        "assigned": 20,
        "unassigned": 5
      }
    },
    {
      "id": "advanced-456",
      "name": "Advanced AI",
      "slug": "advanced",
      "tier": "advanced",
      "weeklyBudget": 2.00,
      "sessionBudget": 0.40,
      "purchasable": true,
      "seats": {
        "total": 10,
        "assigned": 8,
        "unassigned": 2
      }
    }
  ],
  "totalSeats": 35,
  "assignedSeats": 28,
  "weeklyUsage": 12.45,
  "monthlyUsage": 48.32,
  "lastRefresh": "2024-01-15T14:00:00Z"
}

Entitlement Properties:

Field	Type	Description
plans	array	Available AI plans
totalSeats	integer	Total seats across all plans
assignedSeats	integer	Seats currently assigned to users
weeklyUsage	number	Total usage this week (USD)
monthlyUsage	number	Total usage this month (USD)
lastRefresh	date	Last sync with License Manager

---

POST /api/ai-entitlements/_refresh

Force refresh of AI entitlements from License Manager.

Authentication: permission.tenant.superuser

Response:

{
  "refreshed": true,
  "plansUpdated": 3,
  "seatsUpdated": 35,
  "timestamp": "2024-01-15T14:30:00Z"
}

Use Cases:

• Sync after purchasing new seats
• Verify subscription changes
• Troubleshoot entitlement issues

Automatic Refresh

Entitlements are automatically refreshed every 15 minutes. Manual refresh is typically unnecessary unless immediate synchronization is required.

---

GET /api/ai-plans

List all AI plans available to the tenant.

Authentication: permission.tenant.superuser

Query Parameters:

Parameter	Type	Default	Description
includeSeats	boolean	false	Include seat counts per plan

Response:

{
  "_links": {
    "self": { "href": "/api/ai-plans" }
  },
  "_embedded": {
    "inf:ai-plan": [
      {
        "id": "everyday-123",
        "name": "Everyday AI",
        "slug": "everyday",
        "tier": "everyday",
        "icon": "star",
        "weeklyBudget": 0.50,
        "sessionBudget": 0.10,
        "purchasable": true,
        "billingCycle": "monthly",
        "pricePerSeat": 10.00,
        "currency": "USD",
        "seats": {
          "total": 25,
          "assigned": 20,
          "unassigned": 5
        }
      }
    ]
  },
  "start": 0,
  "count": 1,
  "total": 1
}

Plan Properties:

Field	Type	Description
id	string	Unique plan ID
name	string	Display name
slug	string	URL-safe identifier
tier	string	Model tier: everyday, advanced, strategic
icon	string	Icon identifier
weeklyBudget	number	Weekly budget per seat (USD)
sessionBudget	number	Per-session budget (USD, 6-hour window)
purchasable	boolean	Can purchase additional seats
billingCycle	string	monthly, annual
pricePerSeat	number	Cost per seat per billing cycle
currency	string	Currency code (e.g., USD)
seats	object	Seat counts (if includeSeats=true)

---

GET /api/ai-plans/{id}

Get detailed information about a specific AI plan, including seat assignments.

Authentication: permission.tenant.superuser

Pre-blocks:

• plan.lookup
• permission.tenant.superuser

Response:

{
  "id": "advanced-456",
  "name": "Advanced AI",
  "slug": "advanced",
  "tier": "advanced",
  "icon": "sparkles",
  "weeklyBudget": 2.00,
  "sessionBudget": 0.40,
  "purchasable": true,
  "billingCycle": "monthly",
  "pricePerSeat": 25.00,
  "currency": "USD",
  "seats": {
    "total": 10,
    "assigned": 8,
    "unassigned": 2,
    "assignments": [
      {
        "username": "alice",
        "displayName": "Alice Smith",
        "assignedAt": "2024-01-10T09:00:00Z",
        "assignedBy": "admin",
        "weeklyCostUsed": 1.23,
        "sessionCostUsed": 0.15
      }
    ]
  },
  "models": [
    {
      "id": "claude-3-5-sonnet",
      "name": "Claude 3.5 Sonnet",
      "tier": "advanced"
    }
  ]
}

---

GET /api/ai-subscriptions

Fetch AI subscriptions from License Manager.

Authentication: permission.tenant.superuser

Query Parameters:

Parameter	Type	Description
planSlug	string	Filter by plan slug
billingCycle	string	Filter by billing cycle: monthly, annual
status	string	Filter by status: active, canceled, expired

Response:

{
  "subscriptions": [
    {
      "id": "sub-123",
      "tenantId": "tenant-456",
      "planSlug": "advanced",
      "billingCycle": "monthly",
      "status": "active",
      "quantity": 10,
      "startDate": "2024-01-01T00:00:00Z",
      "endDate": null,
      "nextBillingDate": "2024-02-01T00:00:00Z",
      "pricePerSeat": 25.00,
      "totalAmount": 250.00,
      "currency": "USD"
    }
  ]
}

Subscription Properties:

Field	Type	Description
id	string	Subscription ID
tenantId	string	Tenant identifier
planSlug	string	Plan identifier
billingCycle	string	Billing frequency
status	string	Subscription status
quantity	integer	Number of seats
startDate	date	Subscription start
endDate	date	Subscription end (null for ongoing)
nextBillingDate	date	Next billing date
pricePerSeat	number	Cost per seat
totalAmount	number	Total subscription cost
currency	string	Currency code

Use Cases:

• Display billing information
• Verify subscription status
• Audit seat allocations
• Forecast costs

License Manager Integration

Subscription data is fetched directly from License Manager and represents the source of truth for billing. Changes made through License Manager may take up to 15 minutes to reflect in Informer.