140 lines
3.4 KiB
Plaintext
140 lines
3.4 KiB
Plaintext
---
|
|
title: "Create a plan"
|
|
openapi: "openapi POST /v1/plans.create"
|
|
---
|
|
|
|
import { DynamicParamField } from "/snippets/dynamic-param-field.jsx";
|
|
import { DynamicResponseField } from "/snippets/dynamic-response-field.jsx";
|
|
import { DynamicResponseExample } from "/snippets/dynamic-response-example.jsx";
|
|
|
|
Creates a new plan with optional base price and feature configurations. See [How plans work](/documentation/concepts/plans) for concepts and [Adding features to plans](/documentation/concepts/plan-items) for item configuration.
|
|
|
|
### Plan Configuration
|
|
|
|
A plan consists of:
|
|
- **Base price** - optional recurring charge for the plan itself
|
|
- **Items** - feature configurations defining what customers get and how they're billed
|
|
|
|
### Configuring Items
|
|
|
|
Each item in the `items` array configures a single feature. There are two types:
|
|
|
|
**Consumable features** (API calls, messages, credits):
|
|
- Set `included` for free units that reset each period
|
|
- Set `reset.interval` to define when balance resets to `included`
|
|
- Optionally add `price` for usage beyond included amount
|
|
|
|
**Non-consumable features** (seats, storage):
|
|
- Set `included` for the base allocation
|
|
- Do NOT set `reset` - usage persists across billing cycles
|
|
- Use `billing_method: "prepaid"` for upfront payment per unit
|
|
|
|
### Common Use Cases
|
|
|
|
<CodeGroup>
|
|
|
|
```typescript Free plan with auto-enable
|
|
await autumn.plans.create({
|
|
planId: "free_plan",
|
|
name: "Free",
|
|
autoEnable: true, // Automatically attached on customer creation
|
|
items: [
|
|
{
|
|
featureId: "messages",
|
|
included: 100,
|
|
reset: { interval: "month" }
|
|
}
|
|
]
|
|
});
|
|
```
|
|
|
|
```typescript Paid plan with base price + usage-based feature
|
|
await autumn.plans.create({
|
|
planId: "pro_plan",
|
|
name: "Pro Plan",
|
|
price: { amount: 10, interval: "month" },
|
|
items: [
|
|
{
|
|
featureId: "messages",
|
|
included: 1000,
|
|
reset: { interval: "month" },
|
|
price: {
|
|
amount: 0.01,
|
|
interval: "month",
|
|
billingUnits: 1,
|
|
billingMethod: "usage_based"
|
|
}
|
|
}
|
|
]
|
|
});
|
|
```
|
|
|
|
```typescript Plan with prepaid seats
|
|
await autumn.plans.create({
|
|
planId: "team_plan",
|
|
name: "Team Plan",
|
|
price: { amount: 49, interval: "month" },
|
|
items: [
|
|
{
|
|
featureId: "seats",
|
|
included: 5,
|
|
// No reset - seats persist across billing cycles
|
|
price: {
|
|
amount: 10,
|
|
interval: "month",
|
|
billingUnits: 1,
|
|
billingMethod: "prepaid"
|
|
}
|
|
}
|
|
]
|
|
});
|
|
```
|
|
|
|
```typescript Add-on plan
|
|
await autumn.plans.create({
|
|
planId: "analytics_addon",
|
|
name: "Advanced Analytics",
|
|
addOn: true, // Can be attached alongside other plans
|
|
price: { amount: 20, interval: "month" }
|
|
});
|
|
```
|
|
|
|
```typescript Plan with tiered pricing
|
|
await autumn.plans.create({
|
|
planId: "api_plan",
|
|
name: "API Plan",
|
|
items: [
|
|
{
|
|
featureId: "api_calls",
|
|
included: 1000,
|
|
reset: { interval: "month" },
|
|
price: {
|
|
tiers: [
|
|
{ to: 10000, amount: 0.001 },
|
|
{ to: 100000, amount: 0.0005 },
|
|
{ to: "inf", amount: 0.0001 }
|
|
],
|
|
interval: "month",
|
|
billingUnits: 1,
|
|
billingMethod: "usage_based"
|
|
}
|
|
}
|
|
]
|
|
});
|
|
```
|
|
|
|
```typescript Plan with free trial
|
|
await autumn.plans.create({
|
|
planId: "premium_plan",
|
|
name: "Premium",
|
|
price: { amount: 99, interval: "month" },
|
|
freeTrial: {
|
|
durationLength: 14,
|
|
durationType: "day",
|
|
cardRequired: true
|
|
}
|
|
});
|
|
```
|
|
|
|
</CodeGroup>
|