Feature entities are used to keep track of sub-balances for a feauture. For example, you may have a product that allows 500 credits per user per month.

​
Product setup

There are two ways you can handle entities depending on your use case.

  1. Entity product items: this is the simplest way of handling entities, and keeps everything under 1 subscription.
  2. Attaching a product to an entity: if an entity can have its own subscription tiers, then you can attach a product directly at the entity level by passing the entity ID into an attach function. Each will be under its own subscription in Stripe with the billing cycles synced.

Example

Max has a team product, where each seat under the team gets access to 30 meeting note summaries per month. Since his seats all cost the same and get access to the same features, he can create a product with entity items.

Jamie’s also has a team product, but each user can either be under a Free tier or a Pro tier, where the pro tier gives the seat access to more meeting note summaries. In this case, Jamie can create a free tier and pro tier as normal, without entity items, and just attach these products at the entity level.

​
Creating entities

You can manage feature entities via the entities route. This can be used to create, update and delete entities, such as when a seat or workspace is added or removed.

When you create an entity, a usage event will automatically be sent that increments the count of the number of entities (eg seats) being used.

This means if you create 2 entities for “seats”, your usage of “seats” will be 2, allowing Autumn to bill accordingly if there’s a price set.

Creating an entity is only a required step if the entity is billable (eg if there’s a price per seat). If the entities don’t have an associated price, then you can skip this step and auto-create it from the check and track functions.

import { useCustomer } from "autumn-js/react";

const { createEntity } = useCustomer();

const { data, error } = await createEntity({
  id: "user_abc",
  name: "John Doe",
  featureId: "seats",
});

​
Managing entity balances

Just like with normal features, you can check feature access and track usage events for each entity.

​
Check feature access

import { useEntity } from "autumn-js/react";

const { allowed } = useEntity("user_abc");

if (allowed({ featureId: "ai-messages" })) {
  console.log("User has access to AI messages");
}

​
Send usage event

import { useEntity } from "autumn-js/react";

const { track } = useEntity("user_abc");

track({ featureId: "ai-messages", value: 10 });

​
Customer-level vs entity-level balances

A customer-level balances is the total balance for the feature across all entities. Entity-level balances are the balance for a specific entity. You can check access and track usage events either at the customer-level or entity-level.

Example

You have a product that allows 500 credits per user per month. However, the credits are shared across all users in the account.

You can create a feature entity for “seats” and then check access and send usage events at the top-level.

To use top-level balances, just omit the entity_id from your check request.

This will increment the usage counter for the top-level balance, and also deduct from the first-created entity so that the sum of the the entity balances is always the same as the top-level balance.

​
Deleting Entities

Just as creating an entity sent a usage event for the associated feature, deleting an entity will decrease the usage.

import { Autumn as autumn } from "autumn-js";

await autumn.entities.delete("org_123", "user_abc");