Skip to main content
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

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",
});

​
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);

​
Track usage

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

​
Customer-level vs entity-level

LevelHow to useBehavior
Entity-levelPass entity_id in check/trackChecks/deducts from that entity’s individual balance
Customer-levelOmit entity_idReturns 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",
});