> ## Documentation Index
> Fetch the complete documentation index at: https://docs.useautumn.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/documentation/pricing/plans) for concepts.

export const DynamicResponseExample = ({json, statusCode = "200"}) => {
  const toCamelCase = str => {
    return str.replace(/_([a-z])/g, (_, c) => c.toUpperCase());
  };
  const convertKeysToCamelCase = obj => {
    if (Array.isArray(obj)) {
      return obj.map(item => convertKeysToCamelCase(item));
    }
    if (obj !== null && typeof obj === "object") {
      return Object.keys(obj).reduce((acc, key) => {
        const camelKey = toCamelCase(key);
        acc[camelKey] = convertKeysToCamelCase(obj[key]);
        return acc;
      }, {});
    }
    return obj;
  };
  const [isTypeScript, setIsTypeScript] = useState(() => {
    if (typeof window !== "undefined") {
      try {
        const lang = localStorage.getItem("code");
        return JSON.parse(lang) === "typescript";
      } catch {
        return true;
      }
    }
    return true;
  });
  useEffect(() => {
    const onMintlifyStorage = event => {
      if (event.detail?.key === "code") {
        try {
          const value = JSON.parse(event.detail.value);
          setIsTypeScript(value === "typescript");
        } catch {}
      }
    };
    const pollInterval = setInterval(() => {
      try {
        const lang = localStorage.getItem("code");
        const value = JSON.parse(lang);
        setIsTypeScript(value === "typescript");
      } catch {}
    }, 300);
    document.addEventListener("mintlify-localstorage", onMintlifyStorage);
    return () => {
      document.removeEventListener("mintlify-localstorage", onMintlifyStorage);
      clearInterval(pollInterval);
    };
  }, []);
  const camelCaseJson = useMemo(() => convertKeysToCamelCase(json), [json]);
  const snakeCaseString = JSON.stringify(json, null, 2);
  const camelCaseString = JSON.stringify(camelCaseJson, null, 2);
  return <ResponseExample>
			{isTypeScript ? <CodeBlock language="json" filename={statusCode}>
					{camelCaseString}
				</CodeBlock> : <CodeBlock language="json" filename={statusCode}>
					{snakeCaseString}
				</CodeBlock>}
		</ResponseExample>;
};

export const DynamicResponseField = ({children, name, ...props}) => {
  const convertToCamelCase = str => {
    if (typeof str !== "string") return str;
    return str.replace(/[_-](\w)/g, (_, c) => c.toUpperCase());
  };
  const [lang, setLang] = useState(() => {
    if (typeof window !== "undefined") {
      const stored = localStorage.getItem("code");
      return stored || '"typescript"';
    }
    return '"typescript"';
  });
  useEffect(() => {
    const onMintlifyStorage = event => {
      const key = event.detail?.key;
      if (key === "code") {
        setLang(event.detail.value);
      }
    };
    const pollInterval = setInterval(() => {
      const current = localStorage.getItem("code");
      if (current && current !== lang) {
        setLang(current);
      }
    }, 500);
    document.addEventListener("mintlify-localstorage", onMintlifyStorage);
    return () => {
      document.removeEventListener("mintlify-localstorage", onMintlifyStorage);
      clearInterval(pollInterval);
    };
  }, [lang]);
  const resolvedName = useMemo(() => {
    try {
      const value = JSON.parse(lang);
      const useCamelCase = value === "typescript";
      return useCamelCase ? convertToCamelCase(name) : name;
    } catch {
      return name;
    }
  }, [name, lang]);
  return <ResponseField name={resolvedName} {...props}>
			{children}
		</ResponseField>;
};

export const DynamicParamField = ({children, body, path, ...props}) => {
  const convertToCamelCase = str => {
    if (typeof str !== "string") return str;
    return str.replace(/[_-](\w)/g, (_, c) => c.toUpperCase());
  };
  const [lang, setLang] = useState(() => {
    if (typeof window !== "undefined") {
      const stored = localStorage.getItem("code");
      return stored || '"typescript"';
    }
    return '"typescript"';
  });
  useEffect(() => {
    const onMintlifyStorage = event => {
      const key = event.detail?.key;
      if (key === "code") {
        setLang(event.detail.value);
      }
    };
    const pollInterval = setInterval(() => {
      const current = localStorage.getItem("code");
      if (current && current !== lang) {
        setLang(current);
      }
    }, 500);
    document.addEventListener("mintlify-localstorage", onMintlifyStorage);
    return () => {
      document.removeEventListener("mintlify-localstorage", onMintlifyStorage);
      clearInterval(pollInterval);
    };
  }, [lang]);
  const resolvedBody = useMemo(() => {
    try {
      const value = JSON.parse(lang);
      const useCamelCase = value === "typescript";
      return useCamelCase ? convertToCamelCase(body) : body;
    } catch {
      return body;
    }
  }, [body, lang]);
  const resolvedPath = useMemo(() => {
    try {
      const value = JSON.parse(lang);
      const useCamelCase = value === "typescript";
      return useCamelCase ? convertToCamelCase(path) : path;
    } catch {
      return path;
    }
  }, [path, lang]);
  return <ParamField body={resolvedBody} path={resolvedPath} {...props}>
			{children}
		</ParamField>;
};

