Skip to main content
Sub-entity plans let you attach different subscription tiers to individual entities (users, workspaces, projects) under a parent customer. Each entity can be on a different plan with its own features and billing, while the parent customer handles payment.
Example
A company manages multiple workspaces. Each workspace can be on a different tier — Workspace A is on the Free tier (100 requests/month), while Workspace B is on the Pro tier (10,000 requests/month). Both are billed to the parent organization.

​
When to use sub-entity plans

Use sub-entity plans when entities under a customer need different plan tiers. If all entities get the same features and limits, use sub-entity balances instead.
ScenarioApproach
All seats get the same 50 credits/monthSub-entity balances
Each seat can be Free or Pro tierSub-entity plans

​
Setting up

Create your plans as normal — no special entity configuration needed on the plan itself. The entity-level attachment happens at runtime via the API.
autumn.config.ts
import { feature, item, plan } from 'atmn';

export const requests = feature({
  id: 'requests',
  name: 'API Requests',
  type: 'metered',
  consumable: true,
});

export const workspaceFree = plan({
  id: 'workspace_free',
  name: 'Workspace Free',
  group: 'workspace',
  items: [
    item({
      featureId: requests.id,
      included: 100,
      reset: { interval: 'month' },
    }),
  ],
});

export const workspacePro = plan({
  id: 'workspace_pro',
  name: 'Workspace Pro',
  group: 'workspace',
  price: { amount: 20, interval: 'month' },
  items: [
    item({
      featureId: requests.id,
      included: 10000,
      reset: { interval: 'month' },
    }),
  ],
});
Push changes with atmn push.

​
Attaching plans to entities

First, create the entity. Then attach a plan to it by passing the entity_id in the attach call:

​
Create the entity

import { Autumn } from "autumn-js";

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

await autumn.entities.create({
  customerId: "org_123",
  entityId: "workspace_a",
  featureId: "workspaces",
  name: "Workspace A",
});

​
Attach a plan to the entity

const response = await autumn.billing.attach({
  customerId: "org_123",
  planId: "workspace_pro",
  entityId: "workspace_a",
});
Each entity’s subscription is created separately in Stripe, with billing cycles synced to the parent customer.

​
Checking and tracking per entity

Pass the entity_id to scope check and track calls to a specific entity: 
const { data } = await autumn.check({
  customer_id: "org_123",
  feature_id: "requests",
  entity_id: "workspace_a",
});

console.log(data.allowed);

​
Upgrading an entity’s plan

To upgrade or downgrade an entity, attach the new plan with the same entity_id. The same upgrade/downgrade logic applies: 
await autumn.billing.attach({
  customerId: "org_123",
  planId: "workspace_pro",
  entityId: "workspace_a",
});

​
Cancelling an entity’s plan

Use billing.update with cancelAction to cancel an entity’s plan. The same cancel/uncancel behavior applies. 
await autumn.billing.update({
  customerId: "org_123",
  planId: "workspace_pro",
  entityId: "workspace_a",
  cancelAction: "cancel_end_of_cycle",
});