Entitlements Overview

Billing vs Entitlements

Usage-based billing and feature access control are distinct concerns that are often managed in separate systems. ABAXUS brings them together under one roof, because they share the same source of truth: the price plan.

Billing answers: “How much does this customer owe for the usage they’ve generated this period?”

Entitlements answer: “Is this customer allowed to use this feature right now?”

Both answers change when a customer’s subscription changes — and with ABAXUS, they change atomically. When a subscription is created, amended, or cancelled, the entitlements associated with that subscription’s plan version are immediately reflected in the entitlements API. No separate sync step, no eventual consistency lag.

The 3 Entitlement Types

Every entitlement is declared on a price plan as a key-value pair of a specific type:

Boolean

A feature flag that is either true (granted) or false (not granted). Use this for features that are simply on or off: advanced analytics, API access, specific integrations, priority support.

1

{ "feature_key": "advanced_analytics", "type": "boolean", "value": true }

When resolved for a customer, this returns { "granted": true } or { "granted": false }.

Limit

A numeric ceiling on how much of something a customer can use. Use this for API rate limits, seat counts, storage quotas, monthly active user caps, or any other bounded resource.

1

{ "feature_key": "api_calls_per_month", "type": "limit", "value": 100000 }

When resolved, this returns the limit value and the customer’s current usage so you can calculate remaining capacity:

1
2
3
4
5
6
7
8
9

{
  "feature_key": "api_calls_per_month",
  "type": "limit",
  "limit": 100000,
  "current_usage": 47293,
  "remaining": 52707,
  "granted": true,
  "exceeded": false
}

Custom

An arbitrary string value for configuration that varies by plan tier. Use this for AI model tier selection (gpt-4o vs gpt-3.5-turbo), support SLA definitions (4h vs 24h), geographic restrictions, or any plan-specific configuration your product needs.

1

{ "feature_key": "ai_model_tier", "type": "custom", "value": "gpt-4o" }

Custom entitlements give you a clean way to drive plan-dependent behavior in your product without hardcoding plan names in your service logic.

How Entitlements Are Declared

Entitlements are declared in the entitlements array when creating a price plan:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

curl -X POST "$ABAXUS_URL/v1/price-plans" \
  -H "Authorization: Bearer $ABAXUS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "plan_growth",
    "name": "Growth",
    "entitlements": [
      { "feature_key": "advanced_analytics", "type": "boolean", "value": true },
      { "feature_key": "api_calls_per_month", "type": "limit", "value": 100000 },
      { "feature_key": "export_formats", "type": "boolean", "value": false },
      { "feature_key": "support_tier", "type": "custom", "value": "email" },
      { "feature_key": "ai_model", "type": "custom", "value": "gpt-3.5-turbo" }
    ]
  }'

Entitlements are part of the plan version and are immutable like charges. To change entitlements, create a new plan version.

Multi-Subscription Resolution

Customers can have multiple active subscriptions simultaneously — for example, a base platform subscription and a premium add-on. When you query entitlements for a customer with multiple active subscriptions, ABAXUS resolves them using type-specific merge logic:

This resolution model means customers automatically get the union of their entitlements across all active plans, which matches the natural expectation: buying an add-on should expand your access, not require a plan migration.

Entitlements and Plan Versions

Like charges, entitlements are pinned to the plan version at subscription time. If you update a plan’s entitlement definitions in a new version, existing subscriptions continue to use the entitlements from their pinned version. Customers are not affected by plan updates until their subscription is migrated to the new version.

This means you can raise or lower limits in new plan versions without inadvertently affecting existing customers. It also means you must use subscription amendments to roll out entitlement changes to existing subscribers.