> ## Documentation Index
> Fetch the complete documentation index at: https://autumn-b9b4c0fb-dev.mintlify.site/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.

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, in major currency units (e.g. dollars).
    </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="pooled" type="boolean">
      Whether entity-level grants contribute to a shared customer balance.
    </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>

    <DynamicParamField body="feature_override" type="object">
      Overrides fields of this item's feature for customers on this plan (e.g. a credit system's credit\_schema).

      <Expandable title="properties">
        <DynamicParamField body="credit_schema" type="object | object[]">
          For credit system features: replaces the feature's credit\_schema entirely for customers on this plan.

          <Expandable title="properties">
            <DynamicParamField body="metered_feature_id" type="string">
              ID of the metered feature that draws from this credit system.
            </DynamicParamField>

            <DynamicParamField body="billing_units" type="number">
              Number of metered-feature units priced together. Defaults to one when omitted.
            </DynamicParamField>

            <DynamicParamField body="dimensions.{key}" type="object">
              Named rates chosen by event properties. The most specific match sets the rate; with no match the item's own rate applies.

              <Expandable title="properties">
                <DynamicParamField body="match.{key}" type="string" required>
                  Event properties this entry applies to. Every key must equal the tracked property, compared as strings.
                </DynamicParamField>

                <DynamicParamField body="priority" type="integer">
                  Breaks ties between dimensions that match the same number of keys. Higher wins.
                </DynamicParamField>

                <DynamicParamField body="tier_behavior" type="any" required />

                <DynamicParamField body="tiers" type="object[]" required>
                  <Expandable title="properties">
                    <DynamicParamField body="to" type="number" required>
                      Inclusive upper usage boundary for this graduated tier. The final tier must be 'inf'.
                    </DynamicParamField>

                    <DynamicParamField body="credit_cost" type="number" required>
                      Credits consumed per billing-unit group within this tier.
                    </DynamicParamField>
                  </Expandable>
                </DynamicParamField>
              </Expandable>
            </DynamicParamField>

            <DynamicParamField body="multipliers.{key}" type="object">
              Named adjustments chosen by event properties. Every match applies: factors multiply, then adds are summed.

              <Expandable title="properties">
                <DynamicParamField body="match.{key}" type="string" required>
                  Event properties this entry applies to. Every key must equal the tracked property, compared as strings.
                </DynamicParamField>

                <DynamicParamField body="factor" type="number">
                  Multiplies the matched rate. All matching multipliers stack.
                </DynamicParamField>

                <DynamicParamField body="add" type="number">
                  Added to the rate after every factor is applied, in credits per billing-unit group.
                </DynamicParamField>
              </Expandable>
            </DynamicParamField>

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

            <DynamicParamField body="tiers" type="object[]">
              <Expandable title="properties">
                <DynamicParamField body="to" type="number" required>
                  Inclusive upper usage boundary for this graduated tier. The final tier must be 'inf'.
                </DynamicParamField>

                <DynamicParamField body="credit_cost" type="number" required>
                  Credits consumed per billing-unit group within this tier.
                </DynamicParamField>
              </Expandable>
            </DynamicParamField>

            <DynamicParamField body="credit_cost" type="number">
              Credits consumed per billing-unit group.
            </DynamicParamField>
          </Expandable>
        </DynamicParamField>

        <DynamicParamField body="markups" type="object">
          For AI credit system features: replaces the feature's markup chain entirely for customers on this plan. An unset level means no markup at that level rather than inheriting the feature's.

          <Expandable title="properties">
            <DynamicParamField body="default_markup" type="number">
              Default percentage markup for customers on this plan. Use -100 to make usage free.
            </DynamicParamField>

            <DynamicParamField body="provider_markups.{key}" type="object | null">
              Per-provider markup percentages for customers on this plan.

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

            <DynamicParamField body="model_markups.{key}" type="object | null">
              Per-model markup overrides for customers on this plan.

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

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

                <DynamicParamField body="output_cost" type="number" />
              </Expandable>
            </DynamicParamField>
          </Expandable>
        </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="version_slug" type="string" />

    <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, in major currency units (e.g. dollars).
            </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="pooled" type="boolean">
              Whether entity-level grants contribute to a shared customer balance.
            </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>

            <DynamicParamField body="feature_override" type="object">
              Overrides fields of this item's feature for customers on this plan (e.g. a credit system's credit\_schema).

              <Expandable title="properties">
                <DynamicParamField body="credit_schema" type="object | object[]">
                  For credit system features: replaces the feature's credit\_schema entirely for customers on this plan.

                  <Expandable title="properties">
                    <DynamicParamField body="metered_feature_id" type="string">
                      ID of the metered feature that draws from this credit system.
                    </DynamicParamField>

                    <DynamicParamField body="billing_units" type="number">
                      Number of metered-feature units priced together. Defaults to one when omitted.
                    </DynamicParamField>

                    <DynamicParamField body="dimensions.{key}" type="object">
                      Named rates chosen by event properties. The most specific match sets the rate; with no match the item's own rate applies.

                      <Expandable title="properties">
                        <DynamicParamField body="match.{key}" type="string" required>
                          Event properties this entry applies to. Every key must equal the tracked property, compared as strings.
                        </DynamicParamField>

                        <DynamicParamField body="priority" type="integer">
                          Breaks ties between dimensions that match the same number of keys. Higher wins.
                        </DynamicParamField>

                        <DynamicParamField body="tier_behavior" type="any" required />

                        <DynamicParamField body="tiers" type="object[]" required>
                          <Expandable title="properties">
                            <DynamicParamField body="to" type="number" required>
                              Inclusive upper usage boundary for this graduated tier. The final tier must be 'inf'.
                            </DynamicParamField>

                            <DynamicParamField body="credit_cost" type="number" required>
                              Credits consumed per billing-unit group within this tier.
                            </DynamicParamField>
                          </Expandable>
                        </DynamicParamField>
                      </Expandable>
                    </DynamicParamField>

                    <DynamicParamField body="multipliers.{key}" type="object">
                      Named adjustments chosen by event properties. Every match applies: factors multiply, then adds are summed.

                      <Expandable title="properties">
                        <DynamicParamField body="match.{key}" type="string" required>
                          Event properties this entry applies to. Every key must equal the tracked property, compared as strings.
                        </DynamicParamField>

                        <DynamicParamField body="factor" type="number">
                          Multiplies the matched rate. All matching multipliers stack.
                        </DynamicParamField>

                        <DynamicParamField body="add" type="number">
                          Added to the rate after every factor is applied, in credits per billing-unit group.
                        </DynamicParamField>
                      </Expandable>
                    </DynamicParamField>

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

                    <DynamicParamField body="tiers" type="object[]">
                      <Expandable title="properties">
                        <DynamicParamField body="to" type="number" required>
                          Inclusive upper usage boundary for this graduated tier. The final tier must be 'inf'.
                        </DynamicParamField>

                        <DynamicParamField body="credit_cost" type="number" required>
                          Credits consumed per billing-unit group within this tier.
                        </DynamicParamField>
                      </Expandable>
                    </DynamicParamField>

                    <DynamicParamField body="credit_cost" type="number">
                      Credits consumed per billing-unit group.
                    </DynamicParamField>
                  </Expandable>
                </DynamicParamField>

                <DynamicParamField body="markups" type="object">
                  For AI credit system features: replaces the feature's markup chain entirely for customers on this plan. An unset level means no markup at that level rather than inheriting the feature's.

                  <Expandable title="properties">
                    <DynamicParamField body="default_markup" type="number">
                      Default percentage markup for customers on this plan. Use -100 to make usage free.
                    </DynamicParamField>

                    <DynamicParamField body="provider_markups.{key}" type="object | null">
                      Per-provider markup percentages for customers on this plan.

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

                    <DynamicParamField body="model_markups.{key}" type="object | null">
                      Per-model markup overrides for customers on this plan.

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

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

                        <DynamicParamField body="output_cost" type="number" />
                      </Expandable>
                    </DynamicParamField>
                  </Expandable>
                </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>

            <DynamicParamField body="included" type="number">
              Match items whose grant equals this included usage. Omitted is a wildcard.
            </DynamicParamField>
          </Expandable>
        </DynamicParamField>
      </Expandable>
    </DynamicParamField>

    <DynamicParamField body="metadata" type="object" />
  </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, a payment method is required to start the trial and the customer is charged when it ends. Defaults to false.
    </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. Pass count to set the current window's consumed top-ups.

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

            <DynamicParamField body="count" type="number">
              Set the current window's consumed auto top-up count. Omit to leave runtime state unchanged.
            </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="anchor" type="'billing_cycle' | 'utc'">
          Window alignment. 'billing\_cycle' phases the interval to the customer's renewal time; 'utc' aligns to the UTC calendar.
        </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="basis" type="'balance' | 'included' | 'recurring' | 'usage_limit'">
          What 100% means. balance: every grant on the feature. included: the plan allowance only. recurring: grants that reset. usage\_limit: the cap of the usage limit with the same feature and filter.
        </DynamicParamField>

        <DynamicParamField body="filter" type="object">
          Only valid with basis usage\_limit. Points the alert at the usage limit carrying the same filter.

          <Expandable title="properties">
            <DynamicParamField body="properties.{key}" type="string" required />
          </Expandable>
        </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="version_slug" type="string | null">
  User-facing version identity. Defaults to v\{n} when the version is minted.
</DynamicResponseField>

<DynamicResponseField name="active" type="boolean">
  Whether this is the active version of the plan. At most one version is active.
