Create a plan

Typescript (SDK)

import { Autumn } from 'autumn-js'

const autumn = new Autumn()

const result = await autumn.plans.create({
  planId: "free_plan",
  name: "Free",
  autoEnable: true,
  items: [
    {
      featureId: "messages",
      included: 100,
      reset: {
        interval: "month",
      },
    },
  ],
});

from autumn_sdk import Autumn

autumn = Autumn(secret_key="am_sk_test...")

res = autumn.plans.create(
    plan_id="free_plan",
    name="Free",
    group="",
    add_on=False,
    auto_enable=True,
    items=[
        {
            "feature_id": "messages",
            "included": 100,
            "reset": {
                "interval": "month",
            },
        },
    ],
    create_in_stripe=True,
)

curl --request POST \
  --url https://api.useautumn.com/v1/plans.create \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'x-api-version: <x-api-version>' \
  --data '
{
  "plan_id": "free_plan",
  "name": "Free",
  "auto_enable": true,
  "items": [
    {
      "feature_id": "messages",
      "included": 100,
      "reset": {
        "interval": "month"
      }
    }
  ]
}
'

{
  "id": "pro",
  "name": "Pro Plan",
  "description": null,
  "group": null,
  "version": 1,
  "addOn": false,
  "autoEnable": false,
  "price": {
    "amount": 10,
    "interval": "month",
    "display": {
      "primaryText": "$10",
      "secondaryText": "per month"
    }
  },
  "items": [
    {
      "featureId": "messages",
      "included": 100,
      "unlimited": false,
      "reset": {
        "interval": "month"
      },
      "price": {
        "amount": 0.5,
        "interval": "month",
        "billingUnits": 100,
        "billingMethod": "usage_based",
        "maxPurchase": null
      },
      "display": {
        "primaryText": "100 messages",
        "secondaryText": "then $0.5 per 100 messages"
      }
    },
    {
      "featureId": "users",
      "included": 0,
      "unlimited": false,
      "reset": null,
      "price": {
        "amount": 10,
        "interval": "month",
        "billingUnits": 1,
        "billingMethod": "prepaid",
        "maxPurchase": null
      },
      "display": {
        "primaryText": "$10 per Users"
      }
    }
  ],
  "createdAt": 1771513979217,
  "env": "sandbox",
  "archived": false,
  "baseVariantId": null,
  "config": {
    "ignore_past_due": false
  },
  "billing_controls": {},
  "metadata": {}
}

POST

plans.create

Typescript (SDK)

import { Autumn } from 'autumn-js'

const autumn = new Autumn()

const result = await autumn.plans.create({
  planId: "free_plan",
  name: "Free",
  autoEnable: true,
  items: [
    {
      featureId: "messages",
      included: 100,
      reset: {
        interval: "month",
      },
    },
  ],
});

from autumn_sdk import Autumn

autumn = Autumn(secret_key="am_sk_test...")

res = autumn.plans.create(
    plan_id="free_plan",
    name="Free",
    group="",
    add_on=False,
    auto_enable=True,
    items=[
        {
            "feature_id": "messages",
            "included": 100,
            "reset": {
                "interval": "month",
            },
        },
    ],
    create_in_stripe=True,
)

curl --request POST \
  --url https://api.useautumn.com/v1/plans.create \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'x-api-version: <x-api-version>' \
  --data '
{
  "plan_id": "free_plan",
  "name": "Free",
  "auto_enable": true,
  "items": [
    {
      "feature_id": "messages",
      "included": 100,
      "reset": {
        "interval": "month"
      }
    }
  ]
}
'

{
  "id": "pro",
  "name": "Pro Plan",
  "description": null,
  "group": null,
  "version": 1,
  "addOn": false,
  "autoEnable": false,
  "price": {
    "amount": 10,
    "interval": "month",
    "display": {
      "primaryText": "$10",
      "secondaryText": "per month"
    }
  },
  "items": [
    {
      "featureId": "messages",
      "included": 100,
      "unlimited": false,
      "reset": {
        "interval": "month"
      },
      "price": {
        "amount": 0.5,
        "interval": "month",
        "billingUnits": 100,
        "billingMethod": "usage_based",
        "maxPurchase": null
      },
      "display": {
        "primaryText": "100 messages",
        "secondaryText": "then $0.5 per 100 messages"
      }
    },
    {
      "featureId": "users",
      "included": 0,
      "unlimited": false,
      "reset": null,
      "price": {
        "amount": 10,
        "interval": "month",
        "billingUnits": 1,
        "billingMethod": "prepaid",
        "maxPurchase": null
      },
      "display": {
        "primaryText": "$10 per Users"
      }
    }
  ],
  "createdAt": 1771513979217,
  "env": "sandbox",
  "archived": false,
  "baseVariantId": null,
  "config": {
    "ignore_past_due": false
  },
  "billing_controls": {},
  "metadata": {}
}

