Sub-Entity Balances

Sub-entity balances let you set usage limits that apply to each entity (user, workspace, project, etc.) individually under a parent customer. Instead of a single shared pool, each entity gets its own independent balance.

Example
A team plan costs $30/seat/month. Each seat gets 50 AI meeting summaries per month. If a team has 5 users, each user has their own balance of 50 summaries — they can’t use each other’s allocation.

Setting up

CLI
Dashboard

Create features for both the entity count (e.g., seats) and the per-entity feature (e.g., summaries). Then link them via entityFeatureId on the plan item:

autumn.config.ts

import { feature, item, plan } from 'atmn';

export const seats = feature({
  id: 'seats',
  name: 'Seats',
  type: 'metered',
  consumable: false,
});

export const summaries = feature({
  id: 'summaries',
  name: 'Meeting Summaries',
  type: 'metered',
  consumable: true,
});

export const team = plan({
  id: 'team',
  name: 'Team',
  price: { amount: 30, interval: 'month' },
  items: [
    item({
      featureId: seats.id,
      included: 1,
      price: {
        amount: 30,
        interval: 'month',
        billingUnits: 1,
        billingMethod: 'usage_based',
      },
    }),
    item({
      featureId: summaries.id,
      included: 50,
      reset: { interval: 'month' },
      entityFeatureId: seats.id,
    }),
  ],
});

The entityFeatureId links the summaries feature to the seats feature — each seat (entity) will receive its own balance of 50 summaries.Push changes with atmn push.

Creating entities

When a new team member joins, create an entity. This automatically increments the entity feature count (e.g., seats) and provisions the per-entity balance:

import { Autumn } from "autumn-js";

const autumn = new Autumn({ secretKey: "am_sk_..." });

await autumn.entities.create({
  customerId: "org_123",
  entityId: "user_alice",
  featureId: "seats",
  name: "Alice",
});

from autumn_sdk import Autumn

autumn = Autumn("am_sk_...")

await autumn.entities.create(
    customer_id="org_123",
    entity_id="user_alice",
    feature_id="seats",
    name="Alice",
)

curl -X POST "https://api.useautumn.com/v1/entities" \
  -H "Authorization: Bearer am_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "org_123",
    "entity_id": "user_alice",
    "feature_id": "seats",
    "name": "Alice"
  }'

Checking and tracking per entity

Pass the entity_id to check and track to operate on a specific entity’s balance:

Check access

const { data } = await autumn.check({
  customer_id: "org_123",
  feature_id: "summaries",
  entity_id: "user_alice",
});

console.log(data.allowed);
console.log(data.balance);

response = await autumn.check(
    customer_id="org_123",
    feature_id="summaries",
    entity_id="user_alice",
)

print(response.allowed)
print(response.balance)

curl -X POST "https://api.useautumn.com/v1/check" \
  -H "Authorization: Bearer am_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "org_123",
    "feature_id": "summaries",
    "entity_id": "user_alice"
  }'

Track usage

await autumn.track({
  customer_id: "org_123",
  feature_id: "summaries",
  entity_id: "user_alice",
  value: 1,
});

await autumn.track(
    customer_id="org_123",
    feature_id="summaries",
    entity_id="user_alice",
    value=1,
)

curl -X POST "https://api.useautumn.com/v1/track" \
  -H "Authorization: Bearer am_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "org_123",
    "feature_id": "summaries",
    "entity_id": "user_alice",
    "value": 1
  }'

Customer-level vs entity-level

Level	How to use	Behavior
Entity-level	Pass `entity_id` in check/track	Checks/deducts from that entity’s individual balance
Customer-level	Omit `entity_id`	Returns the total balance across all entities

When tracking at the customer level (without entity_id), usage is deducted from the first-created entity to keep entity-level totals in sync with the customer-level total.

Deleting entities

When a team member leaves, delete the entity. This decrements the entity feature count and removes their balance:

await autumn.entities.delete({
  customerId: "org_123",
  entityId: "user_alice",
});

await autumn.entities.delete(
    customer_id="org_123",
    entity_id="user_alice",
)

curl -X DELETE "https://api.useautumn.com/v1/entities/user_alice" \
  -H "Authorization: Bearer am_sk_..." \
  -H "Content-Type: application/json" \
  -d '{ "customer_id": "org_123" }'

Getting Started

Configure Pricing

Billing & Subscriptions

Customers

Additional Resources

Lakehouse

Sub-Entity Balances

Setting up

Creating entities

Checking and tracking per entity

Check access

Track usage

Customer-level vs entity-level

Deleting entities

​Setting up

​Creating entities

​Checking and tracking per entity

​Check access

​Track usage

​Customer-level vs entity-level

​Deleting entities

Setting up

Creating entities

Checking and tracking per entity

Check access

Track usage

Customer-level vs entity-level

Deleting entities