271 lines
12 KiB
Plaintext
271 lines
12 KiB
Plaintext
---
|
|
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>
|