</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, in major currency units (e.g. dollars).
    </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>

    <DynamicResponseField name="processors" type="object">
      Payment processors this base price is connected to. Omitted when unset.

      <Expandable title="properties">
        <DynamicResponseField name="stripe" type="object | null">
          <Expandable title="properties">
            <DynamicResponseField name="price_id" type="string">
              Stripe price ID. For prepaid with included > 0 this is the V2 price.
            </DynamicResponseField>
          </Expandable>
        </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="pooled" type="boolean">
      Whether entity-level grants contribute to a shared customer balance.
    </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>

        <DynamicResponseField name="processors" type="object">
          Payment processors this item price is connected to. Omitted when unset.

          <Expandable title="properties">
            <DynamicResponseField name="stripe" type="object | null">
              <Expandable title="properties">
                <DynamicResponseField name="price_id" type="string">
                  Stripe price ID. For prepaid with included > 0 this is the V2 price.
                </DynamicResponseField>
              </Expandable>
            </DynamicResponseField>
          </Expandable>
        </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>

    <DynamicResponseField name="feature_override" type="object">
      Overrides fields of this item's feature for customers on this plan (e.g. a credit system's credit\_schema).

      <Expandable title="properties">
        <DynamicResponseField name="credit_schema" type="object | object[]">
          For credit system features: replaces the feature's credit\_schema entirely for customers on this plan.

          <Expandable title="properties">
            <DynamicResponseField name="metered_feature_id" type="string">
              ID of the metered feature that draws from this credit system.
            </DynamicResponseField>

            <DynamicResponseField name="billing_units" type="number">
              Number of metered-feature units priced together. Defaults to one when omitted.
            </DynamicResponseField>

            <DynamicResponseField name="dimensions.{key}" type="object">
              Named rates chosen by event properties. The most specific match sets the rate; with no match the item's own rate applies.

              <Expandable title="properties">
                <DynamicResponseField name="match.{key}" type="string">
                  Event properties this entry applies to. Every key must equal the tracked property, compared as strings.
                </DynamicResponseField>

                <DynamicResponseField name="priority" type="integer">
                  Breaks ties between dimensions that match the same number of keys. Higher wins.
                </DynamicResponseField>

                <DynamicResponseField name="tier_behavior" type="any" />

                <DynamicResponseField name="tiers" type="object[]">
                  <Expandable title="properties">
                    <DynamicResponseField name="to" type="number">
                      Inclusive upper usage boundary for this graduated tier. The final tier must be 'inf'.
                    </DynamicResponseField>

                    <DynamicResponseField name="credit_cost" type="number">
                      Credits consumed per billing-unit group within this tier.
                    </DynamicResponseField>
                  </Expandable>
                </DynamicResponseField>
              </Expandable>
            </DynamicResponseField>

            <DynamicResponseField name="multipliers.{key}" type="object">
              Named adjustments chosen by event properties. Every match applies: factors multiply, then adds are summed.

              <Expandable title="properties">
                <DynamicResponseField name="match.{key}" type="string">
                  Event properties this entry applies to. Every key must equal the tracked property, compared as strings.
                </DynamicResponseField>

                <DynamicResponseField name="factor" type="number">
                  Multiplies the matched rate. All matching multipliers stack.
                </DynamicResponseField>

                <DynamicResponseField name="add" type="number">
                  Added to the rate after every factor is applied, in credits per billing-unit group.
                </DynamicResponseField>
              </Expandable>
            </DynamicResponseField>

            <DynamicResponseField name="tier_behavior" type="any" />

            <DynamicResponseField name="tiers" type="object[]">
              <Expandable title="properties">
                <DynamicResponseField name="to" type="number">
                  Inclusive upper usage boundary for this graduated tier. The final tier must be 'inf'.
                </DynamicResponseField>

                <DynamicResponseField name="credit_cost" type="number">
                  Credits consumed per billing-unit group within this tier.
                </DynamicResponseField>
              </Expandable>
            </DynamicResponseField>

            <DynamicResponseField name="credit_cost" type="number">
              Credits consumed per billing-unit group.
            </DynamicResponseField>
          </Expandable>
        </DynamicResponseField>

        <DynamicResponseField name="markups" type="object">
          For AI credit system features: replaces the feature's markup chain entirely for customers on this plan. An unset level means no markup at that level rather than inheriting the feature's.

          <Expandable title="properties">
            <DynamicResponseField name="default_markup" type="number">
              Default percentage markup for customers on this plan. Use -100 to make usage free.
            </DynamicResponseField>

            <DynamicResponseField name="provider_markups.{key}" type="object | null">
              Per-provider markup percentages for customers on this plan.

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

            <DynamicResponseField name="model_markups.{key}" type="object | null">
              Per-model markup overrides for customers on this plan.

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

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

                <DynamicResponseField name="output_cost" type="number" />
              </Expandable>
            </DynamicResponseField>
          </Expandable>
        </DynamicResponseField>
      </Expandable>
    </DynamicResponseField>
  </Expandable>
</DynamicResponseField>

<DynamicResponseField name="processors" type="object">
  Payment processors this plan is connected to. Omitted when unset.

  <Expandable title="properties">
    <DynamicResponseField name="stripe" type="object | null">
      <Expandable title="properties">
        <DynamicResponseField name="product_id" type="string">
          Stripe product ID this plan is billed under.
        </DynamicResponseField>

        <DynamicResponseField name="additional_product_ids" type="string[]">
          Extra Stripe product IDs aliased to this plan.
        </DynamicResponseField>
      </Expandable>
    </DynamicResponseField>

    <DynamicResponseField name="revenuecat" type="object | null">
      <Expandable title="properties">
        <DynamicResponseField name="products" type="object[]">
          Every RevenueCat product that maps to this plan. Replaces the current set.

          <Expandable title="properties">
            <DynamicResponseField name="product_id" type="string">
              RevenueCat product ID that grants this plan when purchased.
            </DynamicResponseField>

            <DynamicResponseField name="feature_quantities" type="object[]">
              Prepaid quantities granted when this specific RevenueCat product is purchased, in feature units.

              <Expandable title="properties">
                <DynamicResponseField name="feature_id" type="string" />

                <DynamicResponseField name="quantity" type="number" />
              </Expandable>
            </DynamicResponseField>
          </Expandable>
        </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="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="anchor" type="'billing_cycle' | 'utc'">
          Window alignment. 'billing\_cycle' phases the interval to the customer's renewal time; 'utc' aligns to the UTC calendar.
        </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.{key}" type="string" />
          </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="basis" type="'balance' | 'included' | 'recurring' | 'usage_limit'">
          What 100% means. balance: every grant on the feature. included: the plan allowance only. recurring: grants that reset. usage\_limit: the cap of the usage limit with the same feature and filter.
        </DynamicResponseField>

        <DynamicResponseField name="filter" type="object">
          Only valid with basis usage\_limit. Points the alert at the usage limit carrying the same filter.

          <Expandable title="properties">
            <DynamicResponseField name="properties.{key}" type="string" />
          </Expandable>
        </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>

<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, in major currency units (e.g. dollars).
            </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="pooled" type="boolean">
              Whether entity-level grants contribute to a shared customer balance.
            </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>

            <DynamicResponseField name="feature_override" type="object">
              Overrides fields of this item's feature for customers on this plan (e.g. a credit system's credit\_schema).

              <Expandable title="properties">
                <DynamicResponseField name="credit_schema" type="object | object[]">
                  For credit system features: replaces the feature's credit\_schema entirely for customers on this plan.

                  <Expandable title="properties">
                    <DynamicResponseField name="metered_feature_id" type="string">
                      ID of the metered feature that draws from this credit system.
                    </DynamicResponseField>

                    <DynamicResponseField name="billing_units" type="number">
                      Number of metered-feature units priced together. Defaults to one when omitted.
                    </DynamicResponseField>

                    <DynamicResponseField name="dimensions.{key}" type="object">
                      Named rates chosen by event properties. The most specific match sets the rate; with no match the item's own rate applies.

                      <Expandable title="properties">
                        <DynamicResponseField name="match.{key}" type="string">
                          Event properties this entry applies to. Every key must equal the tracked property, compared as strings.
                        </DynamicResponseField>

                        <DynamicResponseField name="priority" type="integer">
                          Breaks ties between dimensions that match the same number of keys. Higher wins.
                        </DynamicResponseField>

                        <DynamicResponseField name="tier_behavior" type="any" />

                        <DynamicResponseField name="tiers" type="object[]">
                          <Expandable title="properties">
                            <DynamicResponseField name="to" type="number">
                              Inclusive upper usage boundary for this graduated tier. The final tier must be 'inf'.
                            </DynamicResponseField>

                            <DynamicResponseField name="credit_cost" type="number">
                              Credits consumed per billing-unit group within this tier.
                            </DynamicResponseField>
                          </Expandable>
                        </DynamicResponseField>
                      </Expandable>
                    </DynamicResponseField>

                    <DynamicResponseField name="multipliers.{key}" type="object">
                      Named adjustments chosen by event properties. Every match applies: factors multiply, then adds are summed.

                      <Expandable title="properties">
                        <DynamicResponseField name="match.{key}" type="string">
                          Event properties this entry applies to. Every key must equal the tracked property, compared as strings.
                        </DynamicResponseField>

                        <DynamicResponseField name="factor" type="number">
                          Multiplies the matched rate. All matching multipliers stack.
                        </DynamicResponseField>

                        <DynamicResponseField name="add" type="number">
                          Added to the rate after every factor is applied, in credits per billing-unit group.
                        </DynamicResponseField>
                      </Expandable>
                    </DynamicResponseField>

                    <DynamicResponseField name="tier_behavior" type="any" />

                    <DynamicResponseField name="tiers" type="object[]">
                      <Expandable title="properties">
                        <DynamicResponseField name="to" type="number">
                          Inclusive upper usage boundary for this graduated tier. The final tier must be 'inf'.
                        </DynamicResponseField>

                        <DynamicResponseField name="credit_cost" type="number">
                          Credits consumed per billing-unit group within this tier.
                        </DynamicResponseField>
                      </Expandable>
                    </DynamicResponseField>

                    <DynamicResponseField name="credit_cost" type="number">
                      Credits consumed per billing-unit group.
                    </DynamicResponseField>
                  </Expandable>
                </DynamicResponseField>

                <DynamicResponseField name="markups" type="object">
                  For AI credit system features: replaces the feature's markup chain entirely for customers on this plan. An unset level means no markup at that level rather than inheriting the feature's.

                  <Expandable title="properties">
                    <DynamicResponseField name="default_markup" type="number">
                      Default percentage markup for customers on this plan. Use -100 to make usage free.
                    </DynamicResponseField>

                    <DynamicResponseField name="provider_markups.{key}" type="object | null">
                      Per-provider markup percentages for customers on this plan.

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

                    <DynamicResponseField name="model_markups.{key}" type="object | null">
                      Per-model markup overrides for customers on this plan.

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

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

                        <DynamicResponseField name="output_cost" type="number" />
                      </Expandable>
                    </DynamicResponseField>
                  </Expandable>
                </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>

            <DynamicResponseField name="included" type="number">
              Match items whose grant equals this included usage. Omitted is a wildcard.
            </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, a payment method is required to start the trial and the customer is charged when it ends. Defaults to false.
            </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. Pass count to set the current window's consumed top-ups.

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

                    <DynamicResponseField name="count" type="number">
                      Set the current window's consumed auto top-up count. Omit to leave runtime state unchanged.
                    </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="anchor" type="'billing_cycle' | 'utc'">
                  Window alignment. 'billing\_cycle' phases the interval to the customer's renewal time; 'utc' aligns to the UTC calendar.
                </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.{key}" type="string" />
                  </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="basis" type="'balance' | 'included' | 'recurring' | 'usage_limit'">
                  What 100% means. balance: every grant on the feature. included: the plan allowance only. recurring: grants that reset. usage\_limit: the cap of the usage limit with the same feature and filter.
                </DynamicResponseField>

                <DynamicResponseField name="filter" type="object">
                  Only valid with basis usage\_limit. Points the alert at the usage limit carrying the same filter.

                  <Expandable title="properties">
                    <DynamicResponseField name="properties.{key}" type="string" />
                  </Expandable>
                </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="upsert_licenses" type="object[]">
          License links to add or override for this customer, keyed by license\_plan\_id. Omitted fields inherit the plan catalog link (included defaults to 1 when the license is not in the catalog). A bare entry restores the license to pure catalog inheritance.

          <Expandable title="properties">
            <DynamicResponseField name="license_plan_id" type="string" />

            <DynamicResponseField name="version_slug" type="string" />

            <DynamicResponseField name="included" type="integer" />

            <DynamicResponseField name="prepaid_only" type="boolean" />

            <DynamicResponseField name="customize" type="object | null">
              <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, in major currency units (e.g. dollars).
                    </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[]">
                  <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="pooled" type="boolean">
                      Whether entity-level grants contribute to a shared customer balance.
                    </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>

                    <DynamicResponseField name="feature_override" type="object">
                      Overrides fields of this item's feature for customers on this plan (e.g. a credit system's credit\_schema).

                      <Expandable title="properties">
                        <DynamicResponseField name="credit_schema" type="object | object[]">
                          For credit system features: replaces the feature's credit\_schema entirely for customers on this plan.

                          <Expandable title="properties">
                            <DynamicResponseField name="metered_feature_id" type="string">
                              ID of the metered feature that draws from this credit system.
                            </DynamicResponseField>

                            <DynamicResponseField name="billing_units" type="number">
                              Number of metered-feature units priced together. Defaults to one when omitted.
                            </DynamicResponseField>

                            <DynamicResponseField name="dimensions.{key}" type="object">
                              Named rates chosen by event properties. The most specific match sets the rate; with no match the item's own rate applies.

                              <Expandable title="properties">
                                <DynamicResponseField name="match.{key}" type="string">
                                  Event properties this entry applies to. Every key must equal the tracked property, compared as strings.
                                </DynamicResponseField>

                                <DynamicResponseField name="priority" type="integer">
                                  Breaks ties between dimensions that match the same number of keys. Higher wins.
                                </DynamicResponseField>

                                <DynamicResponseField name="tier_behavior" type="any" />

                                <DynamicResponseField name="tiers" type="object[]">
                                  <Expandable title="properties">
                                    <DynamicResponseField name="to" type="number">
                                      Inclusive upper usage boundary for this graduated tier. The final tier must be 'inf'.
                                    </DynamicResponseField>

                                    <DynamicResponseField name="credit_cost" type="number">
                                      Credits consumed per billing-unit group within this tier.
                                    </DynamicResponseField>
                                  </Expandable>
                                </DynamicResponseField>
                              </Expandable>
                            </DynamicResponseField>

                            <DynamicResponseField name="multipliers.{key}" type="object">
                              Named adjustments chosen by event properties. Every match applies: factors multiply, then adds are summed.

                              <Expandable title="properties">
                                <DynamicResponseField name="match.{key}" type="string">
                                  Event properties this entry applies to. Every key must equal the tracked property, compared as strings.
                                </DynamicResponseField>

                                <DynamicResponseField name="factor" type="number">
                                  Multiplies the matched rate. All matching multipliers stack.
                                </DynamicResponseField>

                                <DynamicResponseField name="add" type="number">
                                  Added to the rate after every factor is applied, in credits per billing-unit group.
                                </DynamicResponseField>
                              </Expandable>
                            </DynamicResponseField>

                            <DynamicResponseField name="tier_behavior" type="any" />

                            <DynamicResponseField name="tiers" type="object[]">
                              <Expandable title="properties">
                                <DynamicResponseField name="to" type="number">
                                  Inclusive upper usage boundary for this graduated tier. The final tier must be 'inf'.
                                </DynamicResponseField>

                                <DynamicResponseField name="credit_cost" type="number">
                                  Credits consumed per billing-unit group within this tier.
                                </DynamicResponseField>
                              </Expandable>
                            </DynamicResponseField>

                            <DynamicResponseField name="credit_cost" type="number">
                              Credits consumed per billing-unit group.
                            </DynamicResponseField>
                          </Expandable>
                        </DynamicResponseField>

                        <DynamicResponseField name="markups" type="object">
                          For AI credit system features: replaces the feature's markup chain entirely for customers on this plan. An unset level means no markup at that level rather than inheriting the feature's.

                          <Expandable title="properties">
                            <DynamicResponseField name="default_markup" type="number">
                              Default percentage markup for customers on this plan. Use -100 to make usage free.
                            </DynamicResponseField>

                            <DynamicResponseField name="provider_markups.{key}" type="object | null">
                              Per-provider markup percentages for customers on this plan.

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

                            <DynamicResponseField name="model_markups.{key}" type="object | null">
                              Per-model markup overrides for customers on this plan.

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

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

                                <DynamicResponseField name="output_cost" type="number" />
                              </Expandable>
                            </DynamicResponseField>
                          </Expandable>
                        </DynamicResponseField>
                      </Expandable>
                    </DynamicResponseField>
                  </Expandable>
                </DynamicResponseField>

                <DynamicResponseField name="remove_items" type="object[]">
                  <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>

                    <DynamicResponseField name="included" type="number">
                      Match items whose grant equals this included usage. Omitted is a wildcard.
                    </DynamicResponseField>
                  </Expandable>
                </DynamicResponseField>
              </Expandable>
            </DynamicResponseField>

            <DynamicResponseField name="metadata" type="object" />
          </Expandable>
        </DynamicResponseField>

        <DynamicResponseField name="remove_licenses" type="object[]">
          License links to drop, keyed by license\_plan\_id. Parallel to remove\_items.

          <Expandable title="properties">
            <DynamicResponseField name="license_plan_id" type="string" />
          </Expandable>
        </DynamicResponseField>
      </Expandable>
    </DynamicResponseField>
  </Expandable>
