Skip to main content
When customers use features in your product, you’ll need to record their usage so Autumn can track it against their limits or bill them for usage. There are two ways to record usage: sending events or setting usage directly.

​
Sending Events

The track route is recommended for tracking consumable features, like AI messages, credits or API calls. Each time a customer uses a feature, send an event to count their usage.
Before recording usage, you may want to check if the customer is allowed to use the feature. This prevents them from exceeding usage limits defined in the product.
import { Autumn as autumn } from "autumn-js";

await autumn.track({
  customer_id: "user-123",
  feature_id: "ai-messages",
  value: 1,
});

{
"message": "Event recorded successfully",
"event_id": "event_123",
"customer_id": "user-123",
"feature_id": "ai-messages"
}
You can also send a negative value to increase the balance counter, which is useful for increasing a feature limit (eg, if a customer removes a seat).

​
Setting Usage Directly

For non-consumable features (such as seats or workspaces), you may prefer to set usage directly, rather than incrementing Autumn’s feature balance. This enables you to sync a source of truth up on your side with Autumn, preventing any discrepancies. 
import { Autumn as autumn } from "autumn-js";

await autumn.usage({
  customer_id: "user-123",
  feature_id: "seats",
  value: 3,
});

{
  "message": "Usage set successfully",
  "customer_id": "user-123",
  "feature_id": "seats"
}
The usage route overwrites the current usage value. Use this carefully, as it can reset or override incremental usage recorded through events.

​
Using Event Names

In the above examples, we used the feature_id to identify the feature. You can instead use the event_name parameter to link balances to different events in your application. This can be useful when:
  • Multiple balances are affected by the same user action
  • Different user actions should be tracked against the same balance
Example Use Case:Your AI chatbot has a daily limit of 10 messages, with a maximum monthly limit of 100 messages. Recording a message in Autumn should decrease both balances simultaneously.In Autumn, you can create two features: daily-messages and monthly-messages. You can add the same event name to both features: message-sent. Then, assign both features to a plan with the correct included amounts.Every time that event name is recorded, both the daily-messages and monthly-messages balances will be decremented.If you were to use the same feature for both in this case, the daily and monthly balances would sum, allowing the user to send 10 messages a day, with an “overage” balance of 100 messages per month if they go over the daily limit.
You can define event names in the Autumn dashboard:
  1. Go to the Features Page.
  2. Click on the feature you want to add an event to.
  3. In the sheet, under the “advanced” section, add your event names.
  4. Save the feature.
You can then record usage for these events from your application: 
import { Autumn as autumn } from "autumn-js";

await autumn.track({
  customer_id: "user-123",
  value: 1,
  event_name: "blog_post_generation",
});

{
  "message": "Event recorded successfully",
  "event_id": "event_123",
  "customer_id": "user-123",
  "event_name": "blog_post_generation"
}
You can only use one of event_name or feature_id when recording usage. Check that you’re sending the correct one in the request, especially if you’re using a mix of snake_case and kebab-case.