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

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