Creates a new plan with optional base price and feature configurations. See How plans work for concepts and Adding features to plans for item configuration.

Plan Configuration

A plan consists of:

Base price - optional recurring charge for the plan itself
Items - feature configurations defining what customers get and how they’re billed

Configuring Items

Each item in the items array configures a single feature. There are two types: Consumable features (API calls, messages, credits):

Set included for free units that reset each period
Set reset.interval to define when balance resets to included
Optionally add price for usage beyond included amount

Non-consumable features (seats, storage):

Set included for the base allocation
Do NOT set reset - usage persists across billing cycles
Use billing_method: "prepaid" for upfront payment per unit

Multiple Currencies

To sell a plan in currencies beyond your organization’s default, set additional_currencies on the base price, a feature price, or each tier of a tiered price. Amounts are explicit per currency - no exchange rates are applied - and tier boundaries stay the same across currencies. See Plans for how customers are matched to a currency.

Common Use Cases

await autumn.plans.create({
  planId: "free_plan",
  name: "Free",
  autoEnable: true, // Automatically attached on customer creation
  items: [
    {
      featureId: "messages",
      included: 100,
      reset: { interval: "month" }
    }
  ]
});

await autumn.plans.create({
  planId: "pro_plan",
  name: "Pro Plan",
  price: { amount: 10, interval: "month" },
  items: [
    {
      featureId: "messages",
      included: 1000,
      reset: { interval: "month" },
      price: {
        amount: 0.01,
        interval: "month",
        billingUnits: 1,
        billingMethod: "usage_based"
      }
    }
  ]
});

await autumn.plans.create({
  planId: "team_plan",
  name: "Team Plan",
  price: { amount: 49, interval: "month" },
  items: [
    {
      featureId: "seats",
      included: 5,
      // No reset - seats persist across billing cycles
      price: {
        amount: 10,
        interval: "month",
        billingUnits: 1,
        billingMethod: "prepaid"
      }
    }
  ]
});

await autumn.plans.create({
  planId: "analytics_addon",
  name: "Advanced Analytics",
  addOn: true, // Can be attached alongside other plans
  price: { amount: 20, interval: "month" }
});

await autumn.plans.create({
  planId: "api_plan",
  name: "API Plan",
  items: [
    {
      featureId: "api_calls",
      included: 1000,
      reset: { interval: "month" },
      price: {
        tiers: [
          { to: 10000, amount: 0.001 },
          { to: 100000, amount: 0.0005 },
          { to: "inf", amount: 0.0001 }
        ],
        interval: "month",
        billingUnits: 1,
        billingMethod: "usage_based"
      }
    }
  ]
});

await autumn.plans.create({
  planId: "premium_plan",
  name: "Premium",
  price: { amount: 99, interval: "month" },
  freeTrial: {
    durationLength: 14,
    durationType: "day",
    cardRequired: true
  }
});

Body Parameters

Response

