Prepaid Pricing

Prepaid pricing lets customers pay for a fixed quantity of a feature upfront. They select how many units they want at purchase time, pay immediately, and their balance is decremented as they use it. This is in contrast to usage-based pricing, where customers are billed for actual usage at the end of a billing cycle.

Example
An AI platform has a Pro plan at $20/month that includes:

API Credits: 500 included for free, then $10 per 1,000 credits per month (consumable)

Seats: 3 included for free, then $5 per seat per month (non-consumable)

A customer selects 3,000 credits and 10 seats. They pay $20 base + $25 for 2,500 extra credits + $35 for 7 extra seats = $80/month.

Setting up

CLI
Dashboard

Create your features and add them to a plan with prepaid prices:

autumn.config.ts

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

export const apiCredits = feature({
  id: 'api_credits',
  name: 'API Credits',
  type: 'metered',
  consumable: true,
});

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: apiCredits.id,
      included: 500,
      price: {
        amount: 10,
        billingUnits: 1000,
        billingMethod: 'prepaid',
        interval: 'month',
      },
    }),
    item({
      featureId: seats.id,
      included: 3,
      price: {
        amount: 5,
        billingMethod: 'prepaid',
        interval: 'month',
      },
    }),
  ],
});

Push changes with atmn push.

Navigate to Plans and create or edit a plan
Add your features:
- A metered, consumable feature for credits (e.g., “API Credits”) — set an included amount (500), a price ($10 per 1,000 per month), and billing method Prepaid
- A metered, non-consumable feature for seats (e.g., “Seats”) — set an included amount (3), a price ($5 per seat per month), and billing method Prepaid
Save the plan

How it works

When a plan has prepaid features, customers select a quantity at purchase time. This quantity determines:

How many units are granted as their balance
How much they’re charged, based on the price and billing units

The quantity is the total number of feature units the customer will receive, including any included amount. Using our example plan:

A customer selects 3,000 API credits. 500 are included, so they pay for 2,500 → $10 × (2,500 / 1,000) = $25/month for credits.
The same customer selects 10 seats. 3 are included, so they pay for 7 → $5 × 7 = $35/month for seats.

If you pass a quantity equal to or less than the included amount, the customer gets the included amount and pays nothing extra for that feature.

Passing `feature_quantities`

When attaching a plan or updating a subscription that contains prepaid features, use the feature_quantities parameter to specify how many units the customer wants.

Attaching a plan

Pass a feature_quantities entry for each prepaid feature on the plan:

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: "api_credits", quantity: 3000 },
    { 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": "api_credits", "quantity": 3000 },
        { "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": "api_credits", "quantity": 3000 },
      { "feature_id": "seats", "quantity": 10 }
    ]
  }'

Updating a subscription

To change prepaid quantities on an existing subscription, use billing.update. For example, to add more seats mid-cycle:

await autumn.billing.update({
  customerId: "user_123",
  planId: "pro",
  featureQuantities: [
    { featureId: "api_credits", quantity: 3000 },
    { featureId: "seats", quantity: 15 },
  ],
});

await autumn.billing.update(
    customer_id="user_123",
    plan_id="pro",
    feature_quantities=[
        { "feature_id": "api_credits", "quantity": 3000 },
        { "feature_id": "seats", "quantity": 15 },
    ],
)

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

See Updating Subscriptions for more on previewing changes. When quantities change mid-cycle, Autumn can prorate the charge — see Proration for configuration options.

Understanding prepaid balances

Once a customer is attached to a plan with prepaid features, their balance breakdown distinguishes between what was included for free and what was purchased.

Field	Description
`included_grant`	The amount granted by the plan for free — the “included” amount configured on the plan item.
`prepaid_grant`	The amount purchased via `feature_quantities` — the quantity minus the included amount.
`granted`	Top-level total: `included_grant + prepaid_grant` summed across all breakdown items.
`remaining`	How much is left to use.
`usage`	How much has been consumed.

Using the plan from our setup, a customer who attaches with 3,000 credits and 10 seats will have:

{
  "api_credits": {
    "feature_id": "api_credits",
    "granted": 3000,
    "remaining": 3000,
    "usage": 0,
    "unlimited": false,
    "overage_allowed": false,
    "breakdown": [
      {
        "id": "cus_ent_abc123",
        "plan_id": "pro",
        "included_grant": 500,
        "prepaid_grant": 2500,
        "remaining": 3000,
        "usage": 0,
        "reset": {
          "interval": "month",
          "resets_at": 1773851121437
        },
        "price": {
          "amount": 10,
          "billing_units": 1000,
          "billing_method": "prepaid"
        },
        "expires_at": null
      }
    ]
  },
  "seats": {
    "feature_id": "seats",
    "granted": 10,
    "remaining": 10,
    "usage": 0,
    "unlimited": false,
    "overage_allowed": false,
    "breakdown": [
      {
        "id": "cus_ent_def456",
        "plan_id": "pro",
        "included_grant": 3,
        "prepaid_grant": 7,
        "remaining": 10,
        "usage": 0,
        "reset": null,
        "price": {
          "amount": 5,
          "billing_units": 1,
          "billing_method": "prepaid"
        },
        "expires_at": null
      }
    ]
  }
}

Use the check endpoint before allowing a customer to use a prepaid feature, and track usage afterwards to decrement their balance.

Prepaid vs usage-based

	Prepaid	Usage-based
When charged	Upfront at purchase	End of billing cycle
Customer selects quantity	Yes, via `feature_quantities`	No
Balance behavior	Decremented as usage occurs	Accumulated and billed
Best for	Credits, top-ups, seat licenses	Metered APIs, storage, bandwidth

Getting Started

Configure Pricing

Billing & Subscriptions

Customers

Additional Resources

Lakehouse

Prepaid Pricing

Setting up

How it works

Passing `feature_quantities`

Attaching a plan

Updating a subscription

Understanding prepaid balances

Prepaid vs usage-based

​Setting up

​How it works

​Passing feature_quantities

​Attaching a plan

​Updating a subscription

​Understanding prepaid balances

​Prepaid vs usage-based

Setting up

How it works

Passing `feature_quantities`

Attaching a plan

Updating a subscription

Understanding prepaid balances

Prepaid vs usage-based