Entity-level balances

Grant usage limits per entity, such as 50 credits per user per month

Entities are a resource that lives under a parent customer, that can have it’s own plans and feature balances.

Entity-level balances let you set usage limits that apply to each entity (like users, workspaces, or projects) individually. Instead of a single shared pool, each entity gets their own balance.

This is useful when you want to ensure fair usage across team members or isolate resource consumption per workspace.

Example case

We have an AI meeting notes product with team-based pricing:

• Team plan: $30 per seat per month
• Each seat gets: 50 meeting summaries per month

If a team has 8 users, they pay $30 \times 8 = $240/month, and each user gets their own 50 summaries.

Configure Pricing

1. Create Features

   Create two features:

   1. Seats - A metered non-consumable feature to track team members
   2. Meeting Summaries - A metered consumable feature for the number of meeting summaries generated
2. Create Team Plan

   Create a Team plan with:

   1. A $30/month base price
   2. Seats: 1 included, then $30/seat for additional (usage-based)
   3. Meeting Summaries: 50 per month, linked to the Seats feature as a per-entity feature, under “Advanced”

   The key configuration is setting the meeting summaries feature to point to “seats”. When the entity is created, this creates a per-entity balance where each seat gets 50 summaries.

   

Implementation

1. Create an Autumn Customer

   When an organization signs up, create an Autumn customer.

   React

   import { useCustomer } from "autumn-js/react";
   
   const App = () => {
     const { customer } = useCustomer();
   
     console.log("Autumn customer:", customer);
   
     return <h1>Welcome, {customer?.name || "user"}!</h1>;
   };
   
2. Create Initial Entity

   Create an entity for the admin user who is signing up. Since no plan is attached yet, this just registers the entity — no balance is granted yet. This should be done server-side for security.

   Node.js

   import { Autumn } from "autumn-js";
   
   const autumn = new Autumn({
     secretKey: 'am_sk_42424242',
   });
   
   // Create entity for the initial admin user
   await autumn.entities.create("org_123", {
     id: "user_admin",
     name: "Admin User",
     feature_id: "seats",
   });
   

   Since no plan is attached yet, this entity exists but has no balances. Once the Team plan is attached, this entity will automatically receive its 50 meeting summaries.

3. Attach the Team Plan

   When the customer upgrades to Team, attach the plan. The checkout URL will show the $30 base price.

   React

   import { useCustomer, CheckoutDialog } from "autumn-js/react";
   
   export default function UpgradeButton() {
     const { checkout } = useCustomer();
   
     return (
       <button
         onClick={async () => {
           await checkout({
             productId: "team",
             dialog: CheckoutDialog,
           });
         }}
       >
         Upgrade to Team
       </button>
     );
   }
   
4. Create Entities (Seats)

   When team members are added, create entities. This tracks seat usage and initializes their per-entity balance.

   This will also bill the customer a prorated amount for the seat price. You can configure this proration behavior (full vs prorated, immediately vs next cycle) in the “Advanced” section of the plan feature when editing the plan.

   Node.js

   import { Autumn } from "autumn-js";
   
   const autumn = new Autumn({
     secretKey: 'am_sk_42424242',
   });
   
   // Create entities for team members
   await autumn.entities.create("org_123", [
     { id: "user_alice", name: "Alice Smith", feature_id: "seats" },
     { id: "user_bob", name: "Bob Jones", feature_id: "seats" },
     { id: "user_charlie", name: "Charlie Brown", feature_id: "seats" },
   ]);
   

   Creating an entity automatically increments the seat count. If you create 4 entities, your seat usage will be 4.

   After you create an entity, navigate to the Autumn customer page, and you will see it created at the top of the page.

5. Check Access Per Entity

   Before generating a meeting summary, check if that specific user has remaining balance.

   React

   import { useEntity } from "autumn-js/react";
   
   function MeetingSummaryButton({ meetingId }: { meetingId: string }) {
     // Pass the current user's entity ID
     const { allowed, check } = useEntity("user_alice");
   
     const handleSummarize = async () => {
       const { data } = await check({ featureId: "meeting_summaries" });
   
       if (!data?.allowed) {
         alert("You've used all your meeting summaries this month");
         return;
       }
   
       // Generate the summary
       await generateSummary(meetingId);
     };
   
     return <button onClick={handleSummarize}>Summarize Meeting</button>;
   }
   

   Show check response (entity-level)

   {
     "allowed": true,
     "customer_id": "org_123",
     "feature_id": "meeting_summaries",
     "entity_id": "user_alice",
     "balance": 47,
     "usage": 3,
     "included_usage": 50,
     "unlimited": false
   }
   
6. Track Usage Per Entity

   When a user generates a summary, track the usage against their entity.

   React

   import { useEntity } from "autumn-js/react";
   
   const { track } = useEntity("user_alice");
   
   // After generating a meeting summary
   await track({
     featureId: "meeting_summaries",
     value: 1,
   });
   
7. Check Customer-level Balance (Optional)

   You can also check the total balance across all entities, useful for admin dashboards.

   Node.js

   import { Autumn } from "autumn-js";
   
   const autumn = new Autumn({
     secretKey: 'am_sk_42424242',
   });
   
   // Check total balance across all users (omit entity_id)
   const { data } = await autumn.check({
     customer_id: "org_123",
     feature_id: "meeting_summaries",
   });
   
   // With 3 users at 50 each = 150 total
   console.log(`Team has ${data.balance} total summaries remaining`);
   

   Show check response (customer-level)

   {
     "allowed": true,
     "customer_id": "org_123",
     "feature_id": "meeting_summaries",
     "balance": 141,
     "usage": 9,
     "included_usage": 150,
     "unlimited": false
   }
   

   The total is the sum of all entity balances (3 users × 50 = 150 included).

8. Remove Entities

   When a team member leaves, delete their entity. This decrements seat usage and removes their balance.

   It will also create a pro-rated refund for the seat price. You can configure this proration behavior in the “Advanced” section of the plan feature when editing the plan.

   Node.js

   import { Autumn } from "autumn-js";
   
   const autumn = new Autumn({
     secretKey: 'am_sk_42424242',
   });
   
   // Remove Bob from the team
   await autumn.entities.delete("org_123", "user_bob");
   

   Deleting an entity automatically decrements the seat count. The customer’s total meeting summary balance will also decrease accordingly.

Summary

Level	Check/Track With	Use Case
Entity-level	entity_id: "user_alice"	Individual user limits, fair usage
Customer-level	No entity_id	Admin dashboards, total consumption

Entity-level balances are ideal when you want to:

• Ensure fair usage across team members
• Isolate consumption per workspace or project
• Bill per-entity while providing entity-specific limits