Creates a new plan with optional base price and feature configurations. See [How plans work](/documentation/concepts/plans) for concepts and [Adding features to plans](/documentation/concepts/plan-items) 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](/documentation/concepts/plans#multiple-currencies) for how customers are matched to a currency.

### Common Use Cases

<CodeGroup>
  ```typescript Free plan with auto-enable theme={null}
  await autumn.plans.create({
    planId: "free_plan",
    name: "Free",
    autoEnable: true, // Automatically attached on customer creation
    items: [
      {
        featureId: "messages",
        included: 100,
        reset: { interval: "month" }
      }
    ]
  });
  ```

  ```typescript Paid plan with base price + usage-based feature theme={null}
  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"
        }
      }
    ]
  });
  ```

  ```typescript Plan with prepaid seats theme={null}
  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"
        }
      }
    ]
  });
  ```

  ```typescript Add-on plan theme={null}
  await autumn.plans.create({
    planId: "analytics_addon",
    name: "Advanced Analytics",
    addOn: true, // Can be attached alongside other plans
    price: { amount: 20, interval: "month" }
  });
  ```

  ```typescript Plan with tiered pricing theme={null}
  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"
        }
      }
    ]
  });
  ```

  ```typescript Plan with free trial theme={null}
  await autumn.plans.create({
    planId: "premium_plan",
    name: "Premium",
    price: { amount: 99, interval: "month" },
    freeTrial: {
      durationLength: 14,
      durationType: "day",
      cardRequired: true
    }
  });
  ```
</CodeGroup>

### Body Parameters

<DynamicParamField body="plan_id" type="string" required>
  The ID of the plan to create.
</DynamicParamField>

<DynamicParamField body="group" type="string">
  Group identifier for organizing related plans. Plans in the same group are mutually exclusive.
</DynamicParamField>

<DynamicParamField body="name" type="string" required>
  Display name of the plan.
</DynamicParamField>

<DynamicParamField body="description" type="string | null">
  Optional description of the plan.
</DynamicParamField>

<DynamicParamField body="add_on" type="boolean">
  If true, this plan can be attached alongside other plans. Otherwise, attaching replaces existing plans in the same group.
</DynamicParamField>

<DynamicParamField body="auto_enable" type="boolean">
  If true, plan is automatically attached when a customer is created. Use for free tiers.
</DynamicParamField>

<DynamicParamField body="price" type="object">
  Base recurring price for the plan. Omit for free or usage-only plans.

  <Expandable title="properties">
    <DynamicParamField body="amount" type="number" required>
      Base price amount for the plan.
    </DynamicParamField>

    <DynamicParamField body="interval" type="'one_off' | 'week' | 'month' | 'quarter' | 'semi_annual' | 'year'" required>
      Billing interval (e.g. 'month', 'year').
    </DynamicParamField>

    <DynamicParamField body="interval_count" type="number">
      Number of intervals per billing cycle. Defaults to 1.
    </DynamicParamField>

    <DynamicParamField body="additional_currencies" type="object[]">
      Base price amounts in additional currencies. The base 'amount' is in the org's default currency.

      <Expandable title="properties">
        <DynamicParamField body="currency" type="string" required>
          Three-letter Stripe-supported currency code (e.g. 'eur', 'gbp').
        </DynamicParamField>

        <DynamicParamField body="amount" type="number" required>
          Price amount in this currency. Set explicitly per currency, not converted from the base amount.
        </DynamicParamField>
      </Expandable>
    </DynamicParamField>
  </Expandable>
</DynamicParamField>

<DynamicParamField body="items" type="object[]">
  Feature configurations for this plan. Each item defines included units, pricing, and reset behavior.

  <Expandable title="properties">
    <DynamicParamField body="feature_id" type="string" required>
      The ID of the feature to configure.
    </DynamicParamField>

    <DynamicParamField body="included" type="number">
      Number of free units included. Balance resets to this each interval for consumable features.
    </DynamicParamField>

    <DynamicParamField body="unlimited" type="boolean">
      If true, customer has unlimited access to this feature.
    </DynamicParamField>

    <DynamicParamField body="reset" type="object">
      Reset configuration for consumable features. Omit for non-consumable features like seats.

      <Expandable title="properties">
        <DynamicParamField body="interval" type="'one_off' | 'minute' | 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'semi_annual' | 'year'" required>
          Interval at which balance resets (e.g. 'month', 'year'). For consumable features only.
        </DynamicParamField>

        <DynamicParamField body="interval_count" type="number">
          Number of intervals between resets. Defaults to 1.
        </DynamicParamField>
      </Expandable>
    </DynamicParamField>

    <DynamicParamField body="price" type="object">
      Pricing for usage beyond included units. Omit for free features.

      <Expandable title="properties">
        <DynamicParamField body="amount" type="number">
          Price per billing\_units after included usage. Either 'amount' or 'tiers' is required.
        </DynamicParamField>

        <DynamicParamField body="additional_currencies" type="object[]">
          Amounts in additional currencies for this flat price. The base 'amount' is in the org's default currency. Only valid with 'amount', not 'tiers'.

          <Expandable title="properties">
            <DynamicParamField body="currency" type="string" required>
              Three-letter Stripe-supported currency code (e.g. 'eur', 'gbp').
            </DynamicParamField>

            <DynamicParamField body="amount" type="number" required>
              Price amount in this currency. Set explicitly per currency, not converted from the base amount.
            </DynamicParamField>
          </Expandable>
        </DynamicParamField>

        <DynamicParamField body="tiers" type="object[]">
          Tiered pricing. Either 'amount' or 'tiers' is required.

          <Expandable title="properties">
            <DynamicParamField body="to" type="number" required />

            <DynamicParamField body="amount" type="number" />

            <DynamicParamField body="flat_amount" type="number" />

            <DynamicParamField body="additional_currencies" type="object[]">
              Per-currency amounts for this tier. Tier boundaries ('to') are shared across all currencies.

              <Expandable title="properties">
                <DynamicParamField body="currency" type="string" required>
                  Three-letter Stripe-supported currency code (e.g. 'eur', 'gbp').
                </DynamicParamField>

                <DynamicParamField body="amount" type="number">
                  Per-unit amount for this tier in this currency.
                </DynamicParamField>

                <DynamicParamField body="flat_amount" type="number">
                  Flat amount for this tier in this currency, if the tier uses one.
                </DynamicParamField>
              </Expandable>
            </DynamicParamField>
          </Expandable>
        </DynamicParamField>

        <DynamicParamField body="tier_behavior" type="'graduated' | 'volume'" />

        <DynamicParamField body="interval" type="'one_off' | 'week' | 'month' | 'quarter' | 'semi_annual' | 'year'" required>
          Billing interval. For consumable features, should match reset.interval.
        </DynamicParamField>

        <DynamicParamField body="interval_count" type="number">
          Number of intervals per billing cycle. Defaults to 1.
        </DynamicParamField>

        <DynamicParamField body="billing_units" type="number">
          Units per price increment. Usage is rounded UP when billed (e.g. billing\_units=100 means 101 rounds to 200).
        </DynamicParamField>

        <DynamicParamField body="billing_method" type="'prepaid' | 'usage_based'" required>
          'prepaid' for upfront payment (seats), 'usage\_based' for pay-as-you-go.
        </DynamicParamField>

        <DynamicParamField body="max_purchase" type="number | null">
          Max units purchasable beyond included. E.g. included=100, max\_purchase=300 allows 400 total. Null for no limit.
        </DynamicParamField>
      </Expandable>
    </DynamicParamField>

    <DynamicParamField body="proration" type="object">
      Proration settings for prepaid features. Controls mid-cycle quantity change billing.

      <Expandable title="properties">
        <DynamicParamField body="on_increase" type="'bill_immediately' | 'prorate_immediately' | 'prorate_next_cycle' | 'bill_next_cycle'" required>
          Billing behavior when quantity increases mid-cycle.
        </DynamicParamField>

        <DynamicParamField body="on_decrease" type="'prorate' | 'prorate_immediately' | 'prorate_next_cycle' | 'none' | 'no_prorations'" required>
          Credit behavior when quantity decreases mid-cycle.
        </DynamicParamField>
      </Expandable>
    </DynamicParamField>

    <DynamicParamField body="rollover" type="object">
      Rollover config for unused units. If set, unused included units carry over.

      <Expandable title="properties">
        <DynamicParamField body="max" type="number">
          Max rollover units. Omit for unlimited rollover.
        </DynamicParamField>

        <DynamicParamField body="max_percentage" type="number">
          Maximum rollover as a percentage (0-100) of included + prepaid grant. Mutually exclusive with max.
        </DynamicParamField>

        <DynamicParamField body="expiry_duration_type" type="'month' | 'forever'" required>
          When rolled over units expire.
        </DynamicParamField>

        <DynamicParamField body="expiry_duration_length" type="number">
          Number of periods before expiry.
        </DynamicParamField>
      </Expandable>
    </DynamicParamField>
  </Expandable>
</DynamicParamField>

<DynamicParamField body="licenses" type="object[]">
  Plans offered as assignable licenses under this plan. The full set replaces existing links.

  <Expandable title="properties">
    <DynamicParamField body="license_plan_id" type="string" required />

    <DynamicParamField body="included" type="integer" />

    <DynamicParamField body="prepaid_only" type="boolean" />

    <DynamicParamField body="customize" type="object | null">
      <Expandable title="properties">
        <DynamicParamField body="price" type="object | null">
          Base price configuration for a plan.

          <Expandable title="properties">
            <DynamicParamField body="amount" type="number" required>
              Base price amount for the plan.
            </DynamicParamField>

            <DynamicParamField body="interval" type="'one_off' | 'week' | 'month' | 'quarter' | 'semi_annual' | 'year'" required>
              Billing interval (e.g. 'month', 'year').
            </DynamicParamField>

            <DynamicParamField body="interval_count" type="number">
              Number of intervals per billing cycle. Defaults to 1.
            </DynamicParamField>

            <DynamicParamField body="additional_currencies" type="object[]">
              Base price amounts in additional currencies. The base 'amount' is in the org's default currency.

              <Expandable title="properties">
                <DynamicParamField body="currency" type="string" required>
                  Three-letter Stripe-supported currency code (e.g. 'eur', 'gbp').
                </DynamicParamField>

                <DynamicParamField body="amount" type="number" required>
                  Price amount in this currency. Set explicitly per currency, not converted from the base amount.
                </DynamicParamField>
              </Expandable>
            </DynamicParamField>
          </Expandable>
        </DynamicParamField>

        <DynamicParamField body="add_items" type="object[]">
          <Expandable title="properties">
            <DynamicParamField body="feature_id" type="string" required>
              The ID of the feature to configure.
            </DynamicParamField>

            <DynamicParamField body="included" type="number">
              Number of free units included. Balance resets to this each interval for consumable features.
            </DynamicParamField>

            <DynamicParamField body="unlimited" type="boolean">
              If true, customer has unlimited access to this feature.
            </DynamicParamField>

            <DynamicParamField body="reset" type="object">
              Reset configuration for consumable features. Omit for non-consumable features like seats.

              <Expandable title="properties">
                <DynamicParamField body="interval" type="'one_off' | 'minute' | 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'semi_annual' | 'year'" required>
                  Interval at which balance resets (e.g. 'month', 'year'). For consumable features only.
                </DynamicParamField>

                <DynamicParamField body="interval_count" type="number">
                  Number of intervals between resets. Defaults to 1.
                </DynamicParamField>
              </Expandable>
            </DynamicParamField>

            <DynamicParamField body="price" type="object">
              Pricing for usage beyond included units. Omit for free features.

              <Expandable title="properties">
                <DynamicParamField body="amount" type="number">
                  Price per billing\_units after included usage. Either 'amount' or 'tiers' is required.
                </DynamicParamField>

                <DynamicParamField body="additional_currencies" type="object[]">
                  Amounts in additional currencies for this flat price. The base 'amount' is in the org's default currency. Only valid with 'amount', not 'tiers'.

                  <Expandable title="properties">
                    <DynamicParamField body="currency" type="string" required>
                      Three-letter Stripe-supported currency code (e.g. 'eur', 'gbp').
                    </DynamicParamField>

                    <DynamicParamField body="amount" type="number" required>
                      Price amount in this currency. Set explicitly per currency, not converted from the base amount.
                    </DynamicParamField>
                  </Expandable>
                </DynamicParamField>

                <DynamicParamField body="tiers" type="object[]">
                  Tiered pricing. Either 'amount' or 'tiers' is required.

                  <Expandable title="properties">
                    <DynamicParamField body="to" type="number" required />

                    <DynamicParamField body="amount" type="number" />

                    <DynamicParamField body="flat_amount" type="number" />

                    <DynamicParamField body="additional_currencies" type="object[]">
                      Per-currency amounts for this tier. Tier boundaries ('to') are shared across all currencies.

                      <Expandable title="properties">
                        <DynamicParamField body="currency" type="any" />

                        <DynamicParamField body="amount" type="any" />

                        <DynamicParamField body="flat_amount" type="any" />
                      </Expandable>
                    </DynamicParamField>
                  </Expandable>
                </DynamicParamField>

                <DynamicParamField body="tier_behavior" type="'graduated' | 'volume'" />

                <DynamicParamField body="interval" type="'one_off' | 'week' | 'month' | 'quarter' | 'semi_annual' | 'year'" required>
                  Billing interval. For consumable features, should match reset.interval.
                </DynamicParamField>

                <DynamicParamField body="interval_count" type="number">
                  Number of intervals per billing cycle. Defaults to 1.
                </DynamicParamField>

                <DynamicParamField body="billing_units" type="number">
                  Units per price increment. Usage is rounded UP when billed (e.g. billing\_units=100 means 101 rounds to 200).
                </DynamicParamField>

                <DynamicParamField body="billing_method" type="'prepaid' | 'usage_based'" required>
                  'prepaid' for upfront payment (seats), 'usage\_based' for pay-as-you-go.
                </DynamicParamField>

                <DynamicParamField body="max_purchase" type="number | null">
                  Max units purchasable beyond included. E.g. included=100, max\_purchase=300 allows 400 total. Null for no limit.
                </DynamicParamField>
              </Expandable>
            </DynamicParamField>

            <DynamicParamField body="proration" type="object">
              Proration settings for prepaid features. Controls mid-cycle quantity change billing.

              <Expandable title="properties">
                <DynamicParamField body="on_increase" type="'bill_immediately' | 'prorate_immediately' | 'prorate_next_cycle' | 'bill_next_cycle'" required>
                  Billing behavior when quantity increases mid-cycle.
                </DynamicParamField>

                <DynamicParamField body="on_decrease" type="'prorate' | 'prorate_immediately' | 'prorate_next_cycle' | 'none' | 'no_prorations'" required>
                  Credit behavior when quantity decreases mid-cycle.
                </DynamicParamField>
              </Expandable>
            </DynamicParamField>

            <DynamicParamField body="rollover" type="object">
              Rollover config for unused units. If set, unused included units carry over.

              <Expandable title="properties">
                <DynamicParamField body="max" type="number">
                  Max rollover units. Omit for unlimited rollover.
                </DynamicParamField>

                <DynamicParamField body="max_percentage" type="number">
                  Maximum rollover as a percentage (0-100) of included + prepaid grant. Mutually exclusive with max.
                </DynamicParamField>

                <DynamicParamField body="expiry_duration_type" type="'month' | 'forever'" required>
                  When rolled over units expire.
                </DynamicParamField>

                <DynamicParamField body="expiry_duration_length" type="number">
                  Number of periods before expiry.
                </DynamicParamField>
              </Expandable>
            </DynamicParamField>
          </Expandable>
        </DynamicParamField>

        <DynamicParamField body="remove_items" type="object[]">
          <Expandable title="properties">
            <DynamicParamField body="feature_id" type="string">
              Match items linked to this feature.
            </DynamicParamField>

            <DynamicParamField body="billing_method" type="'prepaid' | 'usage_based'">
              Match items with this billing method (prepaid or usage\_based).
            </DynamicParamField>

            <DynamicParamField body="interval" type="'one_off' | 'week' | 'month' | 'quarter' | 'semi_annual' | 'year'">
              Match items with this interval. Accepts either a BillingInterval (price-side) or a ResetInterval (reset-side, includes day/hour/minute) so price-less items keyed by reset.interval can be disambiguated.
            </DynamicParamField>

            <DynamicParamField body="interval_count" type="integer">
              Match items with this interval\_count. Disambiguates between items that share an interval but differ in count.
            </DynamicParamField>
          </Expandable>
        </DynamicParamField>
      </Expandable>
    </DynamicParamField>

    <DynamicParamField body="metadata" type="object" />

    <DynamicParamField body="version" type="integer">
      Pin the link to a specific version of the license plan. Omitted, an existing link keeps its pinned version and a new link resolves to the latest.
    </DynamicParamField>
  </Expandable>
</DynamicParamField>

<DynamicParamField body="free_trial" type="object">
  Free trial configuration. Customers can try this plan before being charged.

  <Expandable title="properties">
    <DynamicParamField body="duration_length" type="number" required>
      Number of duration\_type periods the trial lasts.
    </DynamicParamField>

    <DynamicParamField body="duration_type" type="'day' | 'month' | 'year'">
      Unit of time for the trial ('day', 'month', 'year').
    </DynamicParamField>

    <DynamicParamField body="card_required" type="boolean">
      If true, payment method required to start trial. Customer is charged after trial ends.
    </DynamicParamField>

    <DynamicParamField body="on_end" type="'bill' | 'revert'">
      Behavior when the trial ends. 'bill' charges the customer (default). 'revert' expires the trial and restores the customer's previous plan.
    </DynamicParamField>
  </Expandable>
</DynamicParamField>

<DynamicParamField body="config" type="object">
  Miscellaneous plan-level configuration flags.

  <Expandable title="properties">
    <DynamicParamField body="ignore_past_due" type="boolean">
      If true, entitlements attached to this plan will still reset on schedule even when the customer's product is in a past\_due state.
    </DynamicParamField>
  </Expandable>
</DynamicParamField>

<DynamicParamField body="billing_controls" type="object">
  Plan-level billing controls used as customer defaults.

  <Expandable title="properties">
    <DynamicParamField body="auto_topups" type="object[]">
      List of auto top-up configurations per feature.

      <Expandable title="properties">
        <DynamicParamField body="feature_id" type="string" required>
          The ID of the feature (credit balance) to auto top-up.
        </DynamicParamField>

        <DynamicParamField body="enabled" type="boolean">
          Whether auto top-up is enabled.
        </DynamicParamField>

        <DynamicParamField body="threshold" type="number" required>
          When the balance drops below this threshold, an auto top-up will be purchased.
        </DynamicParamField>

        <DynamicParamField body="quantity" type="number" required>
          Amount of credits to add per auto top-up.
        </DynamicParamField>

        <DynamicParamField body="purchase_limit" type="object">
          Optional rate limit to cap how often auto top-ups occur.

          <Expandable title="properties">
            <DynamicParamField body="interval" type="'hour' | 'day' | 'week' | 'month'" required>
              The time interval for the purchase limit window.
            </DynamicParamField>

            <DynamicParamField body="interval_count" type="number">
              Number of intervals in the purchase limit window.
            </DynamicParamField>

            <DynamicParamField body="limit" type="number" required>
              Maximum number of auto top-ups allowed within the interval.
            </DynamicParamField>
          </Expandable>
        </DynamicParamField>

        <DynamicParamField body="invoice_mode" type="boolean">
          When true, auto top-up creates a send\_invoice invoice instead of auto-charging.
        </DynamicParamField>
      </Expandable>
    </DynamicParamField>

    <DynamicParamField body="spend_limits" type="object[]">
      List of overage spend limits per feature (caps overage spend).

      <Expandable title="properties">
        <DynamicParamField body="feature_id" type="string">
          Optional feature ID this spend limit applies to.
        </DynamicParamField>

        <DynamicParamField body="enabled" type="boolean">
          Whether the overage spend limit is enabled.
        </DynamicParamField>

        <DynamicParamField body="limit_type" type="'absolute' | 'usage_percentage'">
          How overage\_limit is interpreted: an absolute overage cap (default) or a percentage of the main-plan allowance.
        </DynamicParamField>

        <DynamicParamField body="overage_limit" type="number">
          Overage cap for the feature: absolute units, or a percent (e.g. 120) when limit\_type is usage\_percentage.
        </DynamicParamField>

        <DynamicParamField body="skip_overage_billing" type="boolean">
          When true, overage for this feature is not posted to Stripe. Usage tracking and balance resets still behave normally.
        </DynamicParamField>
      </Expandable>
    </DynamicParamField>

    <DynamicParamField body="usage_limits" type="object[]">
      List of hard usage caps per feature (max units per interval).

      <Expandable title="properties">
        <DynamicParamField body="feature_id" type="string" required>
          The feature this usage limit applies to.
        </DynamicParamField>

        <DynamicParamField body="enabled" type="boolean">
          Whether this usage limit is enabled.
        </DynamicParamField>

        <DynamicParamField body="limit" type="number" required>
          Maximum units allowed per interval.
        </DynamicParamField>

        <DynamicParamField body="interval" type="'day' | 'week' | 'month' | 'year'" required>
          Interval for the cap, aligned to the customer's billing cycle.
        </DynamicParamField>

        <DynamicParamField body="filter" type="object">
          When set, only usage from events whose properties match counts toward this cap. Omit to count all usage of the feature.

          <Expandable title="properties">
            <DynamicParamField body="properties.{key}" type="string" required />
          </Expandable>
        </DynamicParamField>
      </Expandable>
    </DynamicParamField>

    <DynamicParamField body="usage_alerts" type="object[]">
      List of usage alert configurations per feature.

      <Expandable title="properties">
        <DynamicParamField body="feature_id" type="string">
          The feature ID this alert applies to.
        </DynamicParamField>

        <DynamicParamField body="enabled" type="boolean">
          Whether this usage alert is enabled.
        </DynamicParamField>

        <DynamicParamField body="threshold" type="number" required>
          The threshold value that triggers the alert. For usage or remaining, this is an absolute count. For usage\_percentage or remaining\_percentage, this is a percentage (0-100).
        </DynamicParamField>

        <DynamicParamField body="threshold_type" type="'usage' | 'usage_percentage' | 'remaining' | 'remaining_percentage'" required>
          Whether the threshold is an absolute count or a percentage of the usage allowance or remaining balance.
        </DynamicParamField>

        <DynamicParamField body="name" type="string">
          Optional user-defined label to distinguish multiple alerts on the same feature.
        </DynamicParamField>
      </Expandable>
    </DynamicParamField>

    <DynamicParamField body="overage_allowed" type="object[]">
      List of overage allowed controls per feature. When enabled, usage can exceed balance.

      <Expandable title="properties">
        <DynamicParamField body="feature_id" type="string" required>
          The feature ID this overage allowed control applies to.
        </DynamicParamField>

        <DynamicParamField body="enabled" type="boolean">
          Whether overage is allowed for this feature.
        </DynamicParamField>
      </Expandable>
    </DynamicParamField>
  </Expandable>
</DynamicParamField>

<DynamicParamField body="metadata" type="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.
</DynamicParamField>

<DynamicParamField body="create_in_stripe" type="boolean" />

### Response

<DynamicResponseField name="id" type="string">
  Unique identifier for the plan.
</DynamicResponseField>

<DynamicResponseField name="name" type="string">
  Display name of the plan.
</DynamicResponseField>

<DynamicResponseField name="description" type="string | null">
  Optional description of the plan.
</DynamicResponseField>

<DynamicResponseField name="group" type="string | null">
  Group identifier for organizing related plans. Plans in the same group are mutually exclusive.
</DynamicResponseField>

<DynamicResponseField name="version" type="number">
  Version number of the plan. Incremented when plan configuration changes.
</DynamicResponseField>

<DynamicResponseField name="add_on" type="boolean">
  Whether this is an add-on plan that can be attached alongside a main plan.
</DynamicResponseField>

<DynamicResponseField name="auto_enable" type="boolean">
  If true, this plan is automatically attached when a customer is created. Used for free plans.
</DynamicResponseField>

<DynamicResponseField name="price" type="object | null">
  Base recurring price for the plan. Null for free plans or usage-only plans.

  <Expandable title="properties">
    <DynamicResponseField name="amount" type="number">
      Base price amount for the plan.
    </DynamicResponseField>

    <DynamicResponseField name="additional_currencies" type="object[]">
      Base price amounts in additional currencies. The base 'amount' is in the org's default currency.

      <Expandable title="properties">
        <DynamicResponseField name="currency" type="string">
          Three-letter Stripe-supported currency code (e.g. 'eur', 'gbp').
        </DynamicResponseField>

        <DynamicResponseField name="amount" type="number">
          Price amount in this currency. Set explicitly per currency, not converted from the base amount.
        </DynamicResponseField>
      </Expandable>
    </DynamicResponseField>

    <DynamicResponseField name="interval" type="'one_off' | 'week' | 'month' | 'quarter' | 'semi_annual' | 'year'">
      Billing interval (e.g. 'month', 'year').
    </DynamicResponseField>

    <DynamicResponseField name="interval_count" type="number">
      Number of intervals per billing cycle. Defaults to 1.
    </DynamicResponseField>

    <DynamicResponseField name="display" type="object">
      Display text for showing this price in pricing pages.

      <Expandable title="properties">
        <DynamicResponseField name="primary_text" type="string">
          Main display text (e.g. '\$10' or '100 messages').
        </DynamicResponseField>

        <DynamicResponseField name="secondary_text" type="string">
          Secondary display text (e.g. 'per month' or 'then \$0.5 per 100').
        </DynamicResponseField>
      </Expandable>
    </DynamicResponseField>
  </Expandable>
</DynamicResponseField>

<DynamicResponseField name="items" type="object[]">
  Feature configurations included in this plan. Each item defines included units, pricing, and reset behavior for a feature.

  <Expandable title="properties">
    <DynamicResponseField name="feature_id" type="string">
      The ID of the feature this item configures.
    </DynamicResponseField>

    <DynamicResponseField name="feature" type="object">
      The full feature object if expanded.

      <Expandable title="properties">
        <DynamicResponseField name="id" type="string">
          The ID of the feature, used to refer to it in other API calls like /track or /check.
        </DynamicResponseField>

        <DynamicResponseField name="name" type="string | null">
          The name of the feature.
        </DynamicResponseField>

        <DynamicResponseField name="type" type="'static' | 'boolean' | 'single_use' | 'continuous_use' | 'credit_system' | 'ai_credit_system'">
          The type of the feature
        </DynamicResponseField>

        <DynamicResponseField name="display" type="object | null">
          Singular and plural display names for the feature.

          <Expandable title="properties">
            <DynamicResponseField name="singular" type="string">
              The singular display name for the feature.
            </DynamicResponseField>

            <DynamicResponseField name="plural" type="string">
              The plural display name for the feature.
            </DynamicResponseField>
          </Expandable>
        </DynamicResponseField>

        <DynamicResponseField name="credit_schema" type="object[] | null">
          Credit cost schema for credit system features.

          <Expandable title="properties">
            <DynamicResponseField name="metered_feature_id" type="string">
              The ID of the metered feature (should be a single\_use feature).
            </DynamicResponseField>

            <DynamicResponseField name="credit_cost" type="number">
              The credit cost of the metered feature.
            </DynamicResponseField>
          </Expandable>
        </DynamicResponseField>

        <DynamicResponseField name="archived" type="boolean | null">
          Whether or not the feature is archived.
        </DynamicResponseField>
      </Expandable>
    </DynamicResponseField>

    <DynamicResponseField name="included" type="number">
      Number of free units included. For consumable features, balance resets to this number each interval.
    </DynamicResponseField>

    <DynamicResponseField name="unlimited" type="boolean">
      Whether the customer has unlimited access to this feature.
    </DynamicResponseField>

    <DynamicResponseField name="reset" type="object | null">
      Reset configuration for consumable features. Null for non-consumable features like seats where usage persists across billing cycles.

      <Expandable title="properties">
        <DynamicResponseField name="interval" type="'one_off' | 'minute' | 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'semi_annual' | 'year'">
          The interval at which the feature balance resets (e.g. 'month', 'year'). For consumable features, usage resets to 0 and included units are restored.
        </DynamicResponseField>

        <DynamicResponseField name="interval_count" type="number">
          Number of intervals between resets. Defaults to 1.
        </DynamicResponseField>
      </Expandable>
    </DynamicResponseField>

    <DynamicResponseField name="price" type="object | null">
      Pricing configuration for usage beyond included units. Null if feature is entirely free.

      <Expandable title="properties">
        <DynamicResponseField name="amount" type="number">
          Price per billing\_units after included usage is consumed. Mutually exclusive with tiers.
        </DynamicResponseField>

        <DynamicResponseField name="additional_currencies" type="object[]">
          Amounts in additional currencies for this flat price. The base 'amount' is in the org's default currency. Only valid with 'amount', not 'tiers' (tiered prices carry per-currency amounts on each tier).

          <Expandable title="properties">
            <DynamicResponseField name="currency" type="string">
              Three-letter Stripe-supported currency code (e.g. 'eur', 'gbp').
            </DynamicResponseField>

            <DynamicResponseField name="amount" type="number">
              Price amount in this currency. Set explicitly per currency, not converted from the base amount.
            </DynamicResponseField>
          </Expandable>
        </DynamicResponseField>

        <DynamicResponseField name="tiers" type="object[]">
          Tiered pricing configuration. Each tier's 'to' INCLUDES the included amount. Either 'tiers' or 'amount' is required.

          <Expandable title="properties">
            <DynamicResponseField name="to" type="number" />

            <DynamicResponseField name="amount" type="number" />

            <DynamicResponseField name="flat_amount" type="number" />

            <DynamicResponseField name="additional_currencies" type="object[]">
              <Expandable title="properties">
                <DynamicResponseField name="currency" type="string">
                  Three-letter Stripe-supported currency code (e.g. 'eur', 'gbp').
                </DynamicResponseField>

                <DynamicResponseField name="amount" type="number">
                  Per-unit amount for this tier in this currency.
                </DynamicResponseField>

                <DynamicResponseField name="flat_amount" type="number">
                  Flat amount for this tier in this currency, if the tier uses one.
                </DynamicResponseField>
              </Expandable>
            </DynamicResponseField>
          </Expandable>
        </DynamicResponseField>

        <DynamicResponseField name="tier_behavior" type="'graduated' | 'volume'" />

        <DynamicResponseField name="interval" type="'one_off' | 'week' | 'month' | 'quarter' | 'semi_annual' | 'year'">
          Billing interval for this price. For consumable features, should match reset.interval.
        </DynamicResponseField>

        <DynamicResponseField name="interval_count" type="number">
          Number of intervals per billing cycle. Defaults to 1.
        </DynamicResponseField>

        <DynamicResponseField name="billing_units" type="number">
          Number of units per price increment. Usage is rounded UP to the nearest billing\_units when billed (e.g. billing\_units=100 means 101 usage rounds to 200).
        </DynamicResponseField>

        <DynamicResponseField name="billing_method" type="'prepaid' | 'usage_based'">
          'prepaid' for features like seats where customers pay upfront, 'usage\_based' for pay-as-you-go after included usage.
        </DynamicResponseField>

        <DynamicResponseField name="max_purchase" type="number | null">
          Maximum units a customer can purchase beyond included. E.g. if included=100 and max\_purchase=300, customer can use up to 400 total before usage is capped. Null for no limit.
        </DynamicResponseField>
      </Expandable>
    </DynamicResponseField>

    <DynamicResponseField name="display" type="object">
      Display text for showing this item in pricing pages.

      <Expandable title="properties">
        <DynamicResponseField name="primary_text" type="string">
          Main display text (e.g. '\$10' or '100 messages').
        </DynamicResponseField>

        <DynamicResponseField name="secondary_text" type="string">
          Secondary display text (e.g. 'per month' or 'then \$0.5 per 100').
        </DynamicResponseField>
      </Expandable>
    </DynamicResponseField>

    <DynamicResponseField name="rollover" type="object">
      Rollover configuration for unused units. If set, unused included units roll over to the next period.

      <Expandable title="properties">
        <DynamicResponseField name="max" type="number | null">
          Maximum rollover units. Null for unlimited rollover.
        </DynamicResponseField>

        <DynamicResponseField name="max_percentage" type="number | null">
          Maximum rollover as a percentage (0-100) of included + prepaid grant. Mutually exclusive with max.
        </DynamicResponseField>

        <DynamicResponseField name="expiry_duration_type" type="'month' | 'forever'">
          When rolled over units expire.
        </DynamicResponseField>

        <DynamicResponseField name="expiry_duration_length" type="number">
          Number of periods before expiry.
        </DynamicResponseField>
      </Expandable>
    </DynamicResponseField>
  </Expandable>
</DynamicResponseField>

<DynamicResponseField name="free_trial" type="object">
  Free trial configuration. If set, new customers can try this plan before being charged.

  <Expandable title="properties">
    <DynamicResponseField name="duration_length" type="number">
      Number of duration\_type periods the trial lasts.
    </DynamicResponseField>

    <DynamicResponseField name="duration_type" type="'day' | 'month' | 'year'">
      Unit of time for the trial duration ('day', 'month', 'year').
    </DynamicResponseField>

    <DynamicResponseField name="card_required" type="boolean">
      Whether a payment method is required to start the trial. If true, customer will be charged after trial ends.
    </DynamicResponseField>

    <DynamicResponseField name="on_end" type="'bill' | 'revert'">
      Behavior when the trial ends. 'bill' charges the customer (default). 'revert' expires the trial and restores the customer's previous plan.
    </DynamicResponseField>
  </Expandable>
</DynamicResponseField>

<DynamicResponseField name="created_at" type="number">
  Unix timestamp (ms) when the plan was created.
</DynamicResponseField>

<DynamicResponseField name="env" type="'sandbox' | 'live'">
  Environment this plan belongs to ('sandbox' or 'live').
</DynamicResponseField>

<DynamicResponseField name="archived" type="boolean">
  Whether the plan is archived. Archived plans cannot be attached to new customers.
</DynamicResponseField>

<DynamicResponseField name="base_variant_id" type="string | null">
  Deprecated. Use variant\_details.base\_plan\_id instead. If this is a variant, the ID of the base plan it was created from.
</DynamicResponseField>

<DynamicResponseField name="variant_details" type="object">
  Details about how this variant relates to its latest base plan.

  <Expandable title="properties">
    <DynamicResponseField name="base_plan_id" type="string">
      The ID of the base plan this variant was derived from.
    </DynamicResponseField>

    <DynamicResponseField name="customize" type="object">
      The customization that transforms the base plan into this variant.

      <Expandable title="properties">
        <DynamicResponseField name="price" type="object | null">
          Base price configuration for a plan.

          <Expandable title="properties">
            <DynamicResponseField name="amount" type="number">
              Base price amount for the plan.
            </DynamicResponseField>

            <DynamicResponseField name="interval" type="'one_off' | 'week' | 'month' | 'quarter' | 'semi_annual' | 'year'">
              Billing interval (e.g. 'month', 'year').
            </DynamicResponseField>

            <DynamicResponseField name="interval_count" type="number">
              Number of intervals per billing cycle. Defaults to 1.
            </DynamicResponseField>

            <DynamicResponseField name="additional_currencies" type="object[]">
              Base price amounts in additional currencies. The base 'amount' is in the org's default currency.

              <Expandable title="properties">
                <DynamicResponseField name="currency" type="string">
                  Three-letter Stripe-supported currency code (e.g. 'eur', 'gbp').
                </DynamicResponseField>

                <DynamicResponseField name="amount" type="number">
                  Price amount in this currency. Set explicitly per currency, not converted from the base amount.
                </DynamicResponseField>
              </Expandable>
            </DynamicResponseField>
          </Expandable>
        </DynamicResponseField>

        <DynamicResponseField name="add_items" type="object[]">
          Items to add to the plan.

          <Expandable title="properties">
            <DynamicResponseField name="feature_id" type="string">
              The ID of the feature to configure.
            </DynamicResponseField>

            <DynamicResponseField name="included" type="number">
              Number of free units included. Balance resets to this each interval for consumable features.
            </DynamicResponseField>

            <DynamicResponseField name="unlimited" type="boolean">
              If true, customer has unlimited access to this feature.
            </DynamicResponseField>

            <DynamicResponseField name="reset" type="object">
              Reset configuration for consumable features. Omit for non-consumable features like seats.

              <Expandable title="properties">
                <DynamicResponseField name="interval" type="'one_off' | 'minute' | 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'semi_annual' | 'year'">
                  Interval at which balance resets (e.g. 'month', 'year'). For consumable features only.
                </DynamicResponseField>

                <DynamicResponseField name="interval_count" type="number">
                  Number of intervals between resets. Defaults to 1.
                </DynamicResponseField>
              </Expandable>
            </DynamicResponseField>

            <DynamicResponseField name="price" type="object">
              Pricing for usage beyond included units. Omit for free features.

              <Expandable title="properties">
                <DynamicResponseField name="amount" type="number">
                  Price per billing\_units after included usage. Either 'amount' or 'tiers' is required.
                </DynamicResponseField>

                <DynamicResponseField name="additional_currencies" type="object[]">
                  Amounts in additional currencies for this flat price. The base 'amount' is in the org's default currency. Only valid with 'amount', not 'tiers'.

                  <Expandable title="properties">
                    <DynamicResponseField name="currency" type="string">
                      Three-letter Stripe-supported currency code (e.g. 'eur', 'gbp').
                    </DynamicResponseField>

                    <DynamicResponseField name="amount" type="number">
                      Price amount in this currency. Set explicitly per currency, not converted from the base amount.
                    </DynamicResponseField>
                  </Expandable>
                </DynamicResponseField>

                <DynamicResponseField name="tiers" type="object[]">
                  Tiered pricing. Either 'amount' or 'tiers' is required.

                  <Expandable title="properties">
                    <DynamicResponseField name="to" type="number" />

                    <DynamicResponseField name="amount" type="number" />

                    <DynamicResponseField name="flat_amount" type="number" />

                    <DynamicResponseField name="additional_currencies" type="object[]">
                      <Expandable title="properties">
                        <DynamicResponseField name="currency" type="string">
                          Three-letter Stripe-supported currency code (e.g. 'eur', 'gbp').
                        </DynamicResponseField>

                        <DynamicResponseField name="amount" type="number">
                          Per-unit amount for this tier in this currency.
                        </DynamicResponseField>

                        <DynamicResponseField name="flat_amount" type="number">
                          Flat amount for this tier in this currency, if the tier uses one.
                        </DynamicResponseField>
                      </Expandable>
                    </DynamicResponseField>
                  </Expandable>
                </DynamicResponseField>

                <DynamicResponseField name="tier_behavior" type="'graduated' | 'volume'" />

                <DynamicResponseField name="interval" type="'one_off' | 'week' | 'month' | 'quarter' | 'semi_annual' | 'year'">
                  Billing interval. For consumable features, should match reset.interval.
                </DynamicResponseField>

                <DynamicResponseField name="interval_count" type="number">
                  Number of intervals per billing cycle. Defaults to 1.
                </DynamicResponseField>

                <DynamicResponseField name="billing_units" type="number">
                  Units per price increment. Usage is rounded UP when billed (e.g. billing\_units=100 means 101 rounds to 200).
                </DynamicResponseField>

                <DynamicResponseField name="billing_method" type="'prepaid' | 'usage_based'">
                  'prepaid' for upfront payment (seats), 'usage\_based' for pay-as-you-go.
                </DynamicResponseField>

                <DynamicResponseField name="max_purchase" type="number | null">
                  Max units purchasable beyond included. E.g. included=100, max\_purchase=300 allows 400 total. Null for no limit.
                </DynamicResponseField>
              </Expandable>
            </DynamicResponseField>

            <DynamicResponseField name="proration" type="object">
              Proration settings for prepaid features. Controls mid-cycle quantity change billing.

              <Expandable title="properties">
                <DynamicResponseField name="on_increase" type="'bill_immediately' | 'prorate_immediately' | 'prorate_next_cycle' | 'bill_next_cycle'">
                  Billing behavior when quantity increases mid-cycle.
                </DynamicResponseField>

                <DynamicResponseField name="on_decrease" type="'prorate' | 'prorate_immediately' | 'prorate_next_cycle' | 'none' | 'no_prorations'">
                  Credit behavior when quantity decreases mid-cycle.
                </DynamicResponseField>
              </Expandable>
            </DynamicResponseField>

            <DynamicResponseField name="rollover" type="object">
              Rollover config for unused units. If set, unused included units carry over.

              <Expandable title="properties">
                <DynamicResponseField name="max" type="number">
                  Max rollover units. Omit for unlimited rollover.
                </DynamicResponseField>

                <DynamicResponseField name="max_percentage" type="number">
                  Maximum rollover as a percentage (0-100) of included + prepaid grant. Mutually exclusive with max.
                </DynamicResponseField>

                <DynamicResponseField name="expiry_duration_type" type="'month' | 'forever'">
                  When rolled over units expire.
                </DynamicResponseField>

                <DynamicResponseField name="expiry_duration_length" type="number">
                  Number of periods before expiry.
                </DynamicResponseField>
              </Expandable>
            </DynamicResponseField>
          </Expandable>
        </DynamicResponseField>

        <DynamicResponseField name="remove_items" type="object[]">
          Filters selecting items to remove from the plan.

          <Expandable title="properties">
            <DynamicResponseField name="feature_id" type="string">
              Match items linked to this feature.
            </DynamicResponseField>

            <DynamicResponseField name="billing_method" type="'prepaid' | 'usage_based'">
              Match items with this billing method (prepaid or usage\_based).
            </DynamicResponseField>

            <DynamicResponseField name="interval" type="'one_off' | 'week' | 'month' | 'quarter' | 'semi_annual' | 'year'">
              Match items with this interval. Accepts either a BillingInterval (price-side) or a ResetInterval (reset-side, includes day/hour/minute) so price-less items keyed by reset.interval can be disambiguated.
            </DynamicResponseField>

            <DynamicResponseField name="interval_count" type="integer">
              Match items with this interval\_count. Disambiguates between items that share an interval but differ in count.
            </DynamicResponseField>
          </Expandable>
        </DynamicResponseField>

        <DynamicResponseField name="free_trial" type="object | null">
          Free trial configuration for a plan.

          <Expandable title="properties">
            <DynamicResponseField name="duration_length" type="number">
              Number of duration\_type periods the trial lasts.
            </DynamicResponseField>

            <DynamicResponseField name="duration_type" type="'day' | 'month' | 'year'">
              Unit of time for the trial ('day', 'month', 'year').
            </DynamicResponseField>

            <DynamicResponseField name="card_required" type="boolean">
              If true, payment method required to start trial. Customer is charged after trial ends.
            </DynamicResponseField>

            <DynamicResponseField name="on_end" type="'bill' | 'revert'">
              Behavior when the trial ends. 'bill' charges the customer (default). 'revert' expires the trial and restores the customer's previous plan.
            </DynamicResponseField>
          </Expandable>
        </DynamicResponseField>

        <DynamicResponseField name="billing_controls" type="object">
          Override the plan's billing controls (auto top-ups, spend limits, usage limits, usage alerts, overage allowed) for this customer.

          <Expandable title="properties">
            <DynamicResponseField name="auto_topups" type="object[]">
              List of auto top-up configurations per feature.

              <Expandable title="properties">
                <DynamicResponseField name="feature_id" type="string">
                  The ID of the feature (credit balance) to auto top-up.
                </DynamicResponseField>

                <DynamicResponseField name="enabled" type="boolean">
                  Whether auto top-up is enabled.
                </DynamicResponseField>

                <DynamicResponseField name="threshold" type="number">
                  When the balance drops below this threshold, an auto top-up will be purchased.
                </DynamicResponseField>

                <DynamicResponseField name="quantity" type="number">
                  Amount of credits to add per auto top-up.
                </DynamicResponseField>

                <DynamicResponseField name="purchase_limit" type="object">
                  Optional rate limit to cap how often auto top-ups occur.

                  <Expandable title="properties">
                    <DynamicResponseField name="interval" type="'hour' | 'day' | 'week' | 'month'">
                      The time interval for the purchase limit window.
                    </DynamicResponseField>

                    <DynamicResponseField name="interval_count" type="number">
                      Number of intervals in the purchase limit window.
                    </DynamicResponseField>

                    <DynamicResponseField name="limit" type="number">
                      Maximum number of auto top-ups allowed within the interval.
                    </DynamicResponseField>
                  </Expandable>
                </DynamicResponseField>

                <DynamicResponseField name="invoice_mode" type="boolean">
                  When true, auto top-up creates a send\_invoice invoice instead of auto-charging.
                </DynamicResponseField>
              </Expandable>
            </DynamicResponseField>

            <DynamicResponseField name="spend_limits" type="object[]">
              List of overage spend limits per feature (caps overage spend).

              <Expandable title="properties">
                <DynamicResponseField name="feature_id" type="string">
                  Optional feature ID this spend limit applies to.
                </DynamicResponseField>

                <DynamicResponseField name="enabled" type="boolean">
                  Whether the overage spend limit is enabled.
                </DynamicResponseField>

                <DynamicResponseField name="limit_type" type="'absolute' | 'usage_percentage'">
                  How overage\_limit is interpreted: an absolute overage cap (default) or a percentage of the main-plan allowance.
                </DynamicResponseField>

                <DynamicResponseField name="overage_limit" type="number">
                  Overage cap for the feature: absolute units, or a percent (e.g. 120) when limit\_type is usage\_percentage.
                </DynamicResponseField>

                <DynamicResponseField name="skip_overage_billing" type="boolean">
                  When true, overage for this feature is not posted to Stripe. Usage tracking and balance resets still behave normally.
                </DynamicResponseField>
              </Expandable>
            </DynamicResponseField>

            <DynamicResponseField name="usage_limits" type="object[]">
              List of hard usage caps per feature (max units per interval).

              <Expandable title="properties">
                <DynamicResponseField name="feature_id" type="string">
                  The feature this usage limit applies to.
                </DynamicResponseField>

                <DynamicResponseField name="enabled" type="boolean">
                  Whether this usage limit is enabled.
                </DynamicResponseField>

                <DynamicResponseField name="limit" type="number">
                  Maximum units allowed per interval.
                </DynamicResponseField>

                <DynamicResponseField name="interval" type="'day' | 'week' | 'month' | 'year'">
                  Interval for the cap, aligned to the customer's billing cycle.
                </DynamicResponseField>

                <DynamicResponseField name="filter" type="object">
                  When set, only usage from events whose properties match counts toward this cap. Omit to count all usage of the feature.

                  <Expandable title="properties">
                    <DynamicResponseField name="properties" type="object" />
                  </Expandable>
                </DynamicResponseField>
              </Expandable>
            </DynamicResponseField>

            <DynamicResponseField name="usage_alerts" type="object[]">
              List of usage alert configurations per feature.

              <Expandable title="properties">
                <DynamicResponseField name="feature_id" type="string">
                  The feature ID this alert applies to.
                </DynamicResponseField>

                <DynamicResponseField name="enabled" type="boolean">
                  Whether this usage alert is enabled.
                </DynamicResponseField>

                <DynamicResponseField name="threshold" type="number">
                  The threshold value that triggers the alert. For usage or remaining, this is an absolute count. For usage\_percentage or remaining\_percentage, this is a percentage (0-100).
                </DynamicResponseField>

                <DynamicResponseField name="threshold_type" type="'usage' | 'usage_percentage' | 'remaining' | 'remaining_percentage'">
                  Whether the threshold is an absolute count or a percentage of the usage allowance or remaining balance.
                </DynamicResponseField>

                <DynamicResponseField name="name" type="string">
                  Optional user-defined label to distinguish multiple alerts on the same feature.
                </DynamicResponseField>
              </Expandable>
            </DynamicResponseField>

            <DynamicResponseField name="overage_allowed" type="object[]">
              List of overage allowed controls per feature. When enabled, usage can exceed balance.

              <Expandable title="properties">
                <DynamicResponseField name="feature_id" type="string">
                  The feature ID this overage allowed control applies to.
                </DynamicResponseField>

                <DynamicResponseField name="enabled" type="boolean">
                  Whether overage is allowed for this feature.
                </DynamicResponseField>
              </Expandable>
            </DynamicResponseField>
          </Expandable>
        </DynamicResponseField>
      </Expandable>
    </DynamicResponseField>
  </Expandable>
</DynamicResponseField>

<DynamicResponseField name="config" type="object">
  Miscellaneous plan-level configuration flags.

  <Expandable title="properties">
    <DynamicResponseField name="ignore_past_due" type="boolean">
      If true, entitlements attached to this plan will still reset on schedule even when the customer's product is in a past\_due state.
    </DynamicResponseField>
  </Expandable>
</DynamicResponseField>

<DynamicResponseField name="billing_controls" type="object">
  Plan-level billing controls used as customer defaults.

  <Expandable title="properties">
    <DynamicResponseField name="auto_topups" type="object[]">
      List of auto top-up configurations per feature.

      <Expandable title="properties">
        <DynamicResponseField name="feature_id" type="string">
          The ID of the feature (credit balance) to auto top-up.
        </DynamicResponseField>

        <DynamicResponseField name="enabled" type="boolean">
          Whether auto top-up is enabled.
        </DynamicResponseField>

        <DynamicResponseField name="threshold" type="number">
          When the balance drops below this threshold, an auto top-up will be purchased.
        </DynamicResponseField>

        <DynamicResponseField name="quantity" type="number">
          Amount of credits to add per auto top-up.
        </DynamicResponseField>

        <DynamicResponseField name="purchase_limit" type="object">
          Optional rate limit to cap how often auto top-ups occur.

          <Expandable title="properties">
            <DynamicResponseField name="interval" type="'hour' | 'day' | 'week' | 'month'">
              The time interval for the purchase limit window.
            </DynamicResponseField>

            <DynamicResponseField name="interval_count" type="number">
              Number of intervals in the purchase limit window.
            </DynamicResponseField>

            <DynamicResponseField name="limit" type="number">
              Maximum number of auto top-ups allowed within the interval.
            </DynamicResponseField>
          </Expandable>
        </DynamicResponseField>

        <DynamicResponseField name="invoice_mode" type="boolean">
          When true, auto top-up creates a send\_invoice invoice instead of auto-charging.
        </DynamicResponseField>
      </Expandable>
    </DynamicResponseField>

    <DynamicResponseField name="spend_limits" type="object[]">
      List of overage spend limits per feature (caps overage spend).

      <Expandable title="properties">
        <DynamicResponseField name="feature_id" type="string">
          Optional feature ID this spend limit applies to.
        </DynamicResponseField>

        <DynamicResponseField name="enabled" type="boolean">
          Whether the overage spend limit is enabled.
        </DynamicResponseField>

        <DynamicResponseField name="limit_type" type="'absolute' | 'usage_percentage'">
          How overage\_limit is interpreted: an absolute overage cap (default) or a percentage of the main-plan allowance.
        </DynamicResponseField>

        <DynamicResponseField name="overage_limit" type="number">
          Overage cap for the feature: absolute units, or a percent (e.g. 120) when limit\_type is usage\_percentage.
        </DynamicResponseField>

        <DynamicResponseField name="skip_overage_billing" type="boolean">
          When true, overage for this feature is not posted to Stripe. Usage tracking and balance resets still behave normally.
        </DynamicResponseField>
      </Expandable>
    </DynamicResponseField>

    <DynamicResponseField name="usage_limits" type="object[]">
      List of hard usage caps per feature (max units per interval).

      <Expandable title="properties">
        <DynamicResponseField name="feature_id" type="string">
          The feature this usage limit applies to.
        </DynamicResponseField>

        <DynamicResponseField name="enabled" type="boolean">
          Whether this usage limit is enabled.
        </DynamicResponseField>

        <DynamicResponseField name="limit" type="number">
          Maximum units allowed per interval.
        </DynamicResponseField>

        <DynamicResponseField name="interval" type="'day' | 'week' | 'month' | 'year'">
          Interval for the cap, aligned to the customer's billing cycle.
        </DynamicResponseField>

        <DynamicResponseField name="filter" type="object">
          When set, only usage from events whose properties match counts toward this cap. Omit to count all usage of the feature.

          <Expandable title="properties">
            <DynamicResponseField name="properties" type="object" />
          </Expandable>
        </DynamicResponseField>
      </Expandable>
    </DynamicResponseField>

    <DynamicResponseField name="usage_alerts" type="object[]">
      List of usage alert configurations per feature.

      <Expandable title="properties">
        <DynamicResponseField name="feature_id" type="string">
          The feature ID this alert applies to.
        </DynamicResponseField>

        <DynamicResponseField name="enabled" type="boolean">
          Whether this usage alert is enabled.
        </DynamicResponseField>

        <DynamicResponseField name="threshold" type="number">
          The threshold value that triggers the alert. For usage or remaining, this is an absolute count. For usage\_percentage or remaining\_percentage, this is a percentage (0-100).
        </DynamicResponseField>

        <DynamicResponseField name="threshold_type" type="'usage' | 'usage_percentage' | 'remaining' | 'remaining_percentage'">
          Whether the threshold is an absolute count or a percentage of the usage allowance or remaining balance.
        </DynamicResponseField>

        <DynamicResponseField name="name" type="string">
          Optional user-defined label to distinguish multiple alerts on the same feature.
        </DynamicResponseField>
      </Expandable>
    </DynamicResponseField>

    <DynamicResponseField name="overage_allowed" type="object[]">
      List of overage allowed controls per feature. When enabled, usage can exceed balance.

      <Expandable title="properties">
        <DynamicResponseField name="feature_id" type="string">
          The feature ID this overage allowed control applies to.
        </DynamicResponseField>

        <DynamicResponseField name="enabled" type="boolean">
          Whether overage is allowed for this feature.
        </DynamicResponseField>
      </Expandable>
    </DynamicResponseField>
  </Expandable>
</DynamicResponseField>

<DynamicResponseField name="metadata" type="object">
  Arbitrary key-value metadata defined by you for your own use. Shared across all versions of the plan.
</DynamicResponseField>

<DynamicResponseField name="customer_eligibility" type="object">
  <Expandable title="properties">
    <DynamicResponseField name="trial_available" type="boolean">
      Whether the trial on this plan is available to this customer. For example, if the customer used the trial in the past, this will be false.
    </DynamicResponseField>

    <DynamicResponseField name="status" type="'active' | 'scheduled'">
      The customer's current status with this plan. 'active' if attached, 'scheduled' if pending activation.
    </DynamicResponseField>

    <DynamicResponseField name="canceling" type="boolean">
      Whether the customer's active instance of this plan is set to cancel.
    </DynamicResponseField>

    <DynamicResponseField name="trialing" type="boolean">
      Whether the customer is currently on a free trial of this plan.
    </DynamicResponseField>

    <DynamicResponseField name="attach_action" type="'activate' | 'upgrade' | 'downgrade' | 'none' | 'purchase'">
      The action that would occur if this plan were attached to the customer.
    </DynamicResponseField>
  </Expandable>
</DynamicResponseField>

<ResponseExample>
  ```json 200 theme={null}
  {
    "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": {}
  }
  ```
</ResponseExample>


## OpenAPI

````yaml openapi POST /v1/plans.create
openapi: 3.1.0
info:
  title: Autumn API
  version: 2.3.0
servers:
  - url: https://api.useautumn.com
    description: Production server
security:
  - secretKey: []
paths:
  /v1/plans.create:
    post:
      tags:
        - plans
      summary: Create a plan
      description: >-
        Creates a new plan with optional base price and feature configurations.


        Use this to programmatically create pricing plans. See [How plans
        work](/documentation/pricing/plans) for concepts.
      operationId: createPlan
      parameters:
        - name: x-api-version
          in: header
          required: true
          schema:
            type: string
            default: 2.3.0
          x-speakeasy-globals-hidden: true
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                plan_id:
                  type: string
                  minLength: 1
                  pattern: ^[a-zA-Z0-9_-]+$
                  description: The ID of the plan to create.
                group:
                  type: string
                  default: ''
                  description: >-
                    Group identifier for organizing related plans. Plans in the
                    same group are mutually exclusive.
                name:
                  type: string
                  minLength: 1
                  description: Display name of the plan.
                description:
                  anyOf:
                    - type: string
                    - type: 'null'
                  default: null
                  description: Optional description of the plan.
                add_on:
                  type: boolean
                  default: false
                  description: >-
                    If true, this plan can be attached alongside other plans.
                    Otherwise, attaching replaces existing plans in the same
                    group.
                auto_enable:
                  type: boolean
                  default: false
                  description: >-
                    If true, plan is automatically attached when a customer is
                    created. Use for free tiers.
                price:
                  type: object
                  properties:
                    amount:
                      type: number
                      description: Base price amount for the plan.
                    interval:
                      enum:
                        - one_off
                        - week
                        - month
                        - quarter
                        - semi_annual
                        - year
                      type: string
                      description: Billing interval (e.g. 'month', 'year').
                    interval_count:
                      type: number
                      description: Number of intervals per billing cycle. Defaults to 1.
                    additional_currencies:
                      type: array
                      items:
                        type: object
                        properties:
                          currency:
                            type: string
                            description: >-
                              Three-letter Stripe-supported currency code (e.g.
                              'eur', 'gbp').
                          amount:
                            type: number
                            description: >-
                              Price amount in this currency. Set explicitly per
                              currency, not converted from the base amount.
                        required:
                          - currency
                          - amount
                      description: >-
                        Base price amounts in additional currencies. The base
                        'amount' is in the org's default currency.
                  required:
                    - amount
                    - interval
                  description: >-
                    Base recurring price for the plan. Omit for free or
                    usage-only plans.
                items:
                  type: array
                  items:
                    type: object
                    properties:
                      feature_id:
                        type: string
                        description: The ID of the feature to configure.
                      included:
                        type: number
                        description: >-
                          Number of free units included. Balance resets to this
                          each interval for consumable features.
                      unlimited:
                        type: boolean
                        description: >-
                          If true, customer has unlimited access to this
                          feature.
                      reset:
                        type: object
                        properties:
                          interval:
                            enum:
                              - one_off
                              - minute
                              - hour
                              - day
                              - week
                              - month
                              - quarter
                              - semi_annual
                              - year
                            type: string
                            description: >-
                              Interval at which balance resets (e.g. 'month',
                              'year'). For consumable features only.
                          interval_count:
                            type: number
                            description: Number of intervals between resets. Defaults to 1.
                        required:
                          - interval
                        description: >-
                          Reset configuration for consumable features. Omit for
                          non-consumable features like seats.
                      price:
                        type: object
                        properties:
                          amount:
                            type: number
                            description: >-
                              Price per billing_units after included usage.
                              Either 'amount' or 'tiers' is required.
                          additional_currencies:
                            type: array
                            items:
                              type: object
                              properties:
                                currency:
                                  type: string
                                  description: >-
                                    Three-letter Stripe-supported currency code
                                    (e.g. 'eur', 'gbp').
                                amount:
                                  type: number
                                  description: >-
                                    Price amount in this currency. Set
                                    explicitly per currency, not converted from
                                    the base amount.
                              required:
                                - currency
                                - amount
                            description: >-
                              Amounts in additional currencies for this flat
                              price. The base 'amount' is in the org's default
                              currency. Only valid with 'amount', not 'tiers'.
                          tiers:
                            type: array
                            items:
                              type: object
                              properties:
                                to:
                                  anyOf:
                                    - type: number
                                    - const: inf
                                amount:
                                  type: number
                                flat_amount:
                                  type: number
                                additional_currencies:
                                  type: array
                                  items:
                                    type: object
                                    properties:
                                      currency:
                                        type: string
                                        description: >-
                                          Three-letter Stripe-supported currency
                                          code (e.g. 'eur', 'gbp').
                                      amount:
                                        type: number
                                        description: >-
                                          Per-unit amount for this tier in this
                                          currency.
                                      flat_amount:
                                        type: number
                                        description: >-
                                          Flat amount for this tier in this
                                          currency, if the tier uses one.
                                    required:
                                      - currency
                                  description: >-
                                    Per-currency amounts for this tier. Tier
                                    boundaries ('to') are shared across all
                                    currencies.
                              required:
                                - to
                            description: >-
                              Tiered pricing.  Either 'amount' or 'tiers' is
                              required.
                          tier_behavior:
                            enum:
                              - graduated
                              - volume
                            type: string
                          interval:
                            enum:
                              - one_off
                              - week
                              - month
                              - quarter
                              - semi_annual
                              - year
                            type: string
                            description: >-
                              Billing interval. For consumable features, should
                              match reset.interval.
                          interval_count:
                            type: number
                            default: 1
                            description: >-
                              Number of intervals per billing cycle. Defaults to
                              1.
                          billing_units:
                            type: number
                            default: 1
                            description: >-
                              Units per price increment. Usage is rounded UP
                              when billed (e.g. billing_units=100 means 101
                              rounds to 200).
                          billing_method:
                            enum:
                              - prepaid
                              - usage_based
                            type: string
                            description: >-
                              'prepaid' for upfront payment (seats),
                              'usage_based' for pay-as-you-go.
                          max_purchase:
                            anyOf:
                              - type: number
                              - type: 'null'
                            description: >-
                              Max units purchasable beyond included. E.g.
                              included=100, max_purchase=300 allows 400 total.
                              Null for no limit.
                        required:
                          - interval
                          - billing_method
                        description: >-
                          Pricing for usage beyond included units. Omit for free
                          features.
                      proration:
                        type: object
                        properties:
                          on_increase:
                            enum:
                              - bill_immediately
                              - prorate_immediately
                              - prorate_next_cycle
                              - bill_next_cycle
                            type: string
                            description: >-
                              Billing behavior when quantity increases
                              mid-cycle.
                          on_decrease:
                            enum:
                              - prorate
                              - prorate_immediately
                              - prorate_next_cycle
                              - none
                              - no_prorations
                            type: string
                            description: Credit behavior when quantity decreases mid-cycle.
                        required:
                          - on_increase
                          - on_decrease
                        description: >-
                          Proration settings for prepaid features. Controls
                          mid-cycle quantity change billing.
                      rollover:
                        type: object
                        properties:
                          max:
                            type: number
                            description: Max rollover units. Omit for unlimited rollover.
                          max_percentage:
                            type: number
                            description: >-
                              Maximum rollover as a percentage (0-100) of
                              included + prepaid grant. Mutually exclusive with
                              max.
                          expiry_duration_type:
                            enum:
                              - month
                              - forever
                            type: string
                            description: When rolled over units expire.
                          expiry_duration_length:
                            type: number
                            description: Number of periods before expiry.
                        required:
                          - expiry_duration_type
                        description: >-
                          Rollover config for unused units. If set, unused
                          included units carry over.
                    required:
                      - feature_id
                    title: PlanItem
                    description: >-
                      Configuration for a feature item in a plan, including
                      usage limits, pricing, and rollover settings.
                  description: >-
                    Feature configurations for this plan. Each item defines
                    included units, pricing, and reset behavior.
                licenses:
                  type: array
                  items:
                    type: object
                    properties:
                      license_plan_id:
                        type: string
                      included:
                        type: integer
                        minimum: 0
                        maximum: 9007199254740991
                      prepaid_only:
                        type: boolean
                      customize:
                        anyOf:
                          - type: object
                            properties:
                              price:
                                anyOf:
                                  - type: object
                                    properties:
                                      amount:
                                        type: number
                                        description: Base price amount for the plan.
                                      interval:
                                        enum:
                                          - one_off
                                          - week
                                          - month
                                          - quarter
                                          - semi_annual
                                          - year
                                        type: string
                                        description: Billing interval (e.g. 'month', 'year').
                                      interval_count:
                                        type: number
                                        description: >-
                                          Number of intervals per billing cycle.
                                          Defaults to 1.
                                      additional_currencies:
                                        type: array
                                        items:
                                          type: object
                                          properties:
                                            currency:
                                              type: string
                                              description: >-
                                                Three-letter Stripe-supported currency
                                                code (e.g. 'eur', 'gbp').
                                            amount:
                                              type: number
                                              description: >-
                                                Price amount in this currency. Set
                                                explicitly per currency, not converted
                                                from the base amount.
                                          required:
                                            - currency
                                            - amount
                                        description: >-
                                          Base price amounts in additional
                                          currencies. The base 'amount' is in the
                                          org's default currency.
                                    required:
                                      - amount
                                      - interval
                                    title: BasePrice
                                    description: Base price configuration for a plan.
                                  - type: 'null'
                              add_items:
                                type: array
                                items:
                                  type: object
                                  properties:
                                    feature_id:
                                      type: string
                                      description: The ID of the feature to configure.
                                    included:
                                      type: number
                                      description: >-
                                        Number of free units included. Balance
                                        resets to this each interval for
                                        consumable features.
                                    unlimited:
                                      type: boolean
                                      description: >-
                                        If true, customer has unlimited access
                                        to this feature.
                                    reset:
                                      type: object
                                      properties:
                                        interval:
                                          enum:
                                            - one_off
                                            - minute
                                            - hour
                                            - day
                                            - week
                                            - month
                                            - quarter
                                            - semi_annual
                                            - year
                                          type: string
                                          description: >-
                                            Interval at which balance resets (e.g.
                                            'month', 'year'). For consumable
                                            features only.
                                        interval_count:
                                          type: number
                                          description: >-
                                            Number of intervals between resets.
                                            Defaults to 1.
                                      required:
                                        - interval
                                      description: >-
                                        Reset configuration for consumable
                                        features. Omit for non-consumable
                                        features like seats.
                                    price:
                                      type: object
                                      properties:
                                        amount:
                                          type: number
                                          description: >-
                                            Price per billing_units after included
                                            usage. Either 'amount' or 'tiers' is
                                            required.
                                        additional_currencies:
                                          type: array
                                          items:
                                            type: object
                                            properties:
                                              currency:
                                                type: string
                                                description: >-
                                                  Three-letter Stripe-supported currency
                                                  code (e.g. 'eur', 'gbp').
                                              amount:
                                                type: number
                                                description: >-
                                                  Price amount in this currency. Set
                                                  explicitly per currency, not converted
                                                  from the base amount.
                                            required:
                                              - currency
                                              - amount
                                          description: >-
                                            Amounts in additional currencies for
                                            this flat price. The base 'amount' is in
                                            the org's default currency. Only valid
                                            with 'amount', not 'tiers'.
                                        tiers:
                                          type: array
                                          items:
                                            type: object
                                            properties:
                                              to:
                                                anyOf:
                                                  - type: number
                                                  - const: inf
                                              amount:
                                                type: number
                                              flat_amount:
                                                type: number
                                              additional_currencies:
                                                type: array
                                                items:
                                                  type: object
                                                  properties:
                                                    currency: {}
                                                    amount: {}
                                                    flat_amount: {}
                                                description: >-
                                                  Per-currency amounts for this tier. Tier
                                                  boundaries ('to') are shared across all
                                                  currencies.
                                            required:
                                              - to
                                          description: >-
                                            Tiered pricing.  Either 'amount' or
                                            'tiers' is required.
                                        tier_behavior:
                                          enum:
                                            - graduated
                                            - volume
                                          type: string
                                        interval:
                                          enum:
                                            - one_off
                                            - week
                                            - month
                                            - quarter
                                            - semi_annual
                                            - year
                                          type: string
                                          description: >-
                                            Billing interval. For consumable
                                            features, should match reset.interval.
                                        interval_count:
                                          type: number
                                          default: 1
                                          description: >-
                                            Number of intervals per billing cycle.
                                            Defaults to 1.
                                        billing_units:
                                          type: number
                                          default: 1
                                          description: >-
                                            Units per price increment. Usage is
                                            rounded UP when billed (e.g.
                                            billing_units=100 means 101 rounds to
                                            200).
                                        billing_method:
                                          enum:
                                            - prepaid
                                            - usage_based
                                          type: string
                                          description: >-
                                            'prepaid' for upfront payment (seats),
                                            'usage_based' for pay-as-you-go.
                                        max_purchase:
                                          anyOf:
                                            - type: number
                                            - type: 'null'
                                          description: >-
                                            Max units purchasable beyond included.
                                            E.g. included=100, max_purchase=300
                                            allows 400 total. Null for no limit.
                                      required:
                                        - interval
                                        - billing_method
                                      description: >-
                                        Pricing for usage beyond included units.
                                        Omit for free features.
                                    proration:
                                      type: object
                                      properties:
                                        on_increase:
                                          enum:
                                            - bill_immediately
                                            - prorate_immediately
                                            - prorate_next_cycle
                                            - bill_next_cycle
                                          type: string
                                          description: >-
                                            Billing behavior when quantity increases
                                            mid-cycle.
                                        on_decrease:
                                          enum:
                                            - prorate
                                            - prorate_immediately
                                            - prorate_next_cycle
                                            - none
                                            - no_prorations
                                          type: string
                                          description: >-
                                            Credit behavior when quantity decreases
                                            mid-cycle.
                                      required:
                                        - on_increase
                                        - on_decrease
                                      description: >-
                                        Proration settings for prepaid features.
                                        Controls mid-cycle quantity change
                                        billing.
                                    rollover:
                                      type: object
                                      properties:
                                        max:
                                          type: number
                                          description: >-
                                            Max rollover units. Omit for unlimited
                                            rollover.
                                        max_percentage:
                                          type: number
                                          description: >-
                                            Maximum rollover as a percentage (0-100)
                                            of included + prepaid grant. Mutually
                                            exclusive with max.
                                        expiry_duration_type:
                                          enum:
                                            - month
                                            - forever
                                          type: string
                                          description: When rolled over units expire.
                                        expiry_duration_length:
                                          type: number
                                          description: Number of periods before expiry.
                                      required:
                                        - expiry_duration_type
                                      description: >-
                                        Rollover config for unused units. If
                                        set, unused included units carry over.
                                  required:
                                    - feature_id
                                  title: PlanItem
                                  description: >-
                                    Configuration for a feature item in a plan,
                                    including usage limits, pricing, and
                                    rollover settings.
                              remove_items:
                                type: array
                                items:
                                  type: object
                                  properties:
                                    feature_id:
                                      type: string
                                      description: Match items linked to this feature.
                                    billing_method:
                                      enum:
                                        - prepaid
                                        - usage_based
                                      type: string
                                      description: >-
                                        Match items with this billing method
                                        (prepaid or usage_based).
                                    interval:
                                      anyOf:
                                        - enum:
                                            - one_off
                                            - week
                                            - month
                                            - quarter
                                            - semi_annual
                                            - year
                                          type: string
                                        - enum:
                                            - one_off
                                            - minute
                                            - hour
                                            - day
                                            - week
                                            - month
                                            - quarter
                                            - semi_annual
                                            - year
                                          type: string
                                      description: >-
                                        Match items with this interval. Accepts
                                        either a BillingInterval (price-side) or
                                        a ResetInterval (reset-side, includes
                                        day/hour/minute) so price-less items
                                        keyed by reset.interval can be
                                        disambiguated.
                                    interval_count:
                                      type: integer
                                      minimum: -9007199254740991
                                      maximum: 9007199254740991
                                      exclusiveMinimum: 0
                                      description: >-
                                        Match items with this interval_count.
                                        Disambiguates between items that share
                                        an interval but differ in count.
                                  title: PlanItemFilter
                                  description: >-
                                    Filter for matching plan items. All provided
                                    fields must match (AND).
                          - type: 'null'
                      metadata:
                        type: object
                        propertyNames:
                          type: string
                        additionalProperties: {}
                      version:
                        type: integer
                        minimum: 1
                        maximum: 9007199254740991
                        description: >-
                          Pin the link to a specific version of the license
                          plan. Omitted, an existing link keeps its pinned
                          version and a new link resolves to the latest.
                    required:
                      - license_plan_id
                  description: >-
                    Plans offered as assignable licenses under this plan. The
                    full set replaces existing links.
                free_trial:
                  type: object
                  properties:
                    duration_length:
                      type: number
                      description: Number of duration_type periods the trial lasts.
                    duration_type:
                      enum:
                        - day
                        - month
                        - year
                      type: string
                      default: month
                      description: Unit of time for the trial ('day', 'month', 'year').
                    card_required:
                      type: boolean
                      default: true
                      description: >-
                        If true, payment method required to start trial.
                        Customer is charged after trial ends.
                    on_end:
                      enum:
                        - bill
                        - revert
                      type: string
                      description: >-
                        Behavior when the trial ends. 'bill' charges the
                        customer (default). 'revert' expires the trial and
                        restores the customer's previous plan.
                  required:
                    - duration_length
                  description: >-
                    Free trial configuration. Customers can try this plan before
                    being charged.
                config:
                  type: object
                  properties:
                    ignore_past_due:
                      type: boolean
                      default: false
                      description: >-
                        If true, entitlements attached to this plan will still
                        reset on schedule even when the customer's product is in
                        a past_due state.
                  description: Miscellaneous plan-level configuration flags.
                billing_controls:
                  type: object
                  properties:
                    auto_topups:
                      type: array
                      items:
                        type: object
                        properties:
                          feature_id:
                            type: string
                            description: >-
                              The ID of the feature (credit balance) to auto
                              top-up.
                          enabled:
                            type: boolean
                            default: false
                            description: Whether auto top-up is enabled.
                          threshold:
                            type: number
                            minimum: 0
                            description: >-
                              When the balance drops below this threshold, an
                              auto top-up will be purchased.
                          quantity:
                            type: number
                            minimum: 1
                            description: Amount of credits to add per auto top-up.
                          purchase_limit:
                            type: object
                            properties:
                              interval:
                                enum:
                                  - hour
                                  - day
                                  - week
                                  - month
                                type: string
                                description: >-
                                  The time interval for the purchase limit
                                  window.
                              interval_count:
                                type: number
                                minimum: 1
                                default: 1
                                description: >-
                                  Number of intervals in the purchase limit
                                  window.
                              limit:
                                type: number
                                minimum: 1
                                description: >-
                                  Maximum number of auto top-ups allowed within
                                  the interval.
                            required:
                              - interval
                              - limit
                            description: >-
                              Optional rate limit to cap how often auto top-ups
                              occur.
                          invoice_mode:
                            type: boolean
                            description: >-
                              When true, auto top-up creates a send_invoice
                              invoice instead of auto-charging.
                        required:
                          - feature_id
                          - threshold
                          - quantity
                      description: List of auto top-up configurations per feature.
                    spend_limits:
                      type: array
                      items:
                        type: object
                        properties:
                          feature_id:
                            type: string
                            description: Optional feature ID this spend limit applies to.
                          enabled:
                            type: boolean
                            default: false
                            description: Whether the overage spend limit is enabled.
                          limit_type:
                            enum:
                              - absolute
                              - usage_percentage
                            type: string
                            description: >-
                              How overage_limit is interpreted: an absolute
                              overage cap (default) or a percentage of the
                              main-plan allowance.
                          overage_limit:
                            type: number
                            minimum: 0
                            description: >-
                              Overage cap for the feature: absolute units, or a
                              percent (e.g. 120) when limit_type is
                              usage_percentage.
                          skip_overage_billing:
                            type: boolean
                            description: >-
                              When true, overage for this feature is not posted
                              to Stripe. Usage tracking and balance resets still
                              behave normally.
                      description: >-
                        List of overage spend limits per feature (caps overage
                        spend).
                    usage_limits:
                      type: array
                      items:
                        type: object
                        properties:
                          feature_id:
                            type: string
                            description: The feature this usage limit applies to.
                          enabled:
                            type: boolean
                            default: true
                            description: Whether this usage limit is enabled.
                          limit:
                            type: number
                            minimum: 0
                            description: Maximum units allowed per interval.
                          interval:
                            enum:
                              - day
                              - week
                              - month
                              - year
                            type: string
                            description: >-
                              Interval for the cap, aligned to the customer's
                              billing cycle.
                          filter:
                            type: object
                            properties:
                              properties:
                                type: object
                                propertyNames:
                                  type: string
                                  minLength: 1
                                  maxLength: 64
                                additionalProperties:
                                  anyOf:
                                    - type: string
                                      minLength: 1
                                      maxLength: 128
                                    - type: number
                                    - type: boolean
                            required:
                              - properties
                            description: >-
                              When set, only usage from events whose properties
                              match counts toward this cap. Omit to count all
                              usage of the feature.
                        required:
                          - feature_id
                          - limit
                          - interval
                      description: >-
                        List of hard usage caps per feature (max units per
                        interval).
                    usage_alerts:
                      type: array
                      items:
                        type: object
                        properties:
                          feature_id:
                            type: string
                            description: The feature ID this alert applies to.
                          enabled:
                            type: boolean
                            default: true
                            description: Whether this usage alert is enabled.
                          threshold:
                            type: number
                            minimum: 0
                            description: >-
                              The threshold value that triggers the alert. For
                              usage or remaining, this is an absolute count. For
                              usage_percentage or remaining_percentage, this is
                              a percentage (0-100).
                          threshold_type:
                            enum:
                              - usage
                              - usage_percentage
                              - remaining
                              - remaining_percentage
                            type: string
                            description: >-
                              Whether the threshold is an absolute count or a
                              percentage of the usage allowance or remaining
                              balance.
                          name:
                            type: string
                            description: >-
                              Optional user-defined label to distinguish
                              multiple alerts on the same feature.
                        required:
                          - threshold
                          - threshold_type
                      description: List of usage alert configurations per feature.
                    overage_allowed:
                      type: array
                      items:
                        type: object
                        properties:
                          feature_id:
                            type: string
                            description: >-
                              The feature ID this overage allowed control
                              applies to.
                          enabled:
                            type: boolean
                            default: false
                            description: Whether overage is allowed for this feature.
                        required:
                          - feature_id
                      description: >-
                        List of overage allowed controls per feature. When
                        enabled, usage can exceed balance.
                  description: Plan-level billing controls used as customer defaults.
                metadata:
                  type: object
                  propertyNames:
                    type: string
                  additionalProperties: {}
                  description: >-
                    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_stripe:
                  type: boolean
                  default: true
              required:
                - plan_id
                - name
              title: CreatePlanParams
              examples:
                - plan_id: free_plan
                  name: Free
                  auto_enable: true
                  items:
                    - feature_id: messages
                      included: 100
                      reset:
                        interval: month
                - plan_id: pro_plan
                  name: Pro Plan
                  price:
                    amount: 10
                    interval: month
                  items:
                    - feature_id: messages
                      included: 1000
                      reset:
                        interval: month
                      price:
                        amount: 0.01
                        interval: month
                        billing_units: 1
                        billing_method: usage_based
                - plan_id: team_plan
                  name: Team Plan
                  price:
                    amount: 49
                    interval: month
                  items:
                    - feature_id: seats
                      included: 5
                      price:
                        amount: 10
                        interval: month
                        billing_units: 1
                        billing_method: prepaid
            example:
              plan_id: free_plan
              name: Free
              auto_enable: true
              items:
                - feature_id: messages
                  included: 100
                  reset:
                    interval: month
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: Unique identifier for the plan.
                  name:
                    type: string
                    description: Display name of the plan.
                  description:
                    anyOf:
                      - type: string
                      - type: 'null'
                    description: Optional description of the plan.
                  group:
                    anyOf:
                      - type: string
                      - type: 'null'
                    description: >-
                      Group identifier for organizing related plans. Plans in
                      the same group are mutually exclusive.
                  version:
                    type: number
                    description: >-
                      Version number of the plan. Incremented when plan
                      configuration changes.
                  add_on:
                    type: boolean
                    description: >-
                      Whether this is an add-on plan that can be attached
                      alongside a main plan.
                  auto_enable:
                    type: boolean
                    description: >-
                      If true, this plan is automatically attached when a
                      customer is created. Used for free plans.
                  price:
                    anyOf:
                      - type: object
                        properties:
                          amount:
                            type: number
                            description: Base price amount for the plan.
                          additional_currencies:
                            type: array
                            items:
                              type: object
                              properties:
                                currency:
                                  type: string
                                  description: >-
                                    Three-letter Stripe-supported currency code
                                    (e.g. 'eur', 'gbp').
                                amount:
                                  type: number
                                  description: >-
                                    Price amount in this currency. Set
                                    explicitly per currency, not converted from
                                    the base amount.
                              required:
                                - currency
                                - amount
                            description: >-
                              Base price amounts in additional currencies. The
                              base 'amount' is in the org's default currency.
                          interval:
                            enum:
                              - one_off
                              - week
                              - month
                              - quarter
                              - semi_annual
                              - year
                            type: string
                            description: Billing interval (e.g. 'month', 'year').
                          interval_count:
                            type: number
                            description: >-
                              Number of intervals per billing cycle. Defaults to
                              1.
                          display:
                            type: object
                            properties:
                              primary_text:
                                type: string
                                description: >-
                                  Main display text (e.g. '$10' or '100
                                  messages').
                              secondary_text:
                                type: string
                                description: >-
                                  Secondary display text (e.g. 'per month' or
                                  'then $0.5 per 100').
                            required:
                              - primary_text
                            description: >-
                              Display text for showing this price in pricing
                              pages.
                        required:
                          - amount
                          - interval
                      - type: 'null'
                    description: >-
                      Base recurring price for the plan. Null for free plans or
                      usage-only plans.
                  items:
                    type: array
                    items:
                      type: object
                      properties:
                        feature_id:
                          type: string
                          description: The ID of the feature this item configures.
                        feature:
                          type: object
                          properties:
                            id:
                              type: string
                              description: >-
                                The ID of the feature, used to refer to it in
                                other API calls like /track or /check.
                            name:
                              anyOf:
                                - type: string
                                - type: 'null'
                              description: The name of the feature.
                            type:
                              enum:
                                - static
                                - boolean
                                - single_use
                                - continuous_use
                                - credit_system
                                - ai_credit_system
                              type: string
                              description: The type of the feature
                            display:
                              anyOf:
                                - type: object
                                  properties:
                                    singular:
                                      type: string
                                      description: >-
                                        The singular display name for the
                                        feature.
                                    plural:
                                      type: string
                                      description: The plural display name for the feature.
                                  required:
                                    - singular
                                    - plural
                                - type: 'null'
                              description: >-
                                Singular and plural display names for the
                                feature.
                            credit_schema:
                              anyOf:
                                - type: array
                                  items:
                                    type: object
                                    properties:
                                      metered_feature_id:
                                        type: string
                                        description: >-
                                          The ID of the metered feature (should be
                                          a single_use feature).
                                      credit_cost:
                                        type: number
                                        description: The credit cost of the metered feature.
                                    required:
                                      - metered_feature_id
                                      - credit_cost
                                - type: 'null'
                              description: Credit cost schema for credit system features.
                            archived:
                              anyOf:
                                - type: boolean
                                - type: 'null'
                              description: Whether or not the feature is archived.
                          required:
                            - id
                            - type
                          description: The full feature object if expanded.
                        included:
                          type: number
                          description: >-
                            Number of free units included. For consumable
                            features, balance resets to this number each
                            interval.
                        unlimited:
                          type: boolean
                          description: >-
                            Whether the customer has unlimited access to this
                            feature.
                        reset:
                          anyOf:
                            - type: object
                              properties:
                                interval:
                                  enum:
                                    - one_off
                                    - minute
                                    - hour
                                    - day
                                    - week
                                    - month
                                    - quarter
                                    - semi_annual
                                    - year
                                  type: string
                                  description: >-
                                    The interval at which the feature balance
                                    resets (e.g. 'month', 'year'). For
                                    consumable features, usage resets to 0 and
                                    included units are restored.
                                interval_count:
                                  type: number
                                  description: >-
                                    Number of intervals between resets. Defaults
                                    to 1.
                              required:
                                - interval
                            - type: 'null'
                          description: >-
                            Reset configuration for consumable features. Null
                            for non-consumable features like seats where usage
                            persists across billing cycles.
                        price:
                          anyOf:
                            - type: object
                              properties:
                                amount:
                                  type: number
                                  description: >-
                                    Price per billing_units after included usage
                                    is consumed. Mutually exclusive with tiers.
                                additional_currencies:
                                  type: array
                                  items:
                                    type: object
                                    properties:
                                      currency:
                                        type: string
                                        description: >-
                                          Three-letter Stripe-supported currency
                                          code (e.g. 'eur', 'gbp').
                                      amount:
                                        type: number
                                        description: >-
                                          Price amount in this currency. Set
                                          explicitly per currency, not converted
                                          from the base amount.
                                    required:
                                      - currency
                                      - amount
                                  description: >-
                                    Amounts in additional currencies for this
                                    flat price. The base 'amount' is in the
                                    org's default currency. Only valid with
                                    'amount', not 'tiers' (tiered prices carry
                                    per-currency amounts on each tier).
                                tiers:
                                  type: array
                                  items:
                                    type: object
                                    properties:
                                      to:
                                        anyOf:
                                          - type: number
                                          - const: inf
                                      amount:
                                        type: number
                                      flat_amount:
                                        type: number
                                      additional_currencies:
                                        type: array
                                        items:
                                          type: object
                                          properties:
                                            currency:
                                              type: string
                                              description: >-
                                                Three-letter Stripe-supported currency
                                                code (e.g. 'eur', 'gbp').
                                            amount:
                                              type: number
                                              description: >-
                                                Per-unit amount for this tier in this
                                                currency.
                                            flat_amount:
                                              type: number
                                              description: >-
                                                Flat amount for this tier in this
                                                currency, if the tier uses one.
                                          required:
                                            - currency
                                    required:
                                      - to
                                      - amount
                                  description: >-
                                    Tiered pricing configuration. Each tier's
                                    'to' INCLUDES the included amount. Either
                                    'tiers' or 'amount' is required.
                                tier_behavior:
                                  enum:
                                    - graduated
                                    - volume
                                  type: string
                                interval:
                                  enum:
                                    - one_off
                                    - week
                                    - month
                                    - quarter
                                    - semi_annual
                                    - year
                                  type: string
                                  description: >-
                                    Billing interval for this price. For
                                    consumable features, should match
                                    reset.interval.
                                interval_count:
                                  type: number
                                  description: >-
                                    Number of intervals per billing cycle.
                                    Defaults to 1.
                                billing_units:
                                  type: number
                                  description: >-
                                    Number of units per price increment. Usage
                                    is rounded UP to the nearest billing_units
                                    when billed (e.g. billing_units=100 means
                                    101 usage rounds to 200).
                                billing_method:
                                  enum:
                                    - prepaid
                                    - usage_based
                                  type: string
                                  description: >-
                                    'prepaid' for features like seats where
                                    customers pay upfront, 'usage_based' for
                                    pay-as-you-go after included usage.
                                max_purchase:
                                  anyOf:
                                    - type: number
                                    - type: 'null'
                                  description: >-
                                    Maximum units a customer can purchase beyond
                                    included. E.g. if included=100 and
                                    max_purchase=300, customer can use up to 400
                                    total before usage is capped. Null for no
                                    limit.
                              required:
                                - interval
                                - billing_units
                                - billing_method
                                - max_purchase
                            - type: 'null'
                          description: >-
                            Pricing configuration for usage beyond included
                            units. Null if feature is entirely free.
                        display:
                          type: object
                          properties:
                            primary_text:
                              type: string
                              description: >-
                                Main display text (e.g. '$10' or '100
                                messages').
                            secondary_text:
                              type: string
                              description: >-
                                Secondary display text (e.g. 'per month' or
                                'then $0.5 per 100').
                          required:
                            - primary_text
                          description: Display text for showing this item in pricing pages.
                        rollover:
                          type: object
                          properties:
                            max:
                              anyOf:
                                - type: number
                                - type: 'null'
                              description: >-
                                Maximum rollover units. Null for unlimited
                                rollover.
                            max_percentage:
                              anyOf:
                                - type: number
                                - type: 'null'
                              description: >-
                                Maximum rollover as a percentage (0-100) of
                                included + prepaid grant. Mutually exclusive
                                with max.
                            expiry_duration_type:
                              enum:
                                - month
                                - forever
                              type: string
                              description: When rolled over units expire.
                            expiry_duration_length:
                              type: number
                              description: Number of periods before expiry.
                          required:
                            - max
                            - expiry_duration_type
                          description: >-
                            Rollover configuration for unused units. If set,
                            unused included units roll over to the next period.
                      required:
                        - feature_id
                        - included
                        - unlimited
                        - reset
                        - price
                    description: >-
                      Feature configurations included in this plan. Each item
                      defines included units, pricing, and reset behavior for a
                      feature.
                  free_trial:
                    type: object
                    properties:
                      duration_length:
                        type: number
                        description: Number of duration_type periods the trial lasts.
                      duration_type:
                        enum:
                          - day
                          - month
                          - year
                        type: string
                        description: >-
                          Unit of time for the trial duration ('day', 'month',
                          'year').
                      card_required:
                        type: boolean
                        description: >-
                          Whether a payment method is required to start the
                          trial. If true, customer will be charged after trial
                          ends.
                      on_end:
                        anyOf:
                          - enum:
                              - bill
                              - revert
                            type: string
                          - type: 'null'
                        description: >-
                          Behavior when the trial ends. 'bill' charges the
                          customer (default). 'revert' expires the trial and
                          restores the customer's previous plan.
                    required:
                      - duration_length
                      - duration_type
                      - card_required
                    description: >-
                      Free trial configuration. If set, new customers can try
                      this plan before being charged.
                  created_at:
                    type: number
                    description: Unix timestamp (ms) when the plan was created.
                  env:
                    enum:
                      - sandbox
                      - live
                    type: string
                    description: Environment this plan belongs to ('sandbox' or 'live').
                  archived:
                    type: boolean
                    description: >-
                      Whether the plan is archived. Archived plans cannot be
                      attached to new customers.
                  base_variant_id:
                    anyOf:
                      - type: string
                      - type: 'null'
                    description: >-
                      Deprecated. Use variant_details.base_plan_id instead. If
                      this is a variant, the ID of the base plan it was created
                      from.
                  variant_details:
                    type: object
                    properties:
                      base_plan_id:
                        type: string
                        description: The ID of the base plan this variant was derived from.
                      customize:
                        type: object
                        properties:
                          price:
                            anyOf:
                              - type: object
                                properties:
                                  amount:
                                    type: number
                                    description: Base price amount for the plan.
                                  interval:
                                    enum:
                                      - one_off
                                      - week
                                      - month
                                      - quarter
                                      - semi_annual
                                      - year
                                    type: string
                                    description: Billing interval (e.g. 'month', 'year').
                                  interval_count:
                                    type: number
                                    description: >-
                                      Number of intervals per billing cycle.
                                      Defaults to 1.
                                  additional_currencies:
                                    type: array
                                    items:
                                      type: object
                                      properties:
                                        currency:
                                          type: string
                                          description: >-
                                            Three-letter Stripe-supported currency
                                            code (e.g. 'eur', 'gbp').
                                        amount:
                                          type: number
                                          description: >-
                                            Price amount in this currency. Set
                                            explicitly per currency, not converted
                                            from the base amount.
                                      required:
                                        - currency
                                        - amount
                                    description: >-
                                      Base price amounts in additional
                                      currencies. The base 'amount' is in the
                                      org's default currency.
                                required:
                                  - amount
                                  - interval
                                title: BasePrice
                                description: Base price configuration for a plan.
                              - type: 'null'
                            description: >-
                              Override the base price of the plan. Pass null to
                              remove the base price.
                          add_items:
                            type: array
                            items:
                              type: object
                              properties:
                                feature_id:
                                  type: string
                                  description: The ID of the feature to configure.
                                included:
                                  type: number
                                  description: >-
                                    Number of free units included. Balance
                                    resets to this each interval for consumable
                                    features.
                                unlimited:
                                  type: boolean
                                  description: >-
                                    If true, customer has unlimited access to
                                    this feature.
                                reset:
                                  type: object
                                  properties:
                                    interval:
                                      enum:
                                        - one_off
                                        - minute
                                        - hour
                                        - day
                                        - week
                                        - month
                                        - quarter
                                        - semi_annual
                                        - year
                                      type: string
                                      description: >-
                                        Interval at which balance resets (e.g.
                                        'month', 'year'). For consumable
                                        features only.
                                    interval_count:
                                      type: number
                                      description: >-
                                        Number of intervals between resets.
                                        Defaults to 1.
                                  required:
                                    - interval
                                  description: >-
                                    Reset configuration for consumable features.
                                    Omit for non-consumable features like seats.
                                price:
                                  type: object
                                  properties:
                                    amount:
                                      type: number
                                      description: >-
                                        Price per billing_units after included
                                        usage. Either 'amount' or 'tiers' is
                                        required.
                                    additional_currencies:
                                      type: array
                                      items:
                                        type: object
                                        properties:
                                          currency:
                                            type: string
                                            description: >-
                                              Three-letter Stripe-supported currency
                                              code (e.g. 'eur', 'gbp').
                                          amount:
                                            type: number
                                            description: >-
                                              Price amount in this currency. Set
                                              explicitly per currency, not converted
                                              from the base amount.
                                        required:
                                          - currency
                                          - amount
                                      description: >-
                                        Amounts in additional currencies for
                                        this flat price. The base 'amount' is in
                                        the org's default currency. Only valid
                                        with 'amount', not 'tiers'.
                                    tiers:
                                      type: array
                                      items:
                                        type: object
                                        properties:
                                          to:
                                            anyOf:
                                              - type: number
                                              - const: inf
                                          amount:
                                            type: number
                                          flat_amount:
                                            type: number
                                          additional_currencies:
                                            type: array
                                            items:
                                              type: object
                                              properties:
                                                currency:
                                                  type: string
                                                  description: >-
                                                    Three-letter Stripe-supported currency
                                                    code (e.g. 'eur', 'gbp').
                                                amount:
                                                  type: number
                                                  description: >-
                                                    Per-unit amount for this tier in this
                                                    currency.
                                                flat_amount:
                                                  type: number
                                                  description: >-
                                                    Flat amount for this tier in this
                                                    currency, if the tier uses one.
                                              required:
                                                - currency
                                        required:
                                          - to
                                          - amount
                                      description: >-
                                        Tiered pricing.  Either 'amount' or
                                        'tiers' is required.
                                    tier_behavior:
                                      enum:
                                        - graduated
                                        - volume
                                      type: string
                                    interval:
                                      enum:
                                        - one_off
                                        - week
                                        - month
                                        - quarter
                                        - semi_annual
                                        - year
                                      type: string
                                      description: >-
                                        Billing interval. For consumable
                                        features, should match reset.interval.
                                    interval_count:
                                      type: number
                                      default: 1
                                      description: >-
                                        Number of intervals per billing cycle.
                                        Defaults to 1.
                                    billing_units:
                                      type: number
                                      default: 1
                                      description: >-
                                        Units per price increment. Usage is
                                        rounded UP when billed (e.g.
                                        billing_units=100 means 101 rounds to
                                        200).
                                    billing_method:
                                      enum:
                                        - prepaid
                                        - usage_based
                                      type: string
                                      description: >-
                                        'prepaid' for upfront payment (seats),
                                        'usage_based' for pay-as-you-go.
                                    max_purchase:
                                      anyOf:
                                        - type: number
                                        - type: 'null'
                                      description: >-
                                        Max units purchasable beyond included.
                                        E.g. included=100, max_purchase=300
                                        allows 400 total. Null for no limit.
                                  required:
                                    - interval
                                    - billing_method
                                  description: >-
                                    Pricing for usage beyond included units.
                                    Omit for free features.
                                proration:
                                  type: object
                                  properties:
                                    on_increase:
                                      enum:
                                        - bill_immediately
                                        - prorate_immediately
                                        - prorate_next_cycle
                                        - bill_next_cycle
                                      type: string
                                      description: >-
                                        Billing behavior when quantity increases
                                        mid-cycle.
                                    on_decrease:
                                      enum:
                                        - prorate
                                        - prorate_immediately
                                        - prorate_next_cycle
                                        - none
                                        - no_prorations
                                      type: string
                                      description: >-
                                        Credit behavior when quantity decreases
                                        mid-cycle.
                                  required:
                                    - on_increase
                                    - on_decrease
                                  description: >-
                                    Proration settings for prepaid features.
                                    Controls mid-cycle quantity change billing.
                                rollover:
                                  type: object
                                  properties:
                                    max:
                                      type: number
                                      description: >-
                                        Max rollover units. Omit for unlimited
                                        rollover.
                                    max_percentage:
                                      type: number
                                      description: >-
                                        Maximum rollover as a percentage (0-100)
                                        of included + prepaid grant. Mutually
                                        exclusive with max.
                                    expiry_duration_type:
                                      enum:
                                        - month
                                        - forever
                                      type: string
                                      description: When rolled over units expire.
                                    expiry_duration_length:
                                      type: number
                                      description: Number of periods before expiry.
                                  required:
                                    - expiry_duration_type
                                  description: >-
                                    Rollover config for unused units. If set,
                                    unused included units carry over.
                              required:
                                - feature_id
                              title: PlanItem
                              description: >-
                                Configuration for a feature item in a plan,
                                including usage limits, pricing, and rollover
                                settings.
                            description: Items to add to the plan.
                          remove_items:
                            type: array
                            items:
                              type: object
                              properties:
                                feature_id:
                                  type: string
                                  description: Match items linked to this feature.
                                billing_method:
                                  enum:
                                    - prepaid
                                    - usage_based
                                  type: string
                                  description: >-
                                    Match items with this billing method
                                    (prepaid or usage_based).
                                interval:
                                  anyOf:
                                    - enum:
                                        - one_off
                                        - week
                                        - month
                                        - quarter
                                        - semi_annual
                                        - year
                                      type: string
                                    - enum:
                                        - one_off
                                        - minute
                                        - hour
                                        - day
                                        - week
                                        - month
                                        - quarter
                                        - semi_annual
                                        - year
                                      type: string
                                  description: >-
                                    Match items with this interval. Accepts
                                    either a BillingInterval (price-side) or a
                                    ResetInterval (reset-side, includes
                                    day/hour/minute) so price-less items keyed
                                    by reset.interval can be disambiguated.
                                interval_count:
                                  type: integer
                                  minimum: -9007199254740991
                                  maximum: 9007199254740991
                                  exclusiveMinimum: 0
                                  description: >-
                                    Match items with this interval_count.
                                    Disambiguates between items that share an
                                    interval but differ in count.
                              title: PlanItemFilter
                              description: >-
                                Filter for matching plan items. All provided
                                fields must match (AND).
                            description: Filters selecting items to remove from the plan.
                          free_trial:
                            anyOf:
                              - type: object
                                properties:
                                  duration_length:
                                    type: number
                                    description: >-
                                      Number of duration_type periods the trial
                                      lasts.
                                  duration_type:
                                    enum:
                                      - day
                                      - month
                                      - year
                                    type: string
                                    default: month
                                    description: >-
                                      Unit of time for the trial ('day',
                                      'month', 'year').
                                  card_required:
                                    type: boolean
                                    default: true
                                    description: >-
                                      If true, payment method required to start
                                      trial. Customer is charged after trial
                                      ends.
                                  on_end:
                                    enum:
                                      - bill
                                      - revert
                                    type: string
                                    description: >-
                                      Behavior when the trial ends. 'bill'
                                      charges the customer (default). 'revert'
                                      expires the trial and restores the
                                      customer's previous plan.
                                required:
                                  - duration_length
                                title: FreeTrialParams
                                description: Free trial configuration for a plan.
                              - type: 'null'
                            description: >-
                              Override the plan's default free trial. Pass an
                              object to set a custom trial, or null to remove
                              the trial entirely.
                          billing_controls:
                            type: object
                            properties:
                              auto_topups:
                                type: array
                                items:
                                  type: object
                                  properties:
                                    feature_id:
                                      type: string
                                      description: >-
                                        The ID of the feature (credit balance)
                                        to auto top-up.
                                    enabled:
                                      type: boolean
                                      default: false
                                      description: Whether auto top-up is enabled.
                                    threshold:
                                      type: number
                                      minimum: 0
                                      description: >-
                                        When the balance drops below this
                                        threshold, an auto top-up will be
                                        purchased.
                                    quantity:
                                      type: number
                                      minimum: 1
                                      description: >-
                                        Amount of credits to add per auto
                                        top-up.
                                    purchase_limit:
                                      type: object
                                      properties:
                                        interval:
                                          enum:
                                            - hour
                                            - day
                                            - week
                                            - month
                                          type: string
                                          description: >-
                                            The time interval for the purchase limit
                                            window.
                                        interval_count:
                                          type: number
                                          minimum: 1
                                          default: 1
                                          description: >-
                                            Number of intervals in the purchase
                                            limit window.
                                        limit:
                                          type: number
                                          minimum: 1
                                          description: >-
                                            Maximum number of auto top-ups allowed
                                            within the interval.
                                      required:
                                        - interval
                                        - limit
                                      description: >-
                                        Optional rate limit to cap how often
                                        auto top-ups occur.
                                    invoice_mode:
                                      type: boolean
                                      description: >-
                                        When true, auto top-up creates a
                                        send_invoice invoice instead of
                                        auto-charging.
                                  required:
                                    - feature_id
                                    - threshold
                                    - quantity
                                description: >-
                                  List of auto top-up configurations per
                                  feature.
                              spend_limits:
                                type: array
                                items:
                                  type: object
                                  properties:
                                    feature_id:
                                      type: string
                                      description: >-
                                        Optional feature ID this spend limit
                                        applies to.
                                    enabled:
                                      type: boolean
                                      default: false
                                      description: >-
                                        Whether the overage spend limit is
                                        enabled.
                                    limit_type:
                                      enum:
                                        - absolute
                                        - usage_percentage
                                      type: string
                                      description: >-
                                        How overage_limit is interpreted: an
                                        absolute overage cap (default) or a
                                        percentage of the main-plan allowance.
                                    overage_limit:
                                      type: number
                                      minimum: 0
                                      description: >-
                                        Overage cap for the feature: absolute
                                        units, or a percent (e.g. 120) when
                                        limit_type is usage_percentage.
                                    skip_overage_billing:
                                      type: boolean
                                      description: >-
                                        When true, overage for this feature is
                                        not posted to Stripe. Usage tracking and
                                        balance resets still behave normally.
                                description: >-
                                  List of overage spend limits per feature (caps
                                  overage spend).
                              usage_limits:
                                type: array
                                items:
                                  type: object
                                  properties:
                                    feature_id:
                                      type: string
                                      description: The feature this usage limit applies to.
                                    enabled:
                                      type: boolean
                                      default: true
                                      description: Whether this usage limit is enabled.
                                    limit:
                                      type: number
                                      minimum: 0
                                      description: Maximum units allowed per interval.
                                    interval:
                                      enum:
                                        - day
                                        - week
                                        - month
                                        - year
                                      type: string
                                      description: >-
                                        Interval for the cap, aligned to the
                                        customer's billing cycle.
                                    filter:
                                      type: object
                                      properties:
                                        properties:
                                          type: object
                                          propertyNames:
                                            type: string
                                            minLength: 1
                                            maxLength: 64
                                          additionalProperties: {}
                                      required:
                                        - properties
                                      description: >-
                                        When set, only usage from events whose
                                        properties match counts toward this cap.
                                        Omit to count all usage of the feature.
                                  required:
                                    - feature_id
                                    - limit
                                    - interval
                                description: >-
                                  List of hard usage caps per feature (max units
                                  per interval).
                              usage_alerts:
                                type: array
                                items:
                                  type: object
                                  properties:
                                    feature_id:
                                      type: string
                                      description: The feature ID this alert applies to.
                                    enabled:
                                      type: boolean
                                      default: true
                                      description: Whether this usage alert is enabled.
                                    threshold:
                                      type: number
                                      minimum: 0
                                      description: >-
                                        The threshold value that triggers the
                                        alert. For usage or remaining, this is
                                        an absolute count. For usage_percentage
                                        or remaining_percentage, this is a
                                        percentage (0-100).
                                    threshold_type:
                                      enum:
                                        - usage
                                        - usage_percentage
                                        - remaining
                                        - remaining_percentage
                                      type: string
                                      description: >-
                                        Whether the threshold is an absolute
                                        count or a percentage of the usage
                                        allowance or remaining balance.
                                    name:
                                      type: string
                                      description: >-
                                        Optional user-defined label to
                                        distinguish multiple alerts on the same
                                        feature.
                                  required:
                                    - threshold
                                    - threshold_type
                                description: >-
                                  List of usage alert configurations per
                                  feature.
                              overage_allowed:
                                type: array
                                items:
                                  type: object
                                  properties:
                                    feature_id:
                                      type: string
                                      description: >-
                                        The feature ID this overage allowed
                                        control applies to.
                                    enabled:
                                      type: boolean
                                      default: false
                                      description: >-
                                        Whether overage is allowed for this
                                        feature.
                                  required:
                                    - feature_id
                                description: >-
                                  List of overage allowed controls per feature.
                                  When enabled, usage can exceed balance.
                            description: >-
                              Override the plan's billing controls (auto
                              top-ups, spend limits, usage limits, usage alerts,
                              overage allowed) for this customer.
                        additionalProperties: false
                        description: >-
                          The customization that transforms the base plan into
                          this variant.
                    required:
                      - base_plan_id
                    description: >-
                      Details about how this variant relates to its latest base
                      plan.
                  config:
                    type: object
                    properties:
                      ignore_past_due:
                        type: boolean
                        default: false
                        description: >-
                          If true, entitlements attached to this plan will still
                          reset on schedule even when the customer's product is
                          in a past_due state.
                    description: Miscellaneous plan-level configuration flags.
                  billing_controls:
                    type: object
                    properties:
                      auto_topups:
                        type: array
                        items:
                          type: object
                          properties:
                            feature_id:
                              type: string
                              description: >-
                                The ID of the feature (credit balance) to auto
                                top-up.
                            enabled:
                              type: boolean
                              default: false
                              description: Whether auto top-up is enabled.
                            threshold:
                              type: number
                              minimum: 0
                              description: >-
                                When the balance drops below this threshold, an
                                auto top-up will be purchased.
                            quantity:
                              type: number
                              minimum: 1
                              description: Amount of credits to add per auto top-up.
                            purchase_limit:
                              type: object
                              properties:
                                interval:
                                  enum:
                                    - hour
                                    - day
                                    - week
                                    - month
                                  type: string
                                  description: >-
                                    The time interval for the purchase limit
                                    window.
                                interval_count:
                                  type: number
                                  minimum: 1
                                  default: 1
                                  description: >-
                                    Number of intervals in the purchase limit
                                    window.
                                limit:
                                  type: number
                                  minimum: 1
                                  description: >-
                                    Maximum number of auto top-ups allowed
                                    within the interval.
                              required:
                                - interval
                                - limit
                              description: >-
                                Optional rate limit to cap how often auto
                                top-ups occur.
                            invoice_mode:
                              type: boolean
                              description: >-
                                When true, auto top-up creates a send_invoice
                                invoice instead of auto-charging.
                          required:
                            - feature_id
                            - threshold
                            - quantity
                        description: List of auto top-up configurations per feature.
                      spend_limits:
                        type: array
                        items:
                          type: object
                          properties:
                            feature_id:
                              type: string
                              description: Optional feature ID this spend limit applies to.
                            enabled:
                              type: boolean
                              default: false
                              description: Whether the overage spend limit is enabled.
                            limit_type:
                              enum:
                                - absolute
                                - usage_percentage
                              type: string
                              description: >-
                                How overage_limit is interpreted: an absolute
                                overage cap (default) or a percentage of the
                                main-plan allowance.
                            overage_limit:
                              type: number
                              minimum: 0
                              description: >-
                                Overage cap for the feature: absolute units, or
                                a percent (e.g. 120) when limit_type is
                                usage_percentage.
                            skip_overage_billing:
                              type: boolean
                              description: >-
                                When true, overage for this feature is not
                                posted to Stripe. Usage tracking and balance
                                resets still behave normally.
                        description: >-
                          List of overage spend limits per feature (caps overage
                          spend).
                      usage_limits:
                        type: array
                        items:
                          type: object
                          properties:
                            feature_id:
                              type: string
                              description: The feature this usage limit applies to.
                            enabled:
                              type: boolean
                              default: true
                              description: Whether this usage limit is enabled.
                            limit:
                              type: number
                              minimum: 0
                              description: Maximum units allowed per interval.
                            interval:
                              enum:
                                - day
                                - week
                                - month
                                - year
                              type: string
                              description: >-
                                Interval for the cap, aligned to the customer's
                                billing cycle.
                            filter:
                              type: object
                              properties:
                                properties:
                                  type: object
                                  propertyNames:
                                    type: string
                                    minLength: 1
                                    maxLength: 64
                                  additionalProperties: {}
                              required:
                                - properties
                              description: >-
                                When set, only usage from events whose
                                properties match counts toward this cap. Omit to
                                count all usage of the feature.
                          required:
                            - feature_id
                            - limit
                            - interval
                        description: >-
                          List of hard usage caps per feature (max units per
                          interval).
                      usage_alerts:
                        type: array
                        items:
                          type: object
                          properties:
                            feature_id:
                              type: string
                              description: The feature ID this alert applies to.
                            enabled:
                              type: boolean
                              default: true
                              description: Whether this usage alert is enabled.
                            threshold:
                              type: number
                              minimum: 0
                              description: >-
                                The threshold value that triggers the alert. For
                                usage or remaining, this is an absolute count.
                                For usage_percentage or remaining_percentage,
                                this is a percentage (0-100).
                            threshold_type:
                              enum:
                                - usage
                                - usage_percentage
                                - remaining
                                - remaining_percentage
                              type: string
                              description: >-
                                Whether the threshold is an absolute count or a
                                percentage of the usage allowance or remaining
                                balance.
                            name:
                              type: string
                              description: >-
                                Optional user-defined label to distinguish
                                multiple alerts on the same feature.
                          required:
                            - threshold
                            - threshold_type
                        description: List of usage alert configurations per feature.
                      overage_allowed:
                        type: array
                        items:
                          type: object
                          properties:
                            feature_id:
                              type: string
                              description: >-
                                The feature ID this overage allowed control
                                applies to.
                            enabled:
                              type: boolean
                              default: false
                              description: Whether overage is allowed for this feature.
                          required:
                            - feature_id
                        description: >-
                          List of overage allowed controls per feature. When
                          enabled, usage can exceed balance.
                    description: Plan-level billing controls used as customer defaults.
                  metadata:
                    type: object
                    propertyNames:
                      type: string
                    additionalProperties: {}
                    description: >-
                      Arbitrary key-value metadata defined by you for your own
                      use. Shared across all versions of the plan.
                  customer_eligibility:
                    type: object
                    properties:
                      trial_available:
                        type: boolean
                        description: >-
                          Whether the trial on this plan is available to this
                          customer. For example, if the customer used the trial
                          in the past, this will be false.
                      status:
                        enum:
                          - active
                          - scheduled
                        type: string
                        description: >-
                          The customer's current status with this plan. 'active'
                          if attached, 'scheduled' if pending activation.
                      canceling:
                        type: boolean
                        description: >-
                          Whether the customer's active instance of this plan is
                          set to cancel.
                      trialing:
                        type: boolean
                        description: >-
                          Whether the customer is currently on a free trial of
                          this plan.
                      attach_action:
                        enum:
                          - activate
                          - upgrade
                          - downgrade
                          - none
                          - purchase
                        type: string
                        description: >-
                          The action that would occur if this plan were attached
                          to the customer.
                    required:
                      - attach_action
                required:
                  - id
                  - name
                  - description
                  - group
                  - version
                  - add_on
                  - auto_enable
                  - price
                  - items
                  - created_at
                  - env
                  - archived
                  - base_variant_id
                  - config
                  - metadata
                description: >-
                  A plan defines a set of features, pricing, and entitlements
                  that can be attached to customers.
                examples:
                  - 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: {}
              example:
                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: {}
      x-codeSamples:
        - lang: typescript
          label: Typescript (SDK)
          source: |-
            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",
                  },
                },
              ],
            });
        - lang: python
          label: Python (SDK)
          source: |-
            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,
            )
components:
  securitySchemes:
    secretKey:
      type: http
      scheme: bearer
      bearerFormat: JWT

````