1365 lines
58 KiB
Plaintext
1365 lines
58 KiB
Plaintext
---
|
|
title: "Preview Multi Attach"
|
|
openapi: "openapi POST /v1/billing.preview_multi_attach"
|
|
---
|
|
|
|
import { DynamicParamField } from "/components/dynamic-param-field.jsx";
|
|
import { DynamicResponseField } from "/components/dynamic-response-field.jsx";
|
|
import { DynamicResponseExample } from "/components/dynamic-response-example.jsx";
|
|
|
|
### Body Parameters
|
|
|
|
<DynamicParamField body="customer_id" type="string" required>
|
|
The ID of the customer to attach the plans to.
|
|
</DynamicParamField>
|
|
|
|
<DynamicParamField body="entity_id" type="string">
|
|
The ID of the entity to attach the plans to.
|
|
</DynamicParamField>
|
|
|
|
<DynamicParamField body="plans" type="object[]" required>
|
|
The list of plans to attach to the customer.
|
|
<Expandable title="properties">
|
|
<DynamicParamField body="plan_id" type="string" required>
|
|
The ID of the plan to attach.
|
|
</DynamicParamField>
|
|
|
|
<DynamicParamField body="customize" type="object">
|
|
Customize the plan to attach. Can override the price or items.
|
|
<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.
|
|
</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>
|
|
|
|
</Expandable>
|
|
</DynamicParamField>
|
|
|
|
<DynamicParamField body="items" type="object[]">
|
|
Override the items in the plan.
|
|
<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="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="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" />
|
|
|
|
</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">
|
|
Max units purchasable beyond included. E.g. included=100, max_purchase=300 allows 400 total.
|
|
</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>
|
|
|
|
</Expandable>
|
|
</DynamicParamField>
|
|
|
|
</Expandable>
|
|
</DynamicParamField>
|
|
|
|
<DynamicParamField body="feature_quantities" type="object[]">
|
|
If this plan contains prepaid features, use this field to specify the quantity of each prepaid feature.
|
|
<Expandable title="properties">
|
|
<DynamicParamField body="feature_id" type="string" required>
|
|
The ID of the feature to set quantity for.
|
|
</DynamicParamField>
|
|
|
|
<DynamicParamField body="quantity" type="number">
|
|
The quantity of the feature.
|
|
</DynamicParamField>
|
|
|
|
<DynamicParamField body="adjustable" type="boolean">
|
|
Whether the customer can adjust the quantity.
|
|
</DynamicParamField>
|
|
|
|
</Expandable>
|
|
</DynamicParamField>
|
|
|
|
<DynamicParamField body="version" type="number">
|
|
The version of the plan to attach.
|
|
</DynamicParamField>
|
|
|
|
<DynamicParamField body="subscription_id" type="string">
|
|
A unique ID to identify this subscription. Useful when attaching the same plan multiple times.
|
|
</DynamicParamField>
|
|
|
|
</Expandable>
|
|
</DynamicParamField>
|
|
|
|
<DynamicParamField body="free_trial" type="object | null">
|
|
Free trial configuration for a plan.
|
|
<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, payment method required to start trial. Customer is charged after trial ends.
|
|
</DynamicParamField>
|
|
|
|
</Expandable>
|
|
</DynamicParamField>
|
|
|
|
<DynamicParamField body="invoice_mode" type="object">
|
|
Invoice mode creates a draft or open invoice and sends it to the customer, instead of charging their card immediately.
|
|
<Expandable title="properties">
|
|
<DynamicParamField body="enabled" type="boolean" required>
|
|
When true, creates an invoice and sends it to the customer instead of charging their card immediately. Uses Stripe's send_invoice collection method.
|
|
</DynamicParamField>
|
|
|
|
<DynamicParamField body="enable_plan_immediately" type="boolean">
|
|
If true, enables the plan immediately even though the invoice is not paid yet.
|
|
</DynamicParamField>
|
|
|
|
<DynamicParamField body="finalize" type="boolean">
|
|
If true, finalizes the invoice so it can be sent to the customer. If false, keeps it as a draft for manual review.
|
|
</DynamicParamField>
|
|
|
|
</Expandable>
|
|
</DynamicParamField>
|
|
|
|
<DynamicParamField body="discounts" type="object[]">
|
|
List of discounts to apply. Each discount can be an Autumn reward ID, Stripe coupon ID, or Stripe promotion code.
|
|
<Expandable title="properties">
|
|
<DynamicParamField body="reward_id" type="string">
|
|
The ID of the reward to apply as a discount.
|
|
</DynamicParamField>
|
|
|
|
<DynamicParamField body="promotion_code" type="string">
|
|
The promotion code to apply as a discount.
|
|
</DynamicParamField>
|
|
|
|
</Expandable>
|
|
</DynamicParamField>
|
|
|
|
<DynamicParamField body="success_url" type="string">
|
|
URL to redirect to after successful checkout.
|
|
</DynamicParamField>
|
|
|
|
<DynamicParamField body="checkout_session_params" type="object">
|
|
Additional parameters to pass into the creation of the Stripe checkout session.
|
|
</DynamicParamField>
|
|
|
|
<DynamicParamField body="redirect_mode" type="'always' | 'if_required' | 'never'">
|
|
Controls when to return a checkout URL. 'always' returns a URL even if payment succeeds, 'if_required' only when payment action is needed, 'never' disables redirects.
|
|
</DynamicParamField>
|
|
|
|
<DynamicParamField body="new_billing_subscription" type="boolean">
|
|
Only applicable when the customer has an existing Stripe subscription. If true, creates a new separate subscription instead of merging into the existing one.
|
|
</DynamicParamField>
|
|
|
|
<DynamicParamField body="customer_data" type="object">
|
|
Customer details to set when creating a customer
|
|
<Expandable title="properties">
|
|
<DynamicParamField body="name" type="string | null">
|
|
Customer's name
|
|
</DynamicParamField>
|
|
|
|
<DynamicParamField body="email" type="string | null">
|
|
Customer's email address
|
|
</DynamicParamField>
|
|
|
|
<DynamicParamField body="fingerprint" type="string | null">
|
|
Unique identifier (eg, serial number) to detect duplicate customers and prevent free trial abuse
|
|
</DynamicParamField>
|
|
|
|
<DynamicParamField body="metadata" type="object | null">
|
|
Additional metadata for the customer
|
|
</DynamicParamField>
|
|
|
|
<DynamicParamField body="stripe_id" type="string | null">
|
|
Stripe customer ID if you already have one
|
|
</DynamicParamField>
|
|
|
|
<DynamicParamField body="create_in_stripe" type="boolean">
|
|
Whether to create the customer in Stripe
|
|
</DynamicParamField>
|
|
|
|
<DynamicParamField body="auto_enable_plan_id" type="string">
|
|
The ID of the free plan to auto-enable for the customer
|
|
</DynamicParamField>
|
|
|
|
<DynamicParamField body="send_email_receipts" type="boolean">
|
|
Whether to send email receipts to this customer
|
|
</DynamicParamField>
|
|
|
|
<DynamicParamField body="billing_controls" type="object">
|
|
Billing controls for the customer (auto top-ups, etc.)
|
|
<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.
|
|
<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>
|
|
|
|
</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.
|
|
<Expandable title="properties">
|
|
<DynamicParamField body="feature_id" type="string">
|
|
Optional feature ID this spend limit applies to.
|
|
</DynamicParamField>
|
|
|
|
<DynamicParamField body="enabled" type="boolean">
|
|
Whether this spend limit is enabled.
|
|
</DynamicParamField>
|
|
|
|
<DynamicParamField body="overage_limit" type="number">
|
|
Maximum allowed overage spend for the target feature.
|
|
</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="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="config" type="object">
|
|
Miscellaneous configurations for the customer.
|
|
<Expandable title="properties">
|
|
<DynamicParamField body="disable_pooled_balance" type="boolean">
|
|
Whether to disable the shared customer-level pool for entities.
|
|
</DynamicParamField>
|
|
|
|
</Expandable>
|
|
</DynamicParamField>
|
|
|
|
</Expandable>
|
|
</DynamicParamField>
|
|
|
|
<DynamicParamField body="entity_data" type="object">
|
|
<Expandable title="properties">
|
|
<DynamicParamField body="feature_id" type="string" required>
|
|
The feature ID that this entity is associated with
|
|
</DynamicParamField>
|
|
|
|
<DynamicParamField body="name" type="string">
|
|
Name of the entity
|
|
</DynamicParamField>
|
|
|
|
<DynamicParamField body="billing_controls" type="object">
|
|
Billing controls for the entity.
|
|
<Expandable title="properties">
|
|
<DynamicParamField body="spend_limits" type="object[]">
|
|
List of overage spend limits per feature.
|
|
<Expandable title="properties">
|
|
<DynamicParamField body="feature_id" type="string">
|
|
Optional feature ID this spend limit applies to.
|
|
</DynamicParamField>
|
|
|
|
<DynamicParamField body="enabled" type="boolean">
|
|
Whether this spend limit is enabled.
|
|
</DynamicParamField>
|
|
|
|
<DynamicParamField body="overage_limit" type="number">
|
|
Maximum allowed overage spend for the target feature.
|
|
</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="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>
|
|
|
|
</Expandable>
|
|
</DynamicParamField>
|
|
|
|
|
|
### Response
|
|
|
|
<DynamicResponseField name="customer_id" type="string">
|
|
The ID of the customer.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="line_items" type="object[]">
|
|
<Expandable title="properties">
|
|
<DynamicResponseField name="display_name" type="string">
|
|
The name of the line item to display to the customer if you're building a UI. It will either be the plan name or the feature name.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="description" type="string">
|
|
A detailed description of the line item.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="subtotal" type="number">
|
|
The amount in cents before discounts for this line item.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="total" type="number">
|
|
The final amount in cents after discounts for this line item.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="discounts" type="object[]">
|
|
List of discounts applied to this line item.
|
|
<Expandable title="properties">
|
|
<DynamicResponseField name="amount_off" type="number" />
|
|
|
|
<DynamicResponseField name="percent_off" type="number" />
|
|
|
|
<DynamicResponseField name="reward_id" type="string" />
|
|
|
|
<DynamicResponseField name="reward_name" type="string" />
|
|
|
|
</Expandable>
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="plan_id" type="string">
|
|
The ID of the plan that this line item belongs to.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="feature_id" type="string | null">
|
|
The ID of the feature that this line item belongs to.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="period" type="object">
|
|
The period of time that this line item is being charged for.
|
|
<Expandable title="properties">
|
|
<DynamicResponseField name="start" type="number">
|
|
The start of the period in milliseconds since the Unix epoch.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="end" type="number">
|
|
The end of the period in milliseconds since the Unix epoch.
|
|
</DynamicResponseField>
|
|
|
|
</Expandable>
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="quantity" type="number">
|
|
The quantity of the line item.
|
|
</DynamicResponseField>
|
|
|
|
</Expandable>
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="subtotal" type="number">
|
|
The total amount in cents before discounts for the current billing period.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="total" type="number">
|
|
The final amount in cents after discounts for the current billing period.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="currency" type="string">
|
|
The three-letter ISO currency code (e.g., 'usd').
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="next_cycle" type="object">
|
|
Preview of the next billing cycle, if applicable. This shows what the customer will be charged in subsequent cycles.
|
|
<Expandable title="properties">
|
|
<DynamicResponseField name="starts_at" type="number">
|
|
Unix timestamp (milliseconds) when the next billing cycle starts.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="subtotal" type="number">
|
|
The total amount in cents before discounts for the next cycle.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="total" type="number">
|
|
The final amount in cents after discounts for the next cycle.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="line_items" type="object[]">
|
|
List of line items for the next billing cycle.
|
|
<Expandable title="properties">
|
|
<DynamicResponseField name="display_name" type="string">
|
|
The name of the line item to display to the customer if you're building a UI. It will either be the plan name or the feature name.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="description" type="string">
|
|
A detailed description of the line item.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="subtotal" type="number">
|
|
The amount in cents before discounts for this line item.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="total" type="number">
|
|
The final amount in cents after discounts for this line item.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="discounts" type="object[]">
|
|
List of discounts applied to this line item.
|
|
<Expandable title="properties">
|
|
<DynamicResponseField name="amount_off" type="number" />
|
|
|
|
<DynamicResponseField name="percent_off" type="number" />
|
|
|
|
<DynamicResponseField name="reward_id" type="string" />
|
|
|
|
<DynamicResponseField name="reward_name" type="string" />
|
|
|
|
</Expandable>
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="plan_id" type="string">
|
|
The ID of the plan that this line item belongs to.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="feature_id" type="string | null">
|
|
The ID of the feature that this line item belongs to.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="period" type="object">
|
|
The period of time that this line item is being charged for.
|
|
<Expandable title="properties">
|
|
<DynamicResponseField name="start" type="number">
|
|
The start of the period in milliseconds since the Unix epoch.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="end" type="number">
|
|
The end of the period in milliseconds since the Unix epoch.
|
|
</DynamicResponseField>
|
|
|
|
</Expandable>
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="quantity" type="number">
|
|
The quantity of the line item.
|
|
</DynamicResponseField>
|
|
|
|
</Expandable>
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="usage_line_items" type="object[]">
|
|
List of line items for usage-based features in the next cycle.
|
|
<Expandable title="properties">
|
|
<DynamicResponseField name="display_name" type="string">
|
|
The name of the line item to display to the customer if you're building a UI. It will either be the plan name or the feature name.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="plan_id" type="string">
|
|
The ID of the plan that this line item belongs to.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="feature_id" type="string | null">
|
|
The ID of the feature that this line item belongs to.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="period" type="object">
|
|
The period of time that this line item is being charged for.
|
|
<Expandable title="properties">
|
|
<DynamicResponseField name="start" type="number">
|
|
The start of the period in milliseconds since the Unix epoch.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="end" type="number">
|
|
The end of the period in milliseconds since the Unix epoch.
|
|
</DynamicResponseField>
|
|
|
|
</Expandable>
|
|
</DynamicResponseField>
|
|
|
|
</Expandable>
|
|
</DynamicResponseField>
|
|
|
|
</Expandable>
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="expand" type="string[]">
|
|
Expand the response with additional data.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="incoming" type="object[]">
|
|
Products or subscription changes being added or updated.
|
|
<Expandable title="properties">
|
|
<DynamicResponseField name="plan_id" type="string">
|
|
The ID of the plan affected by this preview change.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="plan" type="object">
|
|
The full plan object if it was expanded in the response.
|
|
<Expandable title="properties">
|
|
<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="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.
|
|
</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>
|
|
|
|
</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'">
|
|
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="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="tiers" type="any[]">
|
|
Tiered pricing configuration. Each tier's 'to' INCLUDES the included amount. Either 'tiers' or 'amount' is required.
|
|
</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>
|
|
|
|
</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>
|
|
|
|
</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>
|
|
|
|
</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="base_variant_id" type="string | null">
|
|
If this is a variant, the ID of the base plan it was created from.
|
|
</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="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>
|
|
|
|
</Expandable>
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="feature_quantities" type="object[]">
|
|
The feature quantity selections associated with this plan change.
|
|
<Expandable title="properties">
|
|
<DynamicResponseField name="feature_id" type="string">
|
|
The ID of the adjustable feature included in this change.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="quantity" type="number">
|
|
The quantity that will apply for this feature in the change.
|
|
</DynamicResponseField>
|
|
|
|
</Expandable>
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="effective_at" type="number | null">
|
|
When this change takes effect, in milliseconds since the Unix epoch, or null if it applies immediately.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="canceled_at" type="number | null">
|
|
When this plan was canceled, in milliseconds since the Unix epoch, or null if it is not canceled.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="expires_at" type="number | null">
|
|
When this plan expires, in milliseconds since the Unix epoch, or null if it does not expire.
|
|
</DynamicResponseField>
|
|
|
|
</Expandable>
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="outgoing" type="object[]">
|
|
Products or subscription changes being removed or ended.
|
|
<Expandable title="properties">
|
|
<DynamicResponseField name="plan_id" type="string">
|
|
The ID of the plan affected by this preview change.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="plan" type="object">
|
|
The full plan object if it was expanded in the response.
|
|
<Expandable title="properties">
|
|
<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="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.
|
|
</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>
|
|
|
|
</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'">
|
|
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="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="tiers" type="any[]">
|
|
Tiered pricing configuration. Each tier's 'to' INCLUDES the included amount. Either 'tiers' or 'amount' is required.
|
|
</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>
|
|
|
|
</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>
|
|
|
|
</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>
|
|
|
|
</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="base_variant_id" type="string | null">
|
|
If this is a variant, the ID of the base plan it was created from.
|
|
</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="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>
|
|
|
|
</Expandable>
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="feature_quantities" type="object[]">
|
|
The feature quantity selections associated with this plan change.
|
|
<Expandable title="properties">
|
|
<DynamicResponseField name="feature_id" type="string">
|
|
The ID of the adjustable feature included in this change.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="quantity" type="number">
|
|
The quantity that will apply for this feature in the change.
|
|
</DynamicResponseField>
|
|
|
|
</Expandable>
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="effective_at" type="number | null">
|
|
When this change takes effect, in milliseconds since the Unix epoch, or null if it applies immediately.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="canceled_at" type="number | null">
|
|
When this plan was canceled, in milliseconds since the Unix epoch, or null if it is not canceled.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="expires_at" type="number | null">
|
|
When this plan expires, in milliseconds since the Unix epoch, or null if it does not expire.
|
|
</DynamicResponseField>
|
|
|
|
</Expandable>
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="redirect_to_checkout" type="boolean">
|
|
Whether the customer will be redirected to a checkout page if attach is called.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="checkout_type" type="'stripe_checkout' | 'autumn_checkout'">
|
|
The type of checkout that will be used if the customer is redirected to a checkout page.
|
|
</DynamicResponseField>
|
|
|
|
|
|
<ResponseExample>
|
|
```json 200
|
|
{
|
|
"customerId": "charles",
|
|
"lineItems": [
|
|
{
|
|
"display_name": "Pro seed",
|
|
"description": "Pro seed - Base Price (from 18 Feb 2026 to 18 Mar 2026)",
|
|
"subtotal": 20,
|
|
"total": 20,
|
|
"discounts": []
|
|
}
|
|
],
|
|
"subtotal": 20,
|
|
"total": 20,
|
|
"currency": "usd"
|
|
}
|
|
```
|
|
</ResponseExample>
|