Skip to main content
Credit systems let you track actions with different credit costs from a single balance pool. A credit system is made up of a list of features that can draw from it, and a credit cost per unit of usage for each feature.
Example
You have a Pro plan that gives users 100 basic messages per month, and 10 premium messages per month. These 2 balances are separate and independent of each other. To give your users more flexibility, you instead decide to use a credit system, where:
  • basic message: costs 1 credit per message
  • premium message: costs 10 credits per message
Instead of having 2 separate balances for each message type, your Pro plan can have 200 credits per month. Your users can use the credits in any combination of basic and premium messages they want.

​
Creating a credit system

Make sure you have some metered features created before creating a credit system.
  1. Navigate to the features page, under Products.
  2. Click “Create Credit System”
  3. Add the features that can draw from this credit system.
  4. For each feature, define how many credits each unit of usage should cost (eg, 3 credits per “premium request”).
  5. Click “Create”
ExampleIf each premium_request is worth 3 credits, then using 6 premium requests will cost 18 credits.
Now you can add this credit system to a plan, such as granting 50 credits per month or charging $1 per credit.

​
Tracking and limiting credit usage

When implementing a credit system into your application, you should interact with the underlying features — not the credit system itself. This means passing in the underlying feature_id when checking or tracking usage.

​
Checking access

Before allowing a customer to use a feature, check if they have enough credits to do so. If each “premium request” is worth 3 credits, then this example will check if the customer has at least 18 credits remaining. 
import { Autumn } from "autumn-js";

const autumn = new Autumn({
  secretKey: 'am_sk_42424242',
});

const { data } = await autumn.check({
  customer_id: "user_or_org_id_from_auth",
  feature_id: "premium_request",
  required_balance: 6,
});
In this case, we have a balance of 100 credits remaining, so we’re allowed to use our 6 “premium requests” feature.
If a feature is not defined in the credit system, it will returnallowed: false

​
Tracking usage

Since the customer has sufficient credits, you can let them use their 6 “premium requests”. Afterwards, you can track the usage to update their balance. This will decrement the customer’s balance by 18 credits (6 requests * 3 credits per request). 
import { Autumn } from "autumn-js";

const autumn = new Autumn({
  secretKey: 'am_sk_42424242',
});

await autumn.track({
  customer_id: "user_or_org_id_from_auth",
  feature_id: "premium_request",
  value: 6,
});
Since the customer started with a balance of 100 credits, and used 18 credits, their remaining balance is 82 credits.

​
Monetary credits

You may want your credit system to represent a monetary value: eg, $10 of credits. To implement this, you can map each credit to a cent value (eg, 1 credit = 1 cent).
  1. When creating your credit system, define credit amounts in the per-cent cost
Eg: if each premium_request costs 3 cents, our credit cost should be 3.
  1. When adding the credits to a plan, set the granted amount of credits in cents
Eg, if customers get 5 USD credits for free, they should have an included usage of 500.
  1. When charging for the credits, set the cost of each credit to 1 cent
See the credits pricing guide for a more detailed example of setting up a monetary credits system

Credits Example

​
FAQs

No — you typically want one balance, and you grant it from two different plan items:
  • Monthly subscription grant: credits with interval: "month" (these reset/expire each month).
  • One-time top-ups: credits with interval: "one_off" / one-off prepaid (these never reset)
  • One-off credits: do not have a reset, so they don’t need rollover.
  • Rollover: only applies to recurring grants (eg, monthly). If rollover is enabled, any unused credits at reset time are carried into the next interval. Over time, this can make the balance grow month-to-month.
Only if you want Autumn to manage the mapping from actions → credit cost.
  • If you already compute “credits consumed” in your app, you can skip credit systems and just track a single consumable feature like credits.