Sub-Entity Plans

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.

Scenario	Approach
All seats get the same 50 credits/month	Sub-entity balances
Each seat can be Free or Pro tier	Sub-entity plans

Setting up

CLI
Dashboard

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

from autumn_sdk import Autumn

autumn = Autumn("am_sk_...")

await autumn.entities.create(
    customer_id="org_123",
    entity_id="workspace_a",
    feature_id="workspaces",
    name="Workspace A",
)

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

response = await autumn.billing.attach(
    customer_id="org_123",
    plan_id="workspace_pro",
    entity_id="workspace_a",
)

curl -X POST "https://api.useautumn.com/v1/billing.attach" \
  -H "Authorization: Bearer am_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "org_123",
    "plan_id": "workspace_pro",
    "entity_id": "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);

response = await autumn.check(
    customer_id="org_123",
    feature_id="requests",
    entity_id="workspace_a",
)

print(response.allowed)

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": "requests",
    "entity_id": "workspace_a"
  }'

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

await autumn.billing.attach(
    customer_id="org_123",
    plan_id="workspace_pro",
    entity_id="workspace_a",
)

curl -X POST "https://api.useautumn.com/v1/billing.attach" \
  -H "Authorization: Bearer am_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "org_123",
    "plan_id": "workspace_pro",
    "entity_id": "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",
});

await autumn.billing.update(
    customer_id="org_123",
    plan_id="workspace_pro",
    entity_id="workspace_a",
    cancel_action="cancel_end_of_cycle",
)

curl -X POST "https://api.useautumn.com/v1/billing.update" \
  -H "Authorization: Bearer am_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "org_123",
    "plan_id": "workspace_pro",
    "entity_id": "workspace_a",
    "cancel_action": "cancel_end_of_cycle"
  }'

Getting Started

Configure Pricing

Billing & Subscriptions

Customers

Additional Resources

Lakehouse

Sub-Entity Plans

When to use sub-entity plans

Setting up

Attaching plans to entities

Create the entity

Attach a plan to the entity

Checking and tracking per entity

Upgrading an entity’s plan

Cancelling an entity’s plan

​When to use sub-entity plans

​Setting up

​Attaching plans to entities

​Create the entity

​Attach a plan to the entity

​Checking and tracking per entity

​Upgrading an entity’s plan

​Cancelling an entity’s plan

When to use sub-entity plans

Setting up

Attaching plans to entities

Create the entity

Attach a plan to the entity

Checking and tracking per entity

Upgrading an entity’s plan

Cancelling an entity’s plan