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.

To start, add the feature entity as a product item in the Autumn dashboard.

  1. Go to the Products Page and click into the product you want to add a feature entity to.
  2. Click the ”+ Feature” button.
  3. Select the feature to track (eg, credits)
  4. Click the elipsis on the right of the feature selector and click “Add per Feature Entity”
  5. Select the entity you want to add (eg, per user_id)
  6. Define any included usage (eg, 500 credits per user) and add the product item.

​
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.

curl -X POST "https://api.useautumn.com/v1/customers/org_123/entities" \
-H "Authorization: Bearer am_sk_1234567890" \
-H "Content-Type: application/json" \
-d '{
"feature_id": "seats",
"id": "user_abc",
"name": "Brandon Yeo"
}'

{
  "success": true
}

​
Managing entity balances

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

​
Check feature access

curl -X POST "https://api.useautumn.com/v1/check" \
-H "Authorization: Bearer am_sk_1234567890" \
-H "Content-Type: application/json" \
-d '{
"customer_id": "org_123",
"feature_id": "ai-messages",
"entity_id": "user_abc"
}'

​
Send usage event

curl -X POST "https://api.useautumn.com/v1/track" \
-H "Authorization: Bearer am_sk_1234567890" \
-H "Content-Type: application/json" \
-d '{
"customer_id": "org_123",
"feature_id": "ai-messages",
"entity_id": "user_abc",
"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 use case

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.

curl -X POST "https://api.useautumn.com/v1/check" \
-H "Authorization: Bearer am_sk_1234567890" \
-H "Content-Type: application/json" \
-d '{
"customer_id": "org_123",
"feature_id": "ai-messages"
}'

And similarly for usage events.

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.

curl -X POST "https://api.useautumn.com/v1/track" \
-H "Authorization: Bearer am_sk_1234567890" \
-H "Content-Type: application/json" \
-d '{
"customer_id": "org_123",
"feature_id": "ai-messages",
"value": 10
}'

​
Deleting Entities

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

curl -X DELETE "https://api.useautumn.com/v1/customers/org_123/entities/user_abc" \
-H "Authorization: Bearer am_sk_1234567890" \
-H "Content-Type: application/json" \

{
  "success": true,
}