---
title: "Plans Updated"
openapi: "api/openapi.yml webhook billing.updated"
---

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