Sign in

v1

latestOpenAPI 3.1.02026-07-265817860.8 KB
plans

Create a plan

Creates a new plan with optional base price and feature configurations.

Use this to programmatically create pricing plans. See How plans work for concepts.

post/v1/plans.create

Headers

x-api-versionstring required

Request body

plan_idstring required

The ID of the plan to create.

groupstring

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

namestring required

Display name of the plan.

descriptionstring nullable

Optional description of the plan.

add_onboolean

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

auto_enableboolean

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

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

Example request

{
  "plan_id": "free_plan",
  "name": "Free",
  "auto_enable": true,
  "items": [
    {
      "feature_id": "messages",
      "included": 100,
      "reset": {
        "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": {}
}