Per-Unit Pricing

Per-unit pricing charges customers based on the quantity of a resource they use — seats, workspaces, environments, or any other non-consumable feature. Customers either commit to a quantity upfront (prepaid) or are billed based on actual usage at the end of each billing cycle (usage-based).

Example
A collaboration tool charges $10/seat/month. The plan includes 5 seats for free, and each additional seat costs $10.

Setting up

CLI
Dashboard

Create a non-consumable metered feature and add it to a plan with a per-unit price:

autumn.config.ts

import { feature, item, plan } from 'atmn';

export const seats = feature({
  id: 'seats',
  name: 'Seats',
  type: 'metered',
  consumable: false,
});

export const pro = plan({
  id: 'pro',
  name: 'Pro',
  price: { amount: 20, interval: 'month' },
  items: [
    item({
      featureId: seats.id,
      included: 5,
      price: {
        amount: 10,
        interval: 'month',
        billingMethod: 'usage_based',
      },
    }),
  ],
});

Push changes with atmn push.

Navigate to Plans and create or edit a plan
Add a metered, non-consumable feature (e.g., “Seats”)
Set an included amount (e.g., 5 seats for free)
Add a price per unit (e.g., $10 per seat per month)
Choose the billing method:
- Prepaid — customer selects quantity at checkout, charged upfront
- Usage-based — billed for actual usage at end of billing cycle
Under Advanced, configure proration behavior for mid-cycle changes
Save the plan

Billing methods

Method	When charged	Quantity	Best for
Prepaid	Upfront at purchase	Customer selects a fixed quantity	Seat licenses with committed counts
Usage-based	End of billing cycle (prorated on changes)	Automatic — tracks actual usage	Seats that fluctuate frequently

Prepaid per-unit

With prepaid, the customer selects a total quantity when purchasing. The quantity includes any free included amount — Autumn subtracts the included amount and charges for the remainder. For example, with 5 included seats at $10/extra seat, a customer who selects quantity: 10 gets 10 seats total and pays for 5 extra seats ($50/month). Pass the quantity via featureQuantities:

import { Autumn } from "autumn-js";

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

const { data } = await autumn.billing.attach({
  customerId: "user_123",
  planId: "pro",
  featureQuantities: [{
    featureId: "seats",
    quantity: 10,
  }],
});

from autumn_sdk import Autumn

autumn = Autumn("am_sk_...")

response = await autumn.billing.attach(
    customer_id="user_123",
    plan_id="pro",
    feature_quantities=[{
        "feature_id": "seats",
        "quantity": 10,
    }],
)

curl -X POST "https://api.useautumn.com/v1/billing/attach" \
  -H "Authorization: Bearer am_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "user_123",
    "plan_id": "pro",
    "feature_quantities": [{
      "feature_id": "seats",
      "quantity": 10
    }]
  }'

The customer’s balance is set to the total quantity (10). If they’re upgrading and already have seats in use, the existing usage is carried over — so a customer with 3 seats in use would see a remaining balance of 7.

Autumn does not prevent you from passing a quantity lower than the customer’s current usage. If the customer has 5 seats in use and you pass quantity: 3, the balance goes negative (-2). The check endpoint will return allowed: false, preventing new seats from being added, but existing seats are not forcibly removed.

Usage-based per-unit

With usage-based billing, no quantity is needed at purchase time. Track seat additions and removals as they happen, and Autumn bills for the actual number of seats in use.

import { Autumn } from "autumn-js";

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

// Add a seat
await autumn.track({
  customer_id: "user_123",
  feature_id: "seats",
  value: 1,
});

// Remove a seat
await autumn.track({
  customer_id: "user_123",
  feature_id: "seats",
  value: -1,
});

from autumn_sdk import Autumn

autumn = Autumn("am_sk_...")

# Add a seat
await autumn.track(
    customer_id="user_123",
    feature_id="seats",
    value=1,
)

# Remove a seat
await autumn.track(
    customer_id="user_123",
    feature_id="seats",
    value=-1,
)

# Add a seat
curl -X POST "https://api.useautumn.com/v1/track" \
  -H "Authorization: Bearer am_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "user_123",
    "feature_id": "seats",
    "value": 1
  }'

When a customer purchases the plan, any seats already in use are automatically reflected in their subscription from day one. For example, if a customer has 3 seats in use and purchases a plan with 5 included seats at $10/extra seat:

Their balance starts at 5 (the included amount)
The 3 existing seats are carried over, leaving a remaining balance of 2
No extra charge yet — they’re within the included amount
As they add seats beyond 5, each additional seat is billed at $10/month with proration

Existing usage on upgrade

When a customer upgrades from one plan to another, Autumn automatically carries over their current seat usage to the new plan. This ensures there’s no gap in tracking — existing seats don’t disappear or go unbilled.

Prepaid

The customer’s balance is set to their chosen quantity. Existing usage is then deducted from that balance.

Example: Customer has 3 seats in use. They purchase a plan with 5 included seats, passing quantity: 10.

Balance is set to 10 (5 included + 5 purchased)

3 existing seats are deducted → 7 remaining

Stripe charges for 10 seats (with 5 in the free tier)

Usage-based

No quantity is needed. The Stripe subscription quantity is set to the customer’s current usage automatically.

Example: Customer has 3 seats in use. They purchase a plan with 5 included seats at $10/extra seat.

Balance starts at 5 (included amount)

3 existing seats are deducted → 2 remaining

Stripe subscription reflects 3 seats in use (within the free tier, so no extra charge)

When they add a 6th seat, billing begins at $10/seat for the overage

Scenario	Prepaid (qty: 8)	Usage-based
3 in use, 5 included	Balance: 8 → 5 remaining. Charged for 3 extra.	Balance: 5 → 2 remaining. No extra charge.
3 in use, 0 included	Balance: 8 → 5 remaining. Charged for 8.	Balance: 0 → -3. Charged for 3 seats.
7 in use, 5 included	Balance: 8 → 1 remaining. Charged for 3 extra.	Balance: 5 → -2. Charged for 2 extra seats.

Checking access

Before allowing a user to add a new seat, check if they have capacity:

const { data } = await autumn.check({
  customer_id: "user_123",
  feature_id: "seats",
});

if (!data.allowed) {
  // Prompt user to purchase more seats or upgrade
}

response = await autumn.check(
    customer_id="user_123",
    feature_id="seats",
)

if not response.allowed:
    # Prompt user to purchase more seats or upgrade

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

For prepaid, allowed is true when the customer has remaining prepaid balance (ie. unused seats). For usage-based, allowed is true as long as the customer has a usage-based price configured — additional seats are simply billed at the per-unit rate, so there’s no hard cap.

Proration on quantity changes

When a customer increases or decreases their seat count mid-billing-cycle, you can configure how the price adjustment is handled. See Proration for details.

Getting Started

Configure Pricing

Billing & Subscriptions

Customers

Additional Resources

Lakehouse

Per-Unit Pricing

Setting up

Billing methods

Prepaid per-unit

Usage-based per-unit

Existing usage on upgrade

Prepaid

Usage-based

Checking access

Proration on quantity changes

​Setting up

​Billing methods

​Prepaid per-unit

​Usage-based per-unit

​Existing usage on upgrade

​Prepaid

​Usage-based

​Checking access

​Proration on quantity changes

Setting up

Billing methods

Prepaid per-unit

Usage-based per-unit

Existing usage on upgrade

Prepaid

Usage-based

Checking access

Proration on quantity changes