</DynamicResponseField>

<ResponseExample>
  ```json 200 theme={null}
  {
    "id": "pro",
    "name": "Pro Plan",
    "description": null,
    "group": null,
    "version": 1,
    "version_slug": "v1",
    "active": true,
    "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.4.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.4.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, in major currency units
                        (e.g. dollars).
                    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
                        maximum: 10000000000000
                        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.
                      pooled:
                        type: boolean
                        default: false
                        description: >-
                          Whether entity-level grants contribute to a shared
                          customer balance.
                      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.
                      feature_override:
                        type: object
                        properties:
                          credit_schema:
                            type: array
                            items:
                              anyOf:
                                - type: object
                                  properties:
                                    metered_feature_id:
                                      type: string
                                      minLength: 1
                                      description: >-
                                        ID of the metered feature that draws
                                        from this credit system.
                                    billing_units:
                                      type: number
                                      exclusiveMinimum: 0
                                      description: >-
                                        Number of metered-feature units priced
                                        together. Defaults to one when omitted.
                                    dimensions:
                                      type: object
                                      propertyNames:
                                        type: string
                                        minLength: 1
                                        maxLength: 64
                                      additionalProperties:
                                        anyOf:
                                          - type: object
                                            properties:
                                              match:
                                                type: object
                                                propertyNames:
                                                  type: string
                                                additionalProperties:
                                                  anyOf:
                                                    - type: string
                                                    - type: number
                                                    - type: boolean
                                                description: >-
                                                  Event properties this entry applies to.
                                                  Every key must equal the tracked
                                                  property, compared as strings.
                                              priority:
                                                type: integer
                                                minimum: -9007199254740991
                                                maximum: 9007199254740991
                                                description: >-
                                                  Breaks ties between dimensions that
                                                  match the same number of keys. Higher
                                                  wins.
                                              tier_behavior:
                                                const: graduated
                                              tiers:
                                                type: array
                                                minItems: 1
                                                items:
                                                  type: object
                                                  properties:
                                                    to:
                                                      anyOf:
                                                        - type: number
                                                          exclusiveMinimum: 0
                                                        - enum:
                                                            - inf
                                                          type: string
                                                      description: >-
                                                        Inclusive upper usage boundary for this
                                                        graduated tier. The final tier must be
                                                        'inf'.
                                                    credit_cost:
                                                      type: number
                                                      minimum: 0
                                                      description: >-
                                                        Credits consumed per billing-unit group
                                                        within this tier.
                                                  required:
                                                    - to
                                                    - credit_cost
                                            required:
                                              - match
                                              - tier_behavior
                                              - tiers
                                            additionalProperties: false
                                          - type: object
                                            properties:
                                              match:
                                                type: object
                                                propertyNames:
                                                  type: string
                                                additionalProperties:
                                                  anyOf:
                                                    - type: string
                                                    - type: number
                                                    - type: boolean
                                                description: >-
                                                  Event properties this entry applies to.
                                                  Every key must equal the tracked
                                                  property, compared as strings.
                                              priority:
                                                type: integer
                                                minimum: -9007199254740991
                                                maximum: 9007199254740991
                                                description: >-
                                                  Breaks ties between dimensions that
                                                  match the same number of keys. Higher
                                                  wins.
                                              credit_cost:
                                                type: number
                                                minimum: 0
                                                description: >-
                                                  Credits consumed per billing-unit group
                                                  when this dimension matches.
                                            required:
                                              - match
                                              - credit_cost
                                            additionalProperties: false
                                      description: >-
                                        Named rates chosen by event properties.
                                        The most specific match sets the rate;
                                        with no match the item's own rate
                                        applies.
                                    multipliers:
                                      type: object
                                      propertyNames:
                                        type: string
                                        minLength: 1
                                        maxLength: 64
                                      additionalProperties:
                                        type: object
                                        properties:
                                          match:
                                            type: object
                                            propertyNames:
                                              type: string
                                            additionalProperties:
                                              anyOf:
                                                - type: string
                                                - type: number
                                                - type: boolean
                                            description: >-
                                              Event properties this entry applies to.
                                              Every key must equal the tracked
                                              property, compared as strings.
                                          factor:
                                            type: number
                                            exclusiveMinimum: 0
                                            description: >-
                                              Multiplies the matched rate. All
                                              matching multipliers stack.
                                          add:
                                            type: number
                                            description: >-
                                              Added to the rate after every factor is
                                              applied, in credits per billing-unit
                                              group.
                                        required:
                                          - match
                                        additionalProperties: false
                                      description: >-
                                        Named adjustments chosen by event
                                        properties. Every match applies: factors
                                        multiply, then adds are summed.
                                    tier_behavior:
                                      const: graduated
                                    tiers:
                                      type: array
                                      minItems: 1
                                      items:
                                        type: object
                                        properties:
                                          to:
                                            anyOf:
                                              - type: number
                                                exclusiveMinimum: 0
                                              - enum:
                                                  - inf
                                                type: string
                                            description: >-
                                              Inclusive upper usage boundary for this
                                              graduated tier. The final tier must be
                                              'inf'.
                                          credit_cost:
                                            type: number
                                            minimum: 0
                                            description: >-
                                              Credits consumed per billing-unit group
                                              within this tier.
                                        required:
                                          - to
                                          - credit_cost
                                  required:
                                    - metered_feature_id
                                    - tier_behavior
                                    - tiers
                                  additionalProperties: false
                                - type: object
                                  properties:
                                    metered_feature_id:
                                      type: string
                                      minLength: 1
                                      description: >-
                                        ID of the metered feature that draws
                                        from this credit system.
                                    billing_units:
                                      type: number
                                      exclusiveMinimum: 0
                                      description: >-
                                        Number of metered-feature units priced
                                        together. Defaults to one when omitted.
                                    dimensions:
                                      type: object
                                      propertyNames:
                                        type: string
                                        minLength: 1
                                        maxLength: 64
                                      additionalProperties:
                                        anyOf:
                                          - type: object
                                            properties:
                                              match:
                                                type: object
                                                propertyNames:
                                                  type: string
                                                additionalProperties:
                                                  anyOf:
                                                    - type: string
                                                    - type: number
                                                    - type: boolean
                                                description: >-
                                                  Event properties this entry applies to.
                                                  Every key must equal the tracked
                                                  property, compared as strings.
                                              priority:
                                                type: integer
                                                minimum: -9007199254740991
                                                maximum: 9007199254740991
                                                description: >-
                                                  Breaks ties between dimensions that
                                                  match the same number of keys. Higher
                                                  wins.
                                              tier_behavior:
                                                const: graduated
                                              tiers:
                                                type: array
                                                minItems: 1
                                                items:
                                                  type: object
                                                  properties:
                                                    to:
                                                      anyOf:
                                                        - type: number
                                                          exclusiveMinimum: 0
                                                        - enum:
                                                            - inf
                                                          type: string
                                                      description: >-
                                                        Inclusive upper usage boundary for this
                                                        graduated tier. The final tier must be
                                                        'inf'.
                                                    credit_cost:
                                                      type: number
                                                      minimum: 0
                                                      description: >-
                                                        Credits consumed per billing-unit group
                                                        within this tier.
                                                  required:
                                                    - to
                                                    - credit_cost
                                            required:
                                              - match
                                              - tier_behavior
                                              - tiers
                                            additionalProperties: false
                                          - type: object
                                            properties:
                                              match:
                                                type: object
                                                propertyNames:
                                                  type: string
                                                additionalProperties:
                                                  anyOf:
                                                    - type: string
                                                    - type: number
                                                    - type: boolean
                                                description: >-
                                                  Event properties this entry applies to.
                                                  Every key must equal the tracked
                                                  property, compared as strings.
                                              priority:
                                                type: integer
                                                minimum: -9007199254740991
                                                maximum: 9007199254740991
                                                description: >-
                                                  Breaks ties between dimensions that
                                                  match the same number of keys. Higher
                                                  wins.
                                              credit_cost:
                                                type: number
                                                minimum: 0
                                                description: >-
                                                  Credits consumed per billing-unit group
                                                  when this dimension matches.
                                            required:
                                              - match
                                              - credit_cost
                                            additionalProperties: false
                                      description: >-
                                        Named rates chosen by event properties.
                                        The most specific match sets the rate;
                                        with no match the item's own rate
                                        applies.
                                    multipliers:
                                      type: object
                                      propertyNames:
                                        type: string
                                        minLength: 1
                                        maxLength: 64
                                      additionalProperties:
                                        type: object
                                        properties:
                                          match:
                                            type: object
                                            propertyNames:
                                              type: string
                                            additionalProperties:
                                              anyOf:
                                                - type: string
                                                - type: number
                                                - type: boolean
                                            description: >-
                                              Event properties this entry applies to.
                                              Every key must equal the tracked
                                              property, compared as strings.
                                          factor:
                                            type: number
                                            exclusiveMinimum: 0
                                            description: >-
                                              Multiplies the matched rate. All
                                              matching multipliers stack.
                                          add:
                                            type: number
                                            description: >-
                                              Added to the rate after every factor is
                                              applied, in credits per billing-unit
                                              group.
                                        required:
                                          - match
                                        additionalProperties: false
                                      description: >-
                                        Named adjustments chosen by event
                                        properties. Every match applies: factors
                                        multiply, then adds are summed.
                                    credit_cost:
                                      type: number
                                      minimum: 0
                                      description: Credits consumed per billing-unit group.
                                  required:
                                    - metered_feature_id
                                    - credit_cost
                                  additionalProperties: false
                            description: >-
                              For credit system features: replaces the feature's
                              credit_schema entirely for customers on this plan.
                          markups:
                            type: object
                            properties:
                              default_markup:
                                type: number
                                minimum: -100
                                description: >-
                                  Default percentage markup for customers on
                                  this plan. Use -100 to make usage free.
                              provider_markups:
                                anyOf:
                                  - type: object
                                    propertyNames:
                                      type: string
                                    additionalProperties:
                                      type: object
                                      properties:
                                        markup:
                                          type: number
                                          minimum: -100
                                      required:
                                        - markup
                                  - type: 'null'
                                description: >-
                                  Per-provider markup percentages for customers
                                  on this plan.
                              model_markups:
                                anyOf:
                                  - type: object
                                    propertyNames:
                                      type: string
                                      pattern: .+\/.+
                                    additionalProperties:
                                      type: object
                                      properties:
                                        markup:
                                          type: number
                                          minimum: -100
                                        input_cost:
                                          type: number
                                          minimum: 0
                                        output_cost:
                                          type: number
                                          minimum: 0
                                  - type: 'null'
                                description: >-
                                  Per-model markup overrides for customers on
                                  this plan.
                            additionalProperties: false
                            description: >-
                              For AI credit system features: replaces the
                              feature's markup chain entirely for customers on
                              this plan. An unset level means no markup at that
                              level rather than inheriting the feature's.
                        additionalProperties: false
                        description: >-
                          Overrides fields of this item's feature for customers
                          on this plan (e.g. a credit system's credit_schema).
                    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
                      version_slug:
                        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, in major
                                          currency units (e.g. dollars).
                                      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
                                      maximum: 10000000000000
                                      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.
                                    pooled:
                                      type: boolean
                                      default: false
                                      description: >-
                                        Whether entity-level grants contribute
                                        to a shared customer balance.
                                    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.
                                    feature_override:
                                      type: object
                                      properties:
                                        credit_schema:
                                          type: array
                                          items:
                                            anyOf:
                                              - type: object
                                                properties:
                                                  metered_feature_id:
                                                    type: string
                                                    minLength: 1
                                                    description: >-
                                                      ID of the metered feature that draws
                                                      from this credit system.
                                                  billing_units:
                                                    type: number
                                                    exclusiveMinimum: 0
                                                    description: >-
                                                      Number of metered-feature units priced
                                                      together. Defaults to one when omitted.
                                                  dimensions:
                                                    type: object
                                                    propertyNames:
                                                      type: string
                                                      minLength: 1
                                                      maxLength: 64
                                                    additionalProperties:
                                                      anyOf:
                                                        - type: object
                                                          properties:
                                                            match:
                                                              type: object
                                                              propertyNames:
                                                                type: string
                                                              additionalProperties:
                                                                anyOf:
                                                                  - type: string
                                                                  - type: number
                                                                  - type: boolean
                                                              description: >-
                                                                Event properties this entry applies to.
                                                                Every key must equal the tracked
                                                                property, compared as strings.
                                                            priority:
                                                              type: integer
                                                              minimum: -9007199254740991
                                                              maximum: 9007199254740991
                                                              description: >-
                                                                Breaks ties between dimensions that
                                                                match the same number of keys. Higher
                                                                wins.
                                                            tier_behavior:
                                                              const: graduated
                                                            tiers:
                                                              type: array
                                                              minItems: 1
                                                              items:
                                                                type: object
                                                                properties:
                                                                  to:
                                                                    anyOf:
                                                                      - {}
                                                                      - {}
                                                                    description: >-
                                                                      Inclusive upper usage boundary for this
                                                                      graduated tier. The final tier must be
                                                                      'inf'.
                                                                  credit_cost:
                                                                    type: number
                                                                    minimum: 0
                                                                    description: >-
                                                                      Credits consumed per billing-unit group
                                                                      within this tier.
                                                                required:
                                                                  - to
                                                                  - credit_cost
                                                          required:
                                                            - match
                                                            - tier_behavior
                                                            - tiers
                                                          additionalProperties: false
                                                        - type: object
                                                          properties:
                                                            match:
                                                              type: object
                                                              propertyNames:
                                                                type: string
                                                              additionalProperties:
                                                                anyOf:
                                                                  - type: string
                                                                  - type: number
                                                                  - type: boolean
                                                              description: >-
                                                                Event properties this entry applies to.
                                                                Every key must equal the tracked
                                                                property, compared as strings.
                                                            priority:
                                                              type: integer
                                                              minimum: -9007199254740991
                                                              maximum: 9007199254740991
                                                              description: >-
                                                                Breaks ties between dimensions that
                                                                match the same number of keys. Higher
                                                                wins.
                                                            credit_cost:
                                                              type: number
                                                              minimum: 0
                                                              description: >-
                                                                Credits consumed per billing-unit group
                                                                when this dimension matches.
                                                          required:
                                                            - match
                                                            - credit_cost
                                                          additionalProperties: false
                                                    description: >-
                                                      Named rates chosen by event properties.
                                                      The most specific match sets the rate;
                                                      with no match the item's own rate
                                                      applies.
                                                  multipliers:
                                                    type: object
                                                    propertyNames:
                                                      type: string
                                                      minLength: 1
                                                      maxLength: 64
                                                    additionalProperties:
                                                      type: object
                                                      properties:
                                                        match:
                                                          type: object
                                                          propertyNames:
                                                            type: string
                                                          additionalProperties:
                                                            anyOf:
                                                              - type: string
                                                              - type: number
                                                              - type: boolean
                                                          description: >-
                                                            Event properties this entry applies to.
                                                            Every key must equal the tracked
                                                            property, compared as strings.
                                                        factor:
                                                          type: number
                                                          exclusiveMinimum: 0
                                                          description: >-
                                                            Multiplies the matched rate. All
                                                            matching multipliers stack.
                                                        add:
                                                          type: number
                                                          description: >-
                                                            Added to the rate after every factor is
                                                            applied, in credits per billing-unit
                                                            group.
                                                      required:
                                                        - match
                                                      additionalProperties: false
                                                    description: >-
                                                      Named adjustments chosen by event
                                                      properties. Every match applies: factors
                                                      multiply, then adds are summed.
                                                  tier_behavior:
                                                    const: graduated
                                                  tiers:
                                                    type: array
                                                    minItems: 1
                                                    items:
                                                      type: object
                                                      properties:
                                                        to:
                                                          anyOf:
                                                            - type: number
                                                              exclusiveMinimum: 0
                                                            - enum:
                                                                - inf
                                                              type: string
                                                          description: >-
                                                            Inclusive upper usage boundary for this
                                                            graduated tier. The final tier must be
                                                            'inf'.
                                                        credit_cost:
                                                          type: number
                                                          minimum: 0
                                                          description: >-
                                                            Credits consumed per billing-unit group
                                                            within this tier.
                                                      required:
                                                        - to
                                                        - credit_cost
                                                required:
                                                  - metered_feature_id
                                                  - tier_behavior
                                                  - tiers
                                                additionalProperties: false
                                              - type: object
                                                properties:
                                                  metered_feature_id:
                                                    type: string
                                                    minLength: 1
                                                    description: >-
                                                      ID of the metered feature that draws
                                                      from this credit system.
                                                  billing_units:
                                                    type: number
                                                    exclusiveMinimum: 0
                                                    description: >-
                                                      Number of metered-feature units priced
                                                      together. Defaults to one when omitted.
                                                  dimensions:
                                                    type: object
                                                    propertyNames:
                                                      type: string
                                                      minLength: 1
                                                      maxLength: 64
                                                    additionalProperties:
                                                      anyOf:
                                                        - type: object
                                                          properties:
                                                            match:
                                                              type: object
                                                              propertyNames:
                                                                type: string
                                                              additionalProperties:
                                                                anyOf:
                                                                  - type: string
                                                                  - type: number
                                                                  - type: boolean
                                                              description: >-
                                                                Event properties this entry applies to.
                                                                Every key must equal the tracked
                                                                property, compared as strings.
                                                            priority:
                                                              type: integer
                                                              minimum: -9007199254740991
                                                              maximum: 9007199254740991
                                                              description: >-
                                                                Breaks ties between dimensions that
                                                                match the same number of keys. Higher
                                                                wins.
                                                            tier_behavior:
                                                              const: graduated
                                                            tiers:
                                                              type: array
                                                              minItems: 1
                                                              items:
                                                                type: object
                                                                properties:
                                                                  to:
                                                                    anyOf:
                                                                      - {}
                                                                      - {}
                                                                    description: >-
                                                                      Inclusive upper usage boundary for this
                                                                      graduated tier. The final tier must be
                                                                      'inf'.
                                                                  credit_cost:
                                                                    type: number
                                                                    minimum: 0
                                                                    description: >-
                                                                      Credits consumed per billing-unit group
                                                                      within this tier.
                                                                required:
                                                                  - to
                                                                  - credit_cost
                                                          required:
                                                            - match
                                                            - tier_behavior
                                                            - tiers
                                                          additionalProperties: false
                                                        - type: object
                                                          properties:
                                                            match:
                                                              type: object
                                                              propertyNames:
                                                                type: string
                                                              additionalProperties:
                                                                anyOf:
                                                                  - type: string
                                                                  - type: number
                                                                  - type: boolean
                                                              description: >-
                                                                Event properties this entry applies to.
                                                                Every key must equal the tracked
                                                                property, compared as strings.
                                                            priority:
                                                              type: integer
                                                              minimum: -9007199254740991
                                                              maximum: 9007199254740991
                                                              description: >-
                                                                Breaks ties between dimensions that
                                                                match the same number of keys. Higher
                                                                wins.
                                                            credit_cost:
                                                              type: number
                                                              minimum: 0
                                                              description: >-
                                                                Credits consumed per billing-unit group
                                                                when this dimension matches.
                                                          required:
                                                            - match
                                                            - credit_cost
                                                          additionalProperties: false
                                                    description: >-
                                                      Named rates chosen by event properties.
                                                      The most specific match sets the rate;
                                                      with no match the item's own rate
                                                      applies.
                                                  multipliers:
                                                    type: object
                                                    propertyNames:
                                                      type: string
                                                      minLength: 1
                                                      maxLength: 64
                                                    additionalProperties:
                                                      type: object
                                                      properties:
                                                        match:
                                                          type: object
                                                          propertyNames:
                                                            type: string
                                                          additionalProperties:
                                                            anyOf:
                                                              - type: string
                                                              - type: number
                                                              - type: boolean
                                                          description: >-
                                                            Event properties this entry applies to.
                                                            Every key must equal the tracked
                                                            property, compared as strings.
                                                        factor:
                                                          type: number
                                                          exclusiveMinimum: 0
                                                          description: >-
                                                            Multiplies the matched rate. All
                                                            matching multipliers stack.
                                                        add:
                                                          type: number
                                                          description: >-
                                                            Added to the rate after every factor is
                                                            applied, in credits per billing-unit
                                                            group.
                                                      required:
                                                        - match
                                                      additionalProperties: false
                                                    description: >-
                                                      Named adjustments chosen by event
                                                      properties. Every match applies: factors
                                                      multiply, then adds are summed.
                                                  credit_cost:
                                                    type: number
                                                    minimum: 0
                                                    description: Credits consumed per billing-unit group.
                                                required:
                                                  - metered_feature_id
                                                  - credit_cost
                                                additionalProperties: false
                                          description: >-
                                            For credit system features: replaces the
                                            feature's credit_schema entirely for
                                            customers on this plan.
                                        markups:
                                          type: object
                                          properties:
                                            default_markup:
                                              type: number
                                              minimum: -100
                                              description: >-
                                                Default percentage markup for customers
                                                on this plan. Use -100 to make usage
                                                free.
                                            provider_markups:
                                              anyOf:
                                                - type: object
                                                  propertyNames:
                                                    type: string
                                                  additionalProperties:
                                                    type: object
                                                    properties:
                                                      markup:
                                                        type: number
                                                        minimum: -100
                                                    required:
                                                      - markup
                                                - type: 'null'
                                              description: >-
                                                Per-provider markup percentages for
                                                customers on this plan.
                                            model_markups:
                                              anyOf:
                                                - type: object
                                                  propertyNames:
                                                    type: string
                                                    pattern: .+\/.+
                                                  additionalProperties:
                                                    type: object
                                                    properties:
                                                      markup:
                                                        type: number
                                                        minimum: -100
                                                      input_cost:
                                                        type: number
                                                        minimum: 0
                                                      output_cost:
                                                        type: number
                                                        minimum: 0
                                                - type: 'null'
                                              description: >-
                                                Per-model markup overrides for customers
                                                on this plan.
                                          additionalProperties: false
                                          description: >-
                                            For AI credit system features: replaces
                                            the feature's markup chain entirely for
                                            customers on this plan. An unset level
                                            means no markup at that level rather
                                            than inheriting the feature's.
                                      additionalProperties: false
                                      description: >-
                                        Overrides fields of this item's feature
                                        for customers on this plan (e.g. a
                                        credit system's credit_schema).
                                  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.
                                    included:
                                      type: number
                                      maximum: 10000000000000
                                      description: >-
                                        Match items whose grant equals this
                                        included usage. Omitted is a wildcard.
                                  title: PlanItemFilter
                                  description: >-
                                    Filter for matching plan items. All provided
                                    fields must match (AND).
                          - type: 'null'
                      metadata:
                        type: object
                        propertyNames:
                          type: string
                        additionalProperties: {}
                    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: false
                      description: >-
                        If true, a payment method is required to start the trial
                        and the customer is charged when it ends. Defaults to
                        false.
                    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
                            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.
                              count:
                                type: number
                                minimum: 0
                                description: >-
                                  Set the current window's consumed auto top-up
                                  count. Omit to leave runtime state unchanged.
                            required:
                              - interval
                              - limit
                            description: >-
                              Optional rate limit to cap how often auto top-ups
                              occur. Pass count to set the current window's
                              consumed top-ups.
                          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.
                          anchor:
                            enum:
                              - billing_cycle
                              - utc
                            type: string
                            description: >-
                              Window alignment. 'billing_cycle' phases the
                              interval to the customer's renewal time; 'utc'
                              aligns to the UTC calendar.
                          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.
                          basis:
                            enum:
                              - balance
                              - included
                              - recurring
                              - usage_limit
                            type: string
                            default: balance
                            description: >-
                              What 100% means. balance: every grant on the
                              feature. included: the plan allowance only.
                              recurring: grants that reset. usage_limit: the cap
                              of the usage limit with the same feature and
                              filter.
                          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: >-
                              Only valid with basis usage_limit. Points the
                              alert at the usage limit carrying the same filter.
                          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.
                  version_slug:
                    anyOf:
                      - type: string
                      - type: 'null'
                    description: >-
                      User-facing version identity. Defaults to v{n} when the
                      version is minted.
                  active:
                    type: boolean
                    description: >-
                      Whether this is the active version of the plan. At most
                      one version is active.
                  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, in major currency
                              units (e.g. dollars).
                          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.
                          processors:
                            type: object
                            properties:
                              stripe:
                                anyOf:
                                  - type: object
                                    properties:
                                      price_id:
                                        type: string
                                        description: >-
                                          Stripe price ID. For prepaid with
                                          included > 0 this is the V2 price.
                                    required:
                                      - price_id
                                  - type: 'null'
                            description: >-
                              Payment processors this base price is connected
                              to. Omitted when unset.
                        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.
                        pooled:
                          type: boolean
                          default: false
                          description: >-
                            Whether entity-level grants contribute to a shared
                            customer balance.
                        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.
                                processors:
                                  type: object
                                  properties:
                                    stripe:
                                      anyOf:
                                        - type: object
                                          properties:
                                            price_id:
                                              type: string
                                              description: >-
                                                Stripe price ID. For prepaid with
                                                included > 0 this is the V2 price.
                                          required:
                                            - price_id
                                        - type: 'null'
                                  description: >-
                                    Payment processors this item price is
                                    connected to. Omitted when unset.
                              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.
                        feature_override:
                          type: object
                          properties:
                            credit_schema:
                              type: array
                              items:
                                anyOf:
                                  - type: object
                                    properties:
                                      metered_feature_id:
                                        type: string
                                        minLength: 1
                                        description: >-
                                          ID of the metered feature that draws
                                          from this credit system.
                                      billing_units:
                                        type: number
                                        exclusiveMinimum: 0
                                        description: >-
                                          Number of metered-feature units priced
                                          together. Defaults to one when omitted.
                                      dimensions:
                                        type: object
                                        propertyNames:
                                          type: string
                                          minLength: 1
                                          maxLength: 64
                                        additionalProperties:
                                          anyOf:
                                            - type: object
                                              properties:
                                                match:
                                                  type: object
                                                  propertyNames:
                                                    type: string
                                                  additionalProperties:
                                                    type: string
                                                  description: >-
                                                    Event properties this entry applies to.
                                                    Every key must equal the tracked
                                                    property, compared as strings.
                                                priority:
                                                  type: integer
                                                  minimum: -9007199254740991
                                                  maximum: 9007199254740991
                                                  description: >-
                                                    Breaks ties between dimensions that
                                                    match the same number of keys. Higher
                                                    wins.
                                                tier_behavior:
                                                  const: graduated
                                                tiers:
                                                  type: array
                                                  minItems: 1
                                                  items:
                                                    type: object
                                                    properties:
                                                      to:
                                                        anyOf:
                                                          - type: number
                                                            exclusiveMinimum: 0
                                                          - enum:
                                                              - inf
                                                            type: string
                                                        description: >-
                                                          Inclusive upper usage boundary for this
                                                          graduated tier. The final tier must be
                                                          'inf'.
                                                      credit_cost:
                                                        type: number
                                                        minimum: 0
                                                        description: >-
                                                          Credits consumed per billing-unit group
                                                          within this tier.
                                                    required:
                                                      - to
                                                      - credit_cost
                                              required:
                                                - match
                                                - tier_behavior
                                                - tiers
                                              additionalProperties: false
                                            - type: object
                                              properties:
                                                match:
                                                  type: object
                                                  propertyNames:
                                                    type: string
                                                  additionalProperties:
                                                    type: string
                                                  description: >-
                                                    Event properties this entry applies to.
                                                    Every key must equal the tracked
                                                    property, compared as strings.
                                                priority:
                                                  type: integer
                                                  minimum: -9007199254740991
                                                  maximum: 9007199254740991
                                                  description: >-
                                                    Breaks ties between dimensions that
                                                    match the same number of keys. Higher
                                                    wins.
                                                credit_cost:
                                                  type: number
                                                  minimum: 0
                                                  description: >-
                                                    Credits consumed per billing-unit group
                                                    when this dimension matches.
                                              required:
                                                - match
                                                - credit_cost
                                              additionalProperties: false
                                        description: >-
                                          Named rates chosen by event properties.
                                          The most specific match sets the rate;
                                          with no match the item's own rate
                                          applies.
                                      multipliers:
                                        type: object
                                        propertyNames:
                                          type: string
                                          minLength: 1
                                          maxLength: 64
                                        additionalProperties:
                                          type: object
                                          properties:
                                            match:
                                              type: object
                                              propertyNames:
                                                type: string
                                              additionalProperties:
                                                type: string
                                              description: >-
                                                Event properties this entry applies to.
                                                Every key must equal the tracked
                                                property, compared as strings.
                                            factor:
                                              type: number
                                              exclusiveMinimum: 0
                                              description: >-
                                                Multiplies the matched rate. All
                                                matching multipliers stack.
                                            add:
                                              type: number
                                              description: >-
                                                Added to the rate after every factor is
                                                applied, in credits per billing-unit
                                                group.
                                          required:
                                            - match
                                          additionalProperties: false
                                        description: >-
                                          Named adjustments chosen by event
                                          properties. Every match applies: factors
                                          multiply, then adds are summed.
                                      tier_behavior:
                                        const: graduated
                                      tiers:
                                        type: array
                                        minItems: 1
                                        items:
                                          type: object
                                          properties:
                                            to:
                                              anyOf:
                                                - type: number
                                                  exclusiveMinimum: 0
                                                - enum:
                                                    - inf
                                                  type: string
                                              description: >-
                                                Inclusive upper usage boundary for this
                                                graduated tier. The final tier must be
                                                'inf'.
                                            credit_cost:
                                              type: number
                                              minimum: 0
                                              description: >-
                                                Credits consumed per billing-unit group
                                                within this tier.
                                          required:
                                            - to
                                            - credit_cost
                                    required:
                                      - metered_feature_id
                                      - tier_behavior
                                      - tiers
                                    additionalProperties: false
                                  - type: object
                                    properties:
                                      metered_feature_id:
                                        type: string
                                        minLength: 1
                                        description: >-
                                          ID of the metered feature that draws
                                          from this credit system.
                                      billing_units:
                                        type: number
                                        exclusiveMinimum: 0
                                        description: >-
                                          Number of metered-feature units priced
                                          together. Defaults to one when omitted.
                                      dimensions:
                                        type: object
                                        propertyNames:
                                          type: string
                                          minLength: 1
                                          maxLength: 64
                                        additionalProperties:
                                          anyOf:
                                            - type: object
                                              properties:
                                                match:
                                                  type: object
                                                  propertyNames:
                                                    type: string
                                                  additionalProperties:
                                                    type: string
                                                  description: >-
                                                    Event properties this entry applies to.
                                                    Every key must equal the tracked
                                                    property, compared as strings.
                                                priority:
                                                  type: integer
                                                  minimum: -9007199254740991
                                                  maximum: 9007199254740991
                                                  description: >-
                                                    Breaks ties between dimensions that
                                                    match the same number of keys. Higher
                                                    wins.
                                                tier_behavior:
                                                  const: graduated
                                                tiers:
                                                  type: array
                                                  minItems: 1
                                                  items:
                                                    type: object
                                                    properties:
                                                      to:
                                                        anyOf:
                                                          - type: number
                                                            exclusiveMinimum: 0
                                                          - enum:
                                                              - inf
                                                            type: string
                                                        description: >-
                                                          Inclusive upper usage boundary for this
                                                          graduated tier. The final tier must be
                                                          'inf'.
                                                      credit_cost:
                                                        type: number
                                                        minimum: 0
                                                        description: >-
                                                          Credits consumed per billing-unit group
                                                          within this tier.
                                                    required:
                                                      - to
                                                      - credit_cost
                                              required:
                                                - match
                                                - tier_behavior
                                                - tiers
                                              additionalProperties: false
                                            - type: object
                                              properties:
                                                match:
                                                  type: object
                                                  propertyNames:
                                                    type: string
                                                  additionalProperties:
                                                    type: string
                                                  description: >-
                                                    Event properties this entry applies to.
                                                    Every key must equal the tracked
                                                    property, compared as strings.
                                                priority:
                                                  type: integer
                                                  minimum: -9007199254740991
                                                  maximum: 9007199254740991
                                                  description: >-
                                                    Breaks ties between dimensions that
                                                    match the same number of keys. Higher
                                                    wins.
                                                credit_cost:
                                                  type: number
                                                  minimum: 0
                                                  description: >-
                                                    Credits consumed per billing-unit group
                                                    when this dimension matches.
                                              required:
                                                - match
                                                - credit_cost
                                              additionalProperties: false
                                        description: >-
                                          Named rates chosen by event properties.
                                          The most specific match sets the rate;
                                          with no match the item's own rate
                                          applies.
                                      multipliers:
                                        type: object
                                        propertyNames:
                                          type: string
                                          minLength: 1
                                          maxLength: 64
                                        additionalProperties:
                                          type: object
                                          properties:
                                            match:
                                              type: object
                                              propertyNames:
                                                type: string
                                              additionalProperties:
                                                type: string
                                              description: >-
                                                Event properties this entry applies to.
                                                Every key must equal the tracked
                                                property, compared as strings.
                                            factor:
                                              type: number
                                              exclusiveMinimum: 0
                                              description: >-
                                                Multiplies the matched rate. All
                                                matching multipliers stack.
                                            add:
                                              type: number
                                              description: >-
                                                Added to the rate after every factor is
                                                applied, in credits per billing-unit
                                                group.
                                          required:
                                            - match
                                          additionalProperties: false
                                        description: >-
                                          Named adjustments chosen by event
                                          properties. Every match applies: factors
                                          multiply, then adds are summed.
                                      credit_cost:
                                        type: number
                                        minimum: 0
                                        description: Credits consumed per billing-unit group.
                                    required:
                                      - metered_feature_id
                                      - credit_cost
                                    additionalProperties: false
                              description: >-
                                For credit system features: replaces the
                                feature's credit_schema entirely for customers
                                on this plan.
                            markups:
                              type: object
                              properties:
                                default_markup:
                                  type: number
                                  minimum: -100
                                  description: >-
                                    Default percentage markup for customers on
                                    this plan. Use -100 to make usage free.
                                provider_markups:
                                  anyOf:
                                    - type: object
                                      propertyNames:
                                        type: string
                                      additionalProperties:
                                        type: object
                                        properties:
                                          markup:
                                            type: number
                                            minimum: -100
                                        required:
                                          - markup
                                    - type: 'null'
                                  description: >-
                                    Per-provider markup percentages for
                                    customers on this plan.
                                model_markups:
                                  anyOf:
                                    - type: object
                                      propertyNames:
                                        type: string
                                        pattern: .+\/.+
                                      additionalProperties:
                                        type: object
                                        properties:
                                          markup:
                                            type: number
                                            minimum: -100
                                          input_cost:
                                            type: number
                                            minimum: 0
                                          output_cost:
                                            type: number
                                            minimum: 0
                                    - type: 'null'
                                  description: >-
                                    Per-model markup overrides for customers on
                                    this plan.
                              additionalProperties: false
                              description: >-
                                For AI credit system features: replaces the
                                feature's markup chain entirely for customers on
                                this plan. An unset level means no markup at
                                that level rather than inheriting the feature's.
                          additionalProperties: false
                          description: >-
                            Overrides fields of this item's feature for
                            customers on this plan (e.g. a credit system's
                            credit_schema).
                      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.
                  processors:
                    type: object
                    properties:
                      stripe:
                        anyOf:
                          - type: object
                            properties:
                              product_id:
                                type: string
                                description: Stripe product ID this plan is billed under.
                              additional_product_ids:
                                type: array
                                items:
                                  type: string
                                description: Extra Stripe product IDs aliased to this plan.
                            required:
                              - product_id
                          - type: 'null'
                      revenuecat:
                        anyOf:
                          - type: object
                            properties:
                              products:
                                type: array
                                items:
                                  type: object
                                  properties:
                                    product_id:
                                      type: string
                                      description: >-
                                        RevenueCat product ID that grants this
                                        plan when purchased.
                                    feature_quantities:
                                      type: array
                                      items:
                                        type: object
                                        properties:
                                          feature_id:
                                            type: string
                                          quantity:
                                            type: number
                                            minimum: 0
                                        required:
                                          - feature_id
                                      description: >-
                                        Prepaid quantities granted when this
                                        specific RevenueCat product is
                                        purchased, in feature units.
                                  required:
                                    - product_id
                                description: >-
                                  Every RevenueCat product that maps to this
                                  plan. Replaces the current set.
                            required:
                              - products
                          - type: 'null'
                    description: >-
                      Payment processors this plan is connected to. Omitted when
                      unset.
                  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.
                  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
                              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.
                            anchor:
                              enum:
                                - billing_cycle
                                - utc
                              type: string
                              description: >-
                                Window alignment. 'billing_cycle' phases the
                                interval to the customer's renewal time; 'utc'
                                aligns to the UTC calendar.
                            filter:
                              type: object
                              properties:
                                properties:
                                  type: object
                                  propertyNames:
                                    type: string
                                    minLength: 1
                                    maxLength: 64
                                  additionalProperties:
                                    type: string
                              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.
                            basis:
                              enum:
                                - balance
                                - included
                                - recurring
                                - usage_limit
                              type: string
                              default: balance
                              description: >-
                                What 100% means. balance: every grant on the
                                feature. included: the plan allowance only.
                                recurring: grants that reset. usage_limit: the
                                cap of the usage limit with the same feature and
                                filter.
                            filter:
                              type: object
                              properties:
                                properties:
                                  type: object
                                  propertyNames:
                                    type: string
                                    minLength: 1
                                    maxLength: 64
                                  additionalProperties:
                                    type: string
                              required:
                                - properties
                              description: >-
                                Only valid with basis usage_limit. Points the
                                alert at the usage limit carrying the same
                                filter.
                            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
                  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, in major
                                      currency units (e.g. dollars).
                                  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
                                  maximum: 10000000000000
                                  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.
                                pooled:
                                  type: boolean
                                  default: false
                                  description: >-
                                    Whether entity-level grants contribute to a
                                    shared customer balance.
                                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.
                                feature_override:
                                  type: object
                                  properties:
                                    credit_schema:
                                      type: array
                                      items:
                                        anyOf:
                                          - type: object
                                            properties:
                                              metered_feature_id:
                                                type: string
                                                minLength: 1
                                                description: >-
                                                  ID of the metered feature that draws
                                                  from this credit system.
                                              billing_units:
                                                type: number
                                                exclusiveMinimum: 0
                                                description: >-
                                                  Number of metered-feature units priced
                                                  together. Defaults to one when omitted.
                                              dimensions:
                                                type: object
                                                propertyNames:
                                                  type: string
                                                  minLength: 1
                                                  maxLength: 64
                                                additionalProperties:
                                                  anyOf:
                                                    - type: object
                                                      properties:
                                                        match:
                                                          type: object
                                                          propertyNames:
                                                            type: string
                                                          additionalProperties:
                                                            type: string
                                                          description: >-
                                                            Event properties this entry applies to.
                                                            Every key must equal the tracked
                                                            property, compared as strings.
                                                        priority:
                                                          type: integer
                                                          minimum: -9007199254740991
                                                          maximum: 9007199254740991
                                                          description: >-
                                                            Breaks ties between dimensions that
                                                            match the same number of keys. Higher
                                                            wins.
                                                        tier_behavior:
                                                          const: graduated
                                                        tiers:
                                                          type: array
                                                          minItems: 1
                                                          items:
                                                            type: object
                                                            properties:
                                                              to:
                                                                anyOf:
                                                                  - type: number
                                                                    exclusiveMinimum: 0
                                                                  - enum:
                                                                      - inf
                                                                    type: string
                                                                description: >-
                                                                  Inclusive upper usage boundary for this
                                                                  graduated tier. The final tier must be
                                                                  'inf'.
                                                              credit_cost:
                                                                type: number
                                                                minimum: 0
                                                                description: >-
                                                                  Credits consumed per billing-unit group
                                                                  within this tier.
                                                            required:
                                                              - to
                                                              - credit_cost
                                                      required:
                                                        - match
                                                        - tier_behavior
                                                        - tiers
                                                      additionalProperties: false
                                                    - type: object
                                                      properties:
                                                        match:
                                                          type: object
                                                          propertyNames:
                                                            type: string
                                                          additionalProperties:
                                                            type: string
                                                          description: >-
                                                            Event properties this entry applies to.
                                                            Every key must equal the tracked
                                                            property, compared as strings.
                                                        priority:
                                                          type: integer
                                                          minimum: -9007199254740991
                                                          maximum: 9007199254740991
                                                          description: >-
                                                            Breaks ties between dimensions that
                                                            match the same number of keys. Higher
                                                            wins.
                                                        credit_cost:
                                                          type: number
                                                          minimum: 0
                                                          description: >-
                                                            Credits consumed per billing-unit group
                                                            when this dimension matches.
                                                      required:
                                                        - match
                                                        - credit_cost
                                                      additionalProperties: false
                                                description: >-
                                                  Named rates chosen by event properties.
                                                  The most specific match sets the rate;
                                                  with no match the item's own rate
                                                  applies.
                                              multipliers:
                                                type: object
                                                propertyNames:
                                                  type: string
                                                  minLength: 1
                                                  maxLength: 64
                                                additionalProperties:
                                                  type: object
                                                  properties:
                                                    match:
                                                      type: object
                                                      propertyNames:
                                                        type: string
                                                      additionalProperties:
                                                        type: string
                                                      description: >-
                                                        Event properties this entry applies to.
                                                        Every key must equal the tracked
                                                        property, compared as strings.
                                                    factor:
                                                      type: number
                                                      exclusiveMinimum: 0
                                                      description: >-
                                                        Multiplies the matched rate. All
                                                        matching multipliers stack.
                                                    add:
                                                      type: number
                                                      description: >-
                                                        Added to the rate after every factor is
                                                        applied, in credits per billing-unit
                                                        group.
                                                  required:
                                                    - match
                                                  additionalProperties: false
                                                description: >-
                                                  Named adjustments chosen by event
                                                  properties. Every match applies: factors
                                                  multiply, then adds are summed.
                                              tier_behavior:
                                                const: graduated
                                              tiers:
                                                type: array
                                                minItems: 1
                                                items:
                                                  type: object
                                                  properties:
                                                    to:
                                                      anyOf:
                                                        - type: number
                                                          exclusiveMinimum: 0
                                                        - enum:
                                                            - inf
                                                          type: string
                                                      description: >-
                                                        Inclusive upper usage boundary for this
                                                        graduated tier. The final tier must be
                                                        'inf'.
                                                    credit_cost:
                                                      type: number
                                                      minimum: 0
                                                      description: >-
                                                        Credits consumed per billing-unit group
                                                        within this tier.
                                                  required:
                                                    - to
                                                    - credit_cost
                                            required:
                                              - metered_feature_id
                                              - tier_behavior
                                              - tiers
                                            additionalProperties: false
                                          - type: object
                                            properties:
                                              metered_feature_id:
                                                type: string
                                                minLength: 1
                                                description: >-
                                                  ID of the metered feature that draws
                                                  from this credit system.
                                              billing_units:
                                                type: number
                                                exclusiveMinimum: 0
                                                description: >-
                                                  Number of metered-feature units priced
                                                  together. Defaults to one when omitted.
                                              dimensions:
                                                type: object
                                                propertyNames:
                                                  type: string
                                                  minLength: 1
                                                  maxLength: 64
                                                additionalProperties:
                                                  anyOf:
                                                    - type: object
                                                      properties:
                                                        match:
                                                          type: object
                                                          propertyNames:
                                                            type: string
                                                          additionalProperties:
                                                            type: string
                                                          description: >-
                                                            Event properties this entry applies to.
                                                            Every key must equal the tracked
                                                            property, compared as strings.
                                                        priority:
                                                          type: integer
                                                          minimum: -9007199254740991
                                                          maximum: 9007199254740991
                                                          description: >-
                                                            Breaks ties between dimensions that
                                                            match the same number of keys. Higher
                                                            wins.
                                                        tier_behavior:
                                                          const: graduated
                                                        tiers:
                                                          type: array
                                                          minItems: 1
                                                          items:
                                                            type: object
                                                            properties:
                                                              to:
                                                                anyOf:
                                                                  - type: number
                                                                    exclusiveMinimum: 0
                                                                  - enum:
                                                                      - inf
                                                                    type: string
                                                                description: >-
                                                                  Inclusive upper usage boundary for this
                                                                  graduated tier. The final tier must be
                                                                  'inf'.
                                                              credit_cost:
                                                                type: number
                                                                minimum: 0
                                                                description: >-
                                                                  Credits consumed per billing-unit group
                                                                  within this tier.
                                                            required:
                                                              - to
                                                              - credit_cost
                                                      required:
                                                        - match
                                                        - tier_behavior
                                                        - tiers
                                                      additionalProperties: false
                                                    - type: object
                                                      properties:
                                                        match:
                                                          type: object
                                                          propertyNames:
                                                            type: string
                                                          additionalProperties:
                                                            type: string
                                                          description: >-
                                                            Event properties this entry applies to.
                                                            Every key must equal the tracked
                                                            property, compared as strings.
                                                        priority:
                                                          type: integer
                                                          minimum: -9007199254740991
                                                          maximum: 9007199254740991
                                                          description: >-
                                                            Breaks ties between dimensions that
                                                            match the same number of keys. Higher
                                                            wins.
                                                        credit_cost:
                                                          type: number
                                                          minimum: 0
                                                          description: >-
                                                            Credits consumed per billing-unit group
                                                            when this dimension matches.
                                                      required:
                                                        - match
                                                        - credit_cost
                                                      additionalProperties: false
                                                description: >-
                                                  Named rates chosen by event properties.
                                                  The most specific match sets the rate;
                                                  with no match the item's own rate
                                                  applies.
                                              multipliers:
                                                type: object
                                                propertyNames:
                                                  type: string
                                                  minLength: 1
                                                  maxLength: 64
                                                additionalProperties:
                                                  type: object
                                                  properties:
                                                    match:
                                                      type: object
                                                      propertyNames:
                                                        type: string
                                                      additionalProperties:
                                                        type: string
                                                      description: >-
                                                        Event properties this entry applies to.
                                                        Every key must equal the tracked
                                                        property, compared as strings.
                                                    factor:
                                                      type: number
                                                      exclusiveMinimum: 0
                                                      description: >-
                                                        Multiplies the matched rate. All
                                                        matching multipliers stack.
                                                    add:
                                                      type: number
                                                      description: >-
                                                        Added to the rate after every factor is
                                                        applied, in credits per billing-unit
                                                        group.
                                                  required:
                                                    - match
                                                  additionalProperties: false
                                                description: >-
                                                  Named adjustments chosen by event
                                                  properties. Every match applies: factors
                                                  multiply, then adds are summed.
                                              credit_cost:
                                                type: number
                                                minimum: 0
                                                description: Credits consumed per billing-unit group.
                                            required:
                                              - metered_feature_id
                                              - credit_cost
                                            additionalProperties: false
                                      description: >-
                                        For credit system features: replaces the
                                        feature's credit_schema entirely for
                                        customers on this plan.
                                    markups:
                                      type: object
                                      properties:
                                        default_markup:
                                          type: number
                                          minimum: -100
                                          description: >-
                                            Default percentage markup for customers
                                            on this plan. Use -100 to make usage
                                            free.
                                        provider_markups:
                                          anyOf:
                                            - type: object
                                              propertyNames:
                                                type: string
                                              additionalProperties:
                                                type: object
                                                properties:
                                                  markup:
                                                    type: number
                                                    minimum: -100
                                                required:
                                                  - markup
                                            - type: 'null'
                                          description: >-
                                            Per-provider markup percentages for
                                            customers on this plan.
                                        model_markups:
                                          anyOf:
                                            - type: object
                                              propertyNames:
                                                type: string
                                                pattern: .+\/.+
                                              additionalProperties:
                                                type: object
                                                properties:
                                                  markup:
                                                    type: number
                                                    minimum: -100
                                                  input_cost:
                                                    type: number
                                                    minimum: 0
                                                  output_cost:
                                                    type: number
                                                    minimum: 0
                                            - type: 'null'
                                          description: >-
                                            Per-model markup overrides for customers
                                            on this plan.
                                      additionalProperties: false
                                      description: >-
                                        For AI credit system features: replaces
                                        the feature's markup chain entirely for
                                        customers on this plan. An unset level
                                        means no markup at that level rather
                                        than inheriting the feature's.
                                  additionalProperties: false
                                  description: >-
                                    Overrides fields of this item's feature for
                                    customers on this plan (e.g. a credit
                                    system's credit_schema).
                              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.
                                included:
                                  type: number
                                  maximum: 10000000000000
                                  description: >-
                                    Match items whose grant equals this included
                                    usage. Omitted is a wildcard.
                              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: false
                                    description: >-
                                      If true, a payment method is required to
                                      start the trial and the customer is
                                      charged when it ends. Defaults to false.
                                  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
                                      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.
                                        count:
                                          type: number
                                          minimum: 0
                                          description: >-
                                            Set the current window's consumed auto
                                            top-up count. Omit to leave runtime
                                            state unchanged.
                                      required:
                                        - interval
                                        - limit
                                      description: >-
                                        Optional rate limit to cap how often
                                        auto top-ups occur. Pass count to set
                                        the current window's consumed top-ups.
                                    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.
                                    anchor:
                                      enum:
                                        - billing_cycle
                                        - utc
                                      type: string
                                      description: >-
                                        Window alignment. 'billing_cycle' phases
                                        the interval to the customer's renewal
                                        time; 'utc' aligns to the UTC calendar.
                                    filter:
                                      type: object
                                      properties:
                                        properties:
                                          type: object
                                          propertyNames:
                                            type: string
                                            minLength: 1
                                            maxLength: 64
                                          additionalProperties:
                                            type: string
                                      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.
                                    basis:
                                      enum:
                                        - balance
                                        - included
                                        - recurring
                                        - usage_limit
                                      type: string
                                      default: balance
                                      description: >-
                                        What 100% means. balance: every grant on
                                        the feature. included: the plan
                                        allowance only. recurring: grants that
                                        reset. usage_limit: the cap of the usage
                                        limit with the same feature and filter.
                                    filter:
                                      type: object
                                      properties:
                                        properties:
                                          type: object
                                          propertyNames:
                                            type: string
                                            minLength: 1
                                            maxLength: 64
                                          additionalProperties:
                                            type: string
                                      required:
                                        - properties
                                      description: >-
                                        Only valid with basis usage_limit.
                                        Points the alert at the usage limit
                                        carrying the same filter.
                                    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.
                          upsert_licenses:
                            type: array
                            items:
                              type: object
                              properties:
                                license_plan_id:
                                  type: string
                                version_slug:
                                  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, in major
                                                    currency units (e.g. dollars).
                                                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
                                                maximum: 10000000000000
                                                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.
                                              pooled:
                                                type: boolean
                                                default: false
                                                description: >-
                                                  Whether entity-level grants contribute
                                                  to a shared customer balance.
                                              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.
                                              feature_override:
                                                type: object
                                                properties:
                                                  credit_schema:
                                                    type: array
                                                    items:
                                                      anyOf:
                                                        - type: object
                                                          properties:
                                                            metered_feature_id:
                                                              type: string
                                                              minLength: 1
                                                              description: >-
                                                                ID of the metered feature that draws
                                                                from this credit system.
                                                            billing_units:
                                                              type: number
                                                              exclusiveMinimum: 0
                                                              description: >-
                                                                Number of metered-feature units priced
                                                                together. Defaults to one when omitted.
                                                            dimensions:
                                                              type: object
                                                              propertyNames:
                                                                type: string
                                                                minLength: 1
                                                                maxLength: 64
                                                              additionalProperties:
                                                                anyOf:
                                                                  - type: object
                                                                    properties:
                                                                      match: {}
                                                                      priority: {}
                                                                      tier_behavior: {}
                                                                      tiers: {}
                                                                    required:
                                                                      - match
                                                                      - tier_behavior
                                                                      - tiers
                                                                    additionalProperties: false
                                                                  - type: object
                                                                    properties:
                                                                      match: {}
                                                                      priority: {}
                                                                      credit_cost: {}
                                                                    required:
                                                                      - match
                                                                      - credit_cost
                                                                    additionalProperties: false
                                                              description: >-
                                                                Named rates chosen by event properties.
                                                                The most specific match sets the rate;
                                                                with no match the item's own rate
                                                                applies.
                                                            multipliers:
                                                              type: object
                                                              propertyNames:
                                                                type: string
                                                                minLength: 1
                                                                maxLength: 64
                                                              additionalProperties:
                                                                type: object
                                                                properties:
                                                                  match:
                                                                    type: object
                                                                    propertyNames:
                                                                      type: string
                                                                    additionalProperties:
                                                                      type: {}
                                                                    description: >-
                                                                      Event properties this entry applies to.
                                                                      Every key must equal the tracked
                                                                      property, compared as strings.
                                                                  factor:
                                                                    type: number
                                                                    exclusiveMinimum: 0
                                                                    description: >-
                                                                      Multiplies the matched rate. All
                                                                      matching multipliers stack.
                                                                  add:
                                                                    type: number
                                                                    description: >-
                                                                      Added to the rate after every factor is
                                                                      applied, in credits per billing-unit
                                                                      group.
                                                                required:
                                                                  - match
                                                                additionalProperties: false
                                                              description: >-
                                                                Named adjustments chosen by event
                                                                properties. Every match applies: factors
                                                                multiply, then adds are summed.
                                                            tier_behavior:
                                                              const: graduated
                                                            tiers:
                                                              type: array
                                                              minItems: 1
                                                              items:
                                                                type: object
                                                                properties:
                                                                  to:
                                                                    anyOf:
                                                                      - {}
                                                                      - {}
                                                                    description: >-
                                                                      Inclusive upper usage boundary for this
                                                                      graduated tier. The final tier must be
                                                                      'inf'.
                                                                  credit_cost:
                                                                    type: number
                                                                    minimum: 0
                                                                    description: >-
                                                                      Credits consumed per billing-unit group
                                                                      within this tier.
                                                                required:
                                                                  - to
                                                                  - credit_cost
                                                          required:
                                                            - metered_feature_id
                                                            - tier_behavior
                                                            - tiers
                                                          additionalProperties: false
                                                        - type: object
                                                          properties:
                                                            metered_feature_id:
                                                              type: string
                                                              minLength: 1
                                                              description: >-
                                                                ID of the metered feature that draws
                                                                from this credit system.
                                                            billing_units:
                                                              type: number
                                                              exclusiveMinimum: 0
                                                              description: >-
                                                                Number of metered-feature units priced
                                                                together. Defaults to one when omitted.
                                                            dimensions:
                                                              type: object
                                                              propertyNames:
                                                                type: string
                                                                minLength: 1
                                                                maxLength: 64
                                                              additionalProperties:
                                                                anyOf:
                                                                  - type: object
                                                                    properties:
                                                                      match: {}
                                                                      priority: {}
                                                                      tier_behavior: {}
                                                                      tiers: {}
                                                                    required:
                                                                      - match
                                                                      - tier_behavior
                                                                      - tiers
                                                                    additionalProperties: false
                                                                  - type: object
                                                                    properties:
                                                                      match: {}
                                                                      priority: {}
                                                                      credit_cost: {}
                                                                    required:
                                                                      - match
                                                                      - credit_cost
                                                                    additionalProperties: false
                                                              description: >-
                                                                Named rates chosen by event properties.
                                                                The most specific match sets the rate;
                                                                with no match the item's own rate
                                                                applies.
                                                            multipliers:
                                                              type: object
                                                              propertyNames:
                                                                type: string
                                                                minLength: 1
                                                                maxLength: 64
                                                              additionalProperties:
                                                                type: object
                                                                properties:
                                                                  match:
                                                                    type: object
                                                                    propertyNames:
                                                                      type: string
                                                                    additionalProperties:
                                                                      type: {}
                                                                    description: >-
                                                                      Event properties this entry applies to.
                                                                      Every key must equal the tracked
                                                                      property, compared as strings.
                                                                  factor:
                                                                    type: number
                                                                    exclusiveMinimum: 0
                                                                    description: >-
                                                                      Multiplies the matched rate. All
                                                                      matching multipliers stack.
                                                                  add:
                                                                    type: number
                                                                    description: >-
                                                                      Added to the rate after every factor is
                                                                      applied, in credits per billing-unit
                                                                      group.
                                                                required:
                                                                  - match
                                                                additionalProperties: false
                                                              description: >-
                                                                Named adjustments chosen by event
                                                                properties. Every match applies: factors
                                                                multiply, then adds are summed.
                                                            credit_cost:
                                                              type: number
                                                              minimum: 0
                                                              description: Credits consumed per billing-unit group.
                                                          required:
                                                            - metered_feature_id
                                                            - credit_cost
                                                          additionalProperties: false
                                                    description: >-
                                                      For credit system features: replaces the
                                                      feature's credit_schema entirely for
                                                      customers on this plan.
                                                  markups:
                                                    type: object
                                                    properties:
                                                      default_markup:
                                                        type: number
                                                        minimum: -100
                                                        description: >-
                                                          Default percentage markup for customers
                                                          on this plan. Use -100 to make usage
                                                          free.
                                                      provider_markups:
                                                        anyOf:
                                                          - type: object
                                                            propertyNames:
                                                              type: string
                                                            additionalProperties:
                                                              type: object
                                                              properties:
                                                                markup:
                                                                  type: number
                                                                  minimum: -100
                                                              required:
                                                                - markup
                                                          - type: 'null'
                                                        description: >-
                                                          Per-provider markup percentages for
                                                          customers on this plan.
                                                      model_markups:
                                                        anyOf:
                                                          - type: object
                                                            propertyNames:
                                                              type: string
                                                              pattern: .+\/.+
                                                            additionalProperties:
                                                              type: object
                                                              properties:
                                                                markup:
                                                                  type: number
                                                                  minimum: -100
                                                                input_cost:
                                                                  type: number
                                                                  minimum: 0
                                                                output_cost:
                                                                  type: number
                                                                  minimum: 0
                                                          - type: 'null'
                                                        description: >-
                                                          Per-model markup overrides for customers
                                                          on this plan.
                                                    additionalProperties: false
                                                    description: >-
                                                      For AI credit system features: replaces
                                                      the feature's markup chain entirely for
                                                      customers on this plan. An unset level
                                                      means no markup at that level rather
                                                      than inheriting the feature's.
                                                additionalProperties: false
                                                description: >-
                                                  Overrides fields of this item's feature
                                                  for customers on this plan (e.g. a
                                                  credit system's credit_schema).
                                            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.
                                              included:
                                                type: number
                                                maximum: 10000000000000
                                                description: >-
                                                  Match items whose grant equals this
                                                  included usage. Omitted is a wildcard.
                                            title: PlanItemFilter
                                            description: >-
                                              Filter for matching plan items. All
                                              provided fields must match (AND).
                                    - type: 'null'
                                metadata:
                                  type: object
                                  propertyNames:
                                    type: string
                                  additionalProperties: {}
                              required:
                                - license_plan_id
                            description: >-
                              License links to add or override for this
                              customer, keyed by license_plan_id. Omitted fields
                              inherit the plan catalog link (included defaults
                              to 1 when the license is not in the catalog). A
                              bare entry restores the license to pure catalog
                              inheritance.
                          remove_licenses:
                            type: array
                            items:
                              type: object
                              properties:
                                license_plan_id:
                                  type: string
                              required:
                                - license_plan_id
                            description: >-
                              License links to drop, keyed by license_plan_id.
                              Parallel to remove_items.
                        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.
                required:
                  - id
                  - name
                  - description
                  - group
                  - version
                  - add_on
                  - auto_enable
                  - price
                  - items
                  - created_at
                  - env
                  - archived
                  - config
                  - metadata
                  - base_variant_id
                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
                    version_slug: v1
                    active: true
                    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
                version_slug: v1
                active: true
                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

````