119 lines
2.2 KiB
Markdown
119 lines
2.2 KiB
Markdown
# Paddle Subscriptions
|
|
|
|
Full subscription lifecycle management.
|
|
|
|
## Create Subscription
|
|
|
|
Via checkout (customer initiates):
|
|
```typescript
|
|
paddle.Checkout.open({
|
|
items: [{ priceId: 'pri_monthly', quantity: 1 }],
|
|
customer: { email: 'user@example.com' }
|
|
});
|
|
```
|
|
|
|
## Subscription States
|
|
|
|
| Status | Description |
|
|
|--------|-------------|
|
|
| `trialing` | In trial period |
|
|
| `active` | Actively billed |
|
|
| `past_due` | Payment failed, retrying |
|
|
| `paused` | Temporarily suspended |
|
|
| `canceled` | Terminated |
|
|
|
|
## Upgrade/Downgrade
|
|
|
|
```typescript
|
|
// API: Update subscription items
|
|
PATCH /subscriptions/{sub_id}
|
|
{
|
|
"items": [{ "price_id": "pri_annual", "quantity": 1 }],
|
|
"proration_billing_mode": "prorated_immediately"
|
|
}
|
|
```
|
|
|
|
Proration modes:
|
|
- `prorated_immediately` - Charge/credit now
|
|
- `prorated_next_billing_period` - Apply next cycle
|
|
- `full_immediately` - Full new price now
|
|
- `full_next_billing_period` - Full price next cycle
|
|
- `do_not_bill` - No charge for change
|
|
|
|
## Multi-Item Subscriptions
|
|
|
|
```typescript
|
|
// Add item to existing subscription
|
|
PATCH /subscriptions/{sub_id}
|
|
{
|
|
"items": [
|
|
{ "price_id": "pri_base", "quantity": 1 },
|
|
{ "price_id": "pri_addon", "quantity": 5 }
|
|
]
|
|
}
|
|
```
|
|
|
|
## Trials
|
|
|
|
Set trial on price:
|
|
```typescript
|
|
POST /prices
|
|
{
|
|
"product_id": "pro_xxx",
|
|
"unit_price": { "amount": "999", "currency_code": "USD" },
|
|
"billing_cycle": { "interval": "month", "frequency": 1 },
|
|
"trial_period": { "interval": "day", "frequency": 14 }
|
|
}
|
|
```
|
|
|
|
## Pause/Resume
|
|
|
|
```typescript
|
|
// Pause at end of period
|
|
POST /subscriptions/{sub_id}/pause
|
|
{
|
|
"effective_from": "next_billing_period"
|
|
}
|
|
|
|
// Resume immediately
|
|
POST /subscriptions/{sub_id}/resume
|
|
{
|
|
"effective_from": "immediately"
|
|
}
|
|
```
|
|
|
|
## Cancel
|
|
|
|
```typescript
|
|
// Cancel at end of period
|
|
POST /subscriptions/{sub_id}/cancel
|
|
{
|
|
"effective_from": "next_billing_period"
|
|
}
|
|
|
|
// Cancel immediately
|
|
POST /subscriptions/{sub_id}/cancel
|
|
{
|
|
"effective_from": "immediately"
|
|
}
|
|
```
|
|
|
|
## Customer Portal
|
|
|
|
Self-service subscription management:
|
|
```typescript
|
|
// Get portal URL
|
|
POST /customers/{ctm_id}/portal-sessions
|
|
|
|
// Response
|
|
{
|
|
"data": {
|
|
"id": "cps_xxx",
|
|
"customer_id": "ctm_xxx",
|
|
"urls": {
|
|
"general": { "overview": "https://..." }
|
|
}
|
|
}
|
|
}
|
|
```
|