Skip to main content
When you create a plan in Autumn, you define what features your customers on that plan get access to. The check method returns the allowed field in real-time to check if a customer should have access to a feature. You can use this to block access and prompt an upsell.

​
The allowed field

The allowed field will return true for a given feature if:
  • The customer has an active plan with this feature
  • The customer has an active plan with a credit_system that grants this feature
  • The plan feature is included or prepaid, and the current balance is greater than the required_balance parameter
  • The plan feature is usage-based, and the user has not exceeded their max spend limit
  • The plan feature is unlimited or a boolean feature
Under these conditions, you should allow your customer to use the feature. You can then record the usage event so Autumn can update the allowed field as necessary.
The customer must already exist before calling check. If the customer_id doesn’t match an existing customer, the API returns a customer_not_found error. Create customers using customers.getOrCreate during signup or login.

​
Checking metered features

Before your customer uses a feature, you can check if the customer is allowed to use it and their current usage.
ExampleLet’s imagine you have a free plan for a chatbot that allows 5 messages per month. Before your customer sends an AI message, you can check if they have any left.If they still have messages remaining, they’ll be allowed to send an AI message.
import { useCustomer } from "autumn-js/react";

const { check } = useCustomer();

// check the customer state object locally (no API call)
const { allowed } = check({ featureId: "messages" });
Even if your product doesn’t have usage limits (ie your feature is purely usage-based), you can still use the above method to prevent usage if a customer’s payment fails.

​
Checking for a required balance

If you know the balance a user will consume in advance, you can specify it with the requiredBalance parameter. This means you can prevent a user from starting a process that would consume more than their current balance. By default, requiredBalance is 1, so not passing this parameter will return allowed: true as long as the customer has a feature balance of 1 or more. 
import { useCustomer } from "autumn-js/react";

const { check } = useCustomer();

const { allowed } = check({ featureId: "messages", requiredBalance: 3 });

​
Checking and tracking atomically

You can check access and record usage in a single, atomic API call using the sendEvent field. The usage value deducted from the balance will be the requiredBalance parameter. This is useful for concurrent events. 
import { Autumn } from "autumn-js";

const autumn = new Autumn({ secretKey: "am_sk_test_1234" });

const response = await autumn.customers.check({
  customerId: "user_123",
  featureId: "api_calls",
  requiredBalance: 3,
  sendEvent: true,
});

console.log(response.allowed);
If the operation fails, you can then “refund” the usage with a negative usage value in the track endpoint. 
import { Autumn } from "autumn-js";

const autumn = new Autumn({ secretKey: "am_sk_test_1234" });

await autumn.customers.track({
  customerId: "user_123",
  featureId: "api_calls",
  value: -3,
});

​
Checking boolean features

For simple on/off features, use the check method to determine if a customer has access:
React
const { check } = useCustomer();

const { allowed } = check({ featureId: "premium-dashboard" });

if (allowed) {
  // Show premium dashboard
}

​
Feature flags in customer responses

Boolean features are also returned as a flags object on customer and entity API responses. This lets you check on/off feature access directly from the customer object without calling the check endpoint separately. 
{
  "balances": {
    "credits": { "featureId": "credits", "granted": 1000, "remaining": 800, "usage": 200 }
  },
  "flags": {
    "premiumDashboard": {
      "id": "cus_ent_abc123",
      "planId": "pro_plan",
      "expiresAt": null,
      "featureId": "premiumDashboard"
    }
  }
}
  • Flags are separate from balances — boolean features appear under flags, while metered and credit system features remain under balances
  • Each flag shows which planId it originates from and when it expires
  • Use expand: ["flags.feature"] to include the full feature object on each flag
const customer = await autumn.customers.getOrCreate({
  customerId: "user_123",
  expand: ["flags.feature"],
});

if (customer.flags?.["premiumDashboard"]) {
  // Customer has the premium dashboard feature
}