Update a plan

Typescript (SDK)

import { Autumn } from 'autumn-js'

const autumn = new Autumn()

const result = await autumn.plans.update({
  planId: "pro_plan",
  name: "Pro Plan (Updated)",
  price: {
    amount: 15,
    interval: "month",
  },
});

from autumn_sdk import Autumn

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

res = autumn.plans.update(
    plan_id="pro_plan",
    name="Pro Plan (Updated)",
    price={
        "amount": 15,
        "interval": "month",
    },
    create_in_stripe=True,
    archived=False,
)

curl --request POST \
  --url https://api.useautumn.com/v1/plans.update \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'x-api-version: <x-api-version>' \
  --data '
{
  "plan_id": "pro_plan",
  "name": "Pro Plan (Updated)",
  "price": {
    "amount": 15,
    "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.update

Typescript (SDK)

import { Autumn } from 'autumn-js'

const autumn = new Autumn()

const result = await autumn.plans.update({
  planId: "pro_plan",
  name: "Pro Plan (Updated)",
  price: {
    amount: 15,
    interval: "month",
  },
});

from autumn_sdk import Autumn

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

res = autumn.plans.update(
    plan_id="pro_plan",
    name="Pro Plan (Updated)",
    price={
        "amount": 15,
        "interval": "month",
    },
    create_in_stripe=True,
    archived=False,
)

curl --request POST \
  --url https://api.useautumn.com/v1/plans.update \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'x-api-version: <x-api-version>' \
  --data '
{
  "plan_id": "pro_plan",
  "name": "Pro Plan (Updated)",
  "price": {
    "amount": 15,
    "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": {}
}

Updates an existing plan. By default, creates a new version of the plan. See Adding features to plans for item configuration.

Updates create a new plan version by default. Existing customers remain on their current version until their subscription renews or they explicitly upgrade.

Updating Items

When updating items, you must provide the complete items array. The new array replaces the existing configuration entirely. To update a single feature’s configuration while keeping others unchanged, include all existing items with the modified values.

Common Use Cases

await autumn.plans.update({
  planId: "pro_plan",
  price: { amount: 15, interval: "month" }
});

await autumn.plans.update({
  planId: "pro_plan",
  price: null // Removes the base price
});

await autumn.plans.update({
  planId: "pro_plan",
  items: [
    {
      featureId: "messages",
      included: 2000, // Increased from 1000
      reset: { interval: "month" }
    }
  ]
});

await autumn.plans.update({
  planId: "old_plan",
  archived: true
});

await autumn.plans.update({
  planId: "pro_plan",
  name: "Pro Plan (Updated)",
  newPlanId: "pro_plan_v2" // Optional: change the plan ID
});

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 update.

Minimum string length: 1

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

group

string

name

string

Display name of the plan.

Minimum string length: 1

description

string

add_on

boolean

Whether the plan is an add-on.

auto_enable

boolean

Whether the plan is automatically enabled.

price

BasePrice · object | null

The price of the plan. Set to null to remove the base price.

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

FreeTrialParams · object | null

The free trial of the plan. Set to null to remove the free trial.

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

version

number

archived

boolean

default:false

base_plan_id

string | null

The base plan this plan should be linked to as a variant. Set to null to detach it from its base plan.

Minimum string length: 1

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

new_plan_id

string

The new ID to use for the plan. Can only be updated if the plan has not been used by any customers.

Minimum string length: 1

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

disable_version

boolean

all_versions

boolean

Apply the update diff to all versions of this plan. Mutually exclusive with disable_version.

migration

object

Show child attributes

force_version

boolean

Force versioning even when no customers exist. Mutually exclusive with disable_version.

update_variant_ids

string[]

Variant plan IDs to apply this update to. Empty or omitted means no propagation.

update_license_parents

object[]

Parent plan versions that should receive this license-plan update.

Show child attributes

variants

object[]

Additive variant updates for this base plan. Missing variants are created when name is provided.

Show child attributes

is_default

boolean

Whether this is the org's default plan. Cannot be true on a variant.

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

Create a plan Delete a plan

⌘I

Billing

Balances

Customers

Authorization

Events

Entities

Plans

Features

Rewards & Referrals

Webhook Events

Platform (Beta)

Updating Items

Common Use Cases

Body Parameters

Response

Authorizations

Headers

Body

Response

​Updating Items

​Common Use Cases

​Body Parameters

​Response

Authorizations

Headers

Body

Response

Updating Items

Common Use Cases

Body Parameters

Response