When you create a product in Autumn, you define what features your customers on that product get access to.

The entitled method returns the allowed property to check if a customer should have access to a feature, so you can block access or prompt them to upgrade.

​
Checking Metered Features

Before your customer uses a feature, you can check if the customer is allowed to use it and their current usage.

Example Use Case:

Let’s imagine you have a free product that allows 100 AI messages per month. Before your customer sends an AI message, you can check if they have any remaining messages.

If they still have messages remaining, they’ll be allowed to send an AI message. You can then record the usage event so Autumn can keep track of the balance.

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

{
  "allowed": true,
  "balances": [
    {
      "feature_id": "ai-messages",
      "balance": 100,
      "required": 1
    }
  ]
}

Even if your product doesn’t have usage limits (ie your product is purely usage-based), you can still use the above method to prevent excessive usage if a customer’s payment fails.

If the product status is past_due, by default, Autumn will block access to the feature.

​
Checking for a Required Quantity

If you know the quantity a user will consume in advance, you can specify it with the required_quantity parameter. This means you can prevent a user from starting a process that would consume more than their allowance.

By default, required_quantity is 1, so not passing this parameter will return allowed: true as long as the customer has a feature balance of 1 or more.

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

​
Checking Feature Access and Recording Usage together

In a typical workflow, you’ll want to check if a customer has access to a feature and then record the usage as separate steps.

However, you can check entitlement and record usage in a single API call using the send_event field. The usage value will be the required_quantity parameter.

curl -X POST "https://api.useautumn.com/v1/entitled" \
  -H "Authorization: Bearer am_sk_1234567890" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "user-123",
    "feature_id": "ai-messages",
    "required_quantity": 3,
    "send_event": true
  }'

We recommend doing these as separate steps in your application logic, so usage is only counted if the event is successful.

Alternatively, you can “refund” usage with a negative usage value if the event fails.

​
Checking Boolean Features

For simple on/off features, use the endpoint to determine if a customer has access.

You can do this on the client side on page load, using a useEffect function:

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

const { allowed } = await autumn.entitled({
  customer_id: "user-123",
  feature_id: "premium-dashboard",
});

{
  "allowed": true,
  "balances": [
    {
      "feature_id": "premium-dashboard",
      "balance": null,
      "required": null
    }
  ]
}