372 lines
13 KiB
Plaintext
372 lines
13 KiB
Plaintext
---
|
|
title: "Get a plan"
|
|
openapi: "openapi POST /v1/plans.get"
|
|
---
|
|
|
|
import { DynamicParamField } from "/components/dynamic-param-field.jsx";
|
|
import { DynamicResponseField } from "/components/dynamic-response-field.jsx";
|
|
import { DynamicResponseExample } from "/components/dynamic-response-example.jsx";
|
|
|
|
Retrieves a single plan by its ID. Returns the latest version by default.
|
|
|
|
### Common Use Cases
|
|
|
|
<CodeGroup>
|
|
|
|
```typescript Get a plan
|
|
const plan = await autumn.plans.get({
|
|
planId: "pro_plan"
|
|
});
|
|
```
|
|
|
|
```typescript Get a specific version
|
|
const plan = await autumn.plans.get({
|
|
planId: "pro_plan",
|
|
version: 2
|
|
});
|
|
```
|
|
|
|
</CodeGroup>
|
|
|
|
### Body Parameters
|
|
|
|
<DynamicParamField body="plan_id" type="string" required>
|
|
The ID of the plan to retrieve.
|
|
</DynamicParamField>
|
|
|
|
<DynamicParamField body="version" type="number">
|
|
The version of the plan to get. Defaults to the latest version.
|
|
</DynamicParamField>
|
|
|
|
|
|
### Response
|
|
|
|
<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="object[]">
|
|
Tiered pricing configuration. Each tier's 'to' INCLUDES the included amount. Either 'tiers' or 'amount' is required.
|
|
<Expandable title="properties">
|
|
<DynamicResponseField name="to" type="number" />
|
|
|
|
<DynamicResponseField name="amount" type="number" />
|
|
|
|
<DynamicResponseField name="flat_amount" type="number | null" />
|
|
|
|
</Expandable>
|
|
</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="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="customer_eligibility" type="object">
|
|
<Expandable title="properties">
|
|
<DynamicResponseField name="trial_available" type="boolean">
|
|
Whether a free trial is available for this customer.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="scenario" type="'scheduled' | 'active' | 'new' | 'renew' | 'upgrade' | 'downgrade' | 'cancel' | 'expired' | 'past_due'">
|
|
The attach scenario for this customer (e.g. new_subscription, upgrade, downgrade).
|
|
</DynamicResponseField>
|
|
|
|
</Expandable>
|
|
</DynamicResponseField>
|
|
|
|
|
|
<ResponseExample>
|
|
```json 200
|
|
{
|
|
"id": "pro",
|
|
"name": "Pro Plan",
|
|
"description": null,
|
|
"group": null,
|
|
"version": 1,
|
|
"addOn": false,
|
|
"autoEnable": false,
|
|
"price": {
|
|
"amount": 10,
|
|
"interval": "month",
|
|
"display": {
|
|
"primaryText": "$10",
|
|
"secondaryText": "per month"
|
|
}
|
|
},
|
|
"items": [
|
|
{
|
|
"featureId": "messages",
|
|
"included": 100,
|
|
"unlimited": false,
|
|
"reset": {
|
|
"interval": "month"
|
|
},
|
|
"price": {
|
|
"amount": 0.5,
|
|
"interval": "month",
|
|
"billingUnits": 100,
|
|
"billingMethod": "usage_based",
|
|
"maxPurchase": null
|
|
},
|
|
"display": {
|
|
"primaryText": "100 messages",
|
|
"secondaryText": "then $0.5 per 100 messages"
|
|
}
|
|
},
|
|
{
|
|
"featureId": "users",
|
|
"included": 0,
|
|
"unlimited": false,
|
|
"reset": null,
|
|
"price": {
|
|
"amount": 10,
|
|
"interval": "month",
|
|
"billingUnits": 1,
|
|
"billingMethod": "prepaid",
|
|
"maxPurchase": null
|
|
},
|
|
"display": {
|
|
"primaryText": "$10 per Users"
|
|
}
|
|
}
|
|
],
|
|
"createdAt": 1771513979217,
|
|
"env": "sandbox",
|
|
"archived": false,
|
|
"baseVariantId": null
|
|
}
|
|
```
|
|
</ResponseExample>
|