Skip to main content
POST
/
v1
/
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",
  },
});
{
  "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
}
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" }
});

​
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
}

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.1
required

Body

application/json
​
plan_id
string
required

The ID of the plan to update.

Minimum string length: 1
​
group
string
default:""

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

​
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

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

​
items
PlanItem · object[]

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

​
free_trial
FreeTrialParams · object

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

​
version
number
​
archived
boolean
default:false
​
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

Response

200 - application/json

OK

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

​
id
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
required

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

​
items
object[]
required

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

​
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

If this is a variant, the ID of the base plan it was created from.

​
free_trial
object

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