Sign in

v1

latestOpenAPI 3.1.02026-07-265817860.8 KB
plans

Update a plan

Updates an existing plan. Creates a new version unless disableVersion is set.

Use this to modify plan properties, pricing, or feature configurations. See Adding features to plans for item configuration.

post/v1/plans.update

Headers

x-api-versionstring required

Request body

plan_idstring required

The ID of the plan to update.

groupstring
namestring

Display name of the plan.

descriptionstring
add_onboolean

Whether the plan is an add-on.

auto_enableboolean

Whether the plan is automatically enabled.

metadataobject

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.

create_in_stripeboolean
versionnumber
archivedboolean
base_plan_idstring nullable

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

new_plan_idstring

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

disable_versionboolean
all_versionsboolean

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

force_versionboolean

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

update_variant_idsstring[]

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

is_defaultboolean

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

Example request

{
  "plan_id": "pro_plan",
  "name": "Pro Plan (Updated)",
  "price": {
    "amount": 15,
    "interval": "month"
  }
}

Response

OK

idstring required

Unique identifier for the plan.

namestring required

Display name of the plan.

descriptionstring nullable required

Optional description of the plan.

groupstring nullable required

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

versionnumber required

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

add_onboolean required

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

auto_enableboolean required

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

created_atnumber required

Unix timestamp (ms) when the plan was created.

env'sandbox' | 'live' required

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

archivedboolean required

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

base_variant_idstring nullable required

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

metadataobject required

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

Example 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": {}
}