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

# Plans Updated

> Fired when a customer's plans change — activated, scheduled, updated, or expired. Each event carries a `plan_changes` array describing what happened and a `tags` array (e.g. `trial_ended`, `phase_changed`) describing why.

### Payload Fields

<ParamField body="object" type="string" required />

<ParamField body="customer_id" type="string" required>
  The ID of the customer whose plans changed.
</ParamField>

<ParamField body="entity_id" type="string | null">
  The ID of the entity, if the changes are scoped to a specific entity.
</ParamField>

<ParamField body="plan_changes" type="object[]" required>
  The plans that were activated, scheduled, updated, or expired.

  <Expandable title="properties">
    <ParamField body="action" type="'activated' | 'scheduled' | 'updated' | 'expired'" required>
      The lifecycle action applied to this plan: activated (newly active on the customer), scheduled (queued for a future start), updated (mutated in place), or expired (ended).
    </ParamField>

    <ParamField body="subscription" type="object">
      The subscription as it stands after this change. Present when the plan is billed as a recurring subscription.

      <Expandable title="properties">
        <ParamField body="plan_id" type="string" required>
          The ID of the customer plan.
        </ParamField>

        <ParamField body="status" type="'active' | 'scheduled' | 'expired'" required>
          The current status of the subscription on the customer.
        </ParamField>

        <ParamField body="past_due" type="boolean" required>
          Whether the subscription has overdue payments.
        </ParamField>

        <ParamField body="started_at" type="number | null" required>
          When the subscription started, in milliseconds since the Unix epoch.
        </ParamField>

        <ParamField body="canceled_at" type="number | null" required>
          When the subscription was canceled, in milliseconds since the Unix epoch, or null if not canceled.
        </ParamField>

        <ParamField body="expires_at" type="number | null" required>
          When the subscription ends, in milliseconds since the Unix epoch, or null if no expiry is set.
        </ParamField>

        <ParamField body="trial_ends_at" type="number | null" required>
          When the trial ends, in milliseconds since the Unix epoch. Null when not actively trialing.
        </ParamField>

        <ParamField body="current_period_start" type="number | null" required>
          Start of the current billing period, or null if not applicable.
        </ParamField>

        <ParamField body="current_period_end" type="number | null" required>
          End of the current billing period, or null if not applicable.
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="purchase" type="object">
      The purchase as it stands after this change. Present when the plan is a one-off purchase.

      <Expandable title="properties">
        <ParamField body="plan_id" type="string" required>
          The ID of the customer plan.
        </ParamField>

        <ParamField body="status" type="'active' | 'scheduled' | 'expired'" required>
          The current status of the purchase on the customer.
        </ParamField>

        <ParamField body="expires_at" type="number | null" required>
          When the purchase ends, in milliseconds since the Unix epoch, or null if no expiry is set.
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="previous_attributes" type="object | null" required>
      Sparse map of scalar fields whose values changed, holding their previous values. Null when the plan is newly activated or scheduled.
    </ParamField>

    <ParamField body="item_changes" type="object[]" required>
      Features that were added to or removed from this plan. Only populated for updated plans.

      <Expandable title="properties">
        <ParamField body="action" type="'created' | 'deleted'" required>
          Whether the feature was added to or removed from the plan.
        </ParamField>

        <ParamField body="feature_id" type="string" required>
          The ID of the feature that was added or removed.
        </ParamField>

        <ParamField body="item" type="object" required>
          The item snapshot that was added or removed.

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

            <ParamField body="feature" type="object">
              The full feature object if expanded.

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

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

                <ParamField body="type" type="'static' | 'boolean' | 'single_use' | 'continuous_use' | 'credit_system' | 'ai_credit_system'" required>
                  The type of the feature
                </ParamField>

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

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

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

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

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

                    <ParamField body="credit_cost" type="number" required>
                      The credit cost of the metered feature.
                    </ParamField>
                  </Expandable>
                </ParamField>

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

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

            <ParamField body="unlimited" type="boolean" required>
              Whether the customer has unlimited access to this feature.
            </ParamField>

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

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

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

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

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

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

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

                    <ParamField body="amount" type="number" required />

                    <ParamField body="flat_amount" type="number" />
                  </Expandable>
                </ParamField>

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

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

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

                <ParamField body="billing_units" type="number" required>
                  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).
                </ParamField>

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

                <ParamField body="max_purchase" type="number | null" required>
                  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.
                </ParamField>
              </Expandable>
            </ParamField>

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

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

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

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

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

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

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

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

<ParamField body="tags" type="string[]" required>
  Reason tags describing why this event fired (e.g. 'trial\_ended', 'phase\_changed'). Always present; empty when no specific reason applies.
</ParamField>


## OpenAPI

````yaml api/openapi.yml webhook billing.updated
openapi: 3.1.0
info:
  title: Autumn API
  version: 2.3.0
servers:
  - url: https://api.useautumn.com
    description: Production server
security:
  - secretKey: []
paths: {}
components:
  securitySchemes:
    secretKey:
      type: http
      scheme: bearer
      bearerFormat: JWT

````