{
  "id": "pro",
  "name": "Pro Plan",
  "description": null,
  "group": null,
  "version": 1,
  "addOn": false,
  "autoEnable": false,
  "price": {
    "amount": 10,
    "interval": "month",
    "display": {
      "primaryText": "$10",
      "secondaryText": "per month"
    }
  },
  "items": [
    {
      "featureId": "messages",
      "included": 100,
      "unlimited": false,
      "reset": {
        "interval": "month"
      },
      "price": {
        "amount": 0.5,
        "interval": "month",
        "billingUnits": 100,
        "billingMethod": "usage_based",
        "maxPurchase": null
      },
      "display": {
        "primaryText": "100 messages",
        "secondaryText": "then $0.5 per 100 messages"
      }
    },
    {
      "featureId": "users",
      "included": 0,
      "unlimited": false,
      "reset": null,
      "price": {
        "amount": 10,
        "interval": "month",
        "billingUnits": 1,
        "billingMethod": "prepaid",
        "maxPurchase": null
      },
      "display": {
        "primaryText": "$10 per Users"
      }
    }
  ],
  "createdAt": 1771513979217,
  "env": "sandbox",
  "archived": false,
  "baseVariantId": null,
  "config": {
    "ignore_past_due": false
  },
  "billing_controls": {},
  "metadata": {}
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

x-api-version

string

default:2.3.0

required

Body

application/json

plan_id

string

required

The ID of the plan to create.

Minimum string length: 1

Pattern: ^[a-zA-Z0-9_-]+$

name

string

required

Display name of the plan.

Minimum string length: 1

group

string

default:""

Group identifier for organizing related plans. Plans in the same group are mutually exclusive.

description

string | null

Optional description of the plan.

add_on

boolean

default:false

If true, this plan can be attached alongside other plans. Otherwise, attaching replaces existing plans in the same group.

auto_enable

boolean

default:false

If true, plan is automatically attached when a customer is created. Use for free tiers.

price

object

Base recurring price for the plan. Omit for free or usage-only plans.

Show child attributes

items

PlanItem · object[]

Feature configurations for this plan. Each item defines included units, pricing, and reset behavior.

Show child attributes

licenses

object[]

Plans offered as assignable licenses under this plan. The full set replaces existing links.

Show child attributes

free_trial

object

Free trial configuration. Customers can try this plan before being charged.

Show child attributes

config

object

Miscellaneous plan-level configuration flags.

Show child attributes

billing_controls

object

Plan-level billing controls used as customer defaults.

Show child attributes

metadata

object

Arbitrary key-value metadata defined by you for your own use (e.g. UI copy, feature highlights). Values can be any JSON-serializable value. Shared across all versions of the plan.

Show child attributes

create_in_stripe

boolean

default:true

Response

200 - application/json

A plan defines a set of features, pricing, and entitlements that can be attached to customers.

string

required

Unique identifier for the plan.

name

string

required

Display name of the plan.

description

string | null

required

Optional description of the plan.

group

string | null

required

Group identifier for organizing related plans. Plans in the same group are mutually exclusive.

version

number

required

Version number of the plan. Incremented when plan configuration changes.

add_on

boolean

required

Whether this is an add-on plan that can be attached alongside a main plan.

auto_enable

boolean

required

If true, this plan is automatically attached when a customer is created. Used for free plans.

price

object | null

required

Base recurring price for the plan. Null for free plans or usage-only plans.

Show child attributes

items

object[]

required

Feature configurations included in this plan. Each item defines included units, pricing, and reset behavior for a feature.

Show child attributes

created_at

number

required

Unix timestamp (ms) when the plan was created.

env

enum<string>

required

Environment this plan belongs to ('sandbox' or 'live').

Available options:

sandbox,

live

archived

boolean

required

Whether the plan is archived. Archived plans cannot be attached to new customers.

base_variant_id

string | null

required

Deprecated. Use variant_details.base_plan_id instead. If this is a variant, the ID of the base plan it was created from.

config

object

required

Miscellaneous plan-level configuration flags.

Show child attributes

metadata

object

required

Arbitrary key-value metadata defined by you for your own use. Shared across all versions of the plan.

Show child attributes

free_trial

object

Free trial configuration. If set, new customers can try this plan before being charged.

Show child attributes

variant_details

object

Details about how this variant relates to its latest base plan.

Show child attributes

billing_controls

object

Plan-level billing controls used as customer defaults.

Show child attributes

customer_eligibility

object

Show child attributes

List all plans Update a plan

⌘I

Billing

Balances

Customers

Authorization

Events

Entities

Plans

Features

Rewards & Referrals

Webhook Events

Platform (Beta)

Plan Configuration

Configuring Items

Multiple Currencies

Common Use Cases

Body Parameters

Response

Authorizations

Headers

Body

Response

​Plan Configuration

​Configuring Items

​Multiple Currencies

​Common Use Cases

​Body Parameters

​Response

Authorizations

Headers

Body

Response

Plan Configuration

Configuring Items

Multiple Currencies

Common Use Cases

Body Parameters

Response