# Subscriptions

Automate recurring payments with flexible subscription management.

## Overview

Subscriptions are recurring payments of a fixed amount, automatically charged at regular intervals. They're perfect for membership services, SaaS products, and any business model requiring predictable recurring revenue.

## Key Features

- **Automatic Billing**: Payments processed automatically on schedule
- **Flexible Frequencies**: From daily to every 3 years
- **Retry Logic**: Configurable retries for failed payments
- **Fallback Methods**: Secondary payment method if primary fails
- **Finite or Unlimited**: Set end date/capture limit or run indefinitely
- **Easy Management**: Activate, pause, update, or cancel anytime


## Supported Payment Methods

- Credit/Debit Card
- Direct Debit


## Frequency Options

| Frequency | Description |
|  --- | --- |
| `1D` | Daily |
| `1W` | Weekly |
| `2W` | Bi-weekly (every 2 weeks) |
| `1M` | Monthly |
| `2M` | Bi-monthly (every 2 months) |
| `3M` | Quarterly (every 3 months) |
| `4M` | Every 4 months |
| `6M` | Semi-annually (every 6 months) |
| `1Y` | Annually |
| `2Y` | Every 2 years |
| `3Y` | Every 3 years |


## Subscription Lifecycle

![Subscription lifecycle](https://mermaid.ink/svg/pako:eNq1Vt1q2zAUfpWDLkYC6U9auiSGFkrLoBftwlJ2MQJFkY9jUVvyZHluVvImYw-3J9lRLDtOm6broL6S5fOdn-98OvIjEzpEFrAcvxeoBF5KPjc8nSqghxdWqyKdoaneM26sFDLjysI1GhG7Bc_X6_MsS6TgVmr1HDGejM_HV85-zBcpOvPx1RazhNtIm9QZTkSMYZFsi3-DttTmvu3Ob0197DqrvbOzKnQAFwa5RZgUs1wYmbk8oTP-PLmFg7y1160cVCgH9ykF8JUnMnQuPgBtlNyEILSK5NwjvOEGxgeVSlrJE5jJJJFqDmIhEoRObrkt8tMMVUi7PrLSBNA_0MDazSUKGaKH2UWGAQie2cLgndIlaAMGFZZ8lmDNAE9s26bafJKnJy2Ac2sxzRoAdOqEVxG7a7BH7G0U-QXzIrGVESY5tpPZEnUNrFsMkTS59eVlVHmWcLXGbmPkRoNMUwylo7dOmzoqHOGNBInYNh9XEfDGuCT18KpuDKHjeaQAaFoFO1itsUkhBOb5-uOLhV1zUmdVzinkO2GEq8VKhFDCUOIs1vrelS0jf6JIKy2N3tU1eNetfFf81wl_4jIhs83IidYZtcyaBXQq_RbG9aomIz-YcXGvo6i7iXtJO5Urn9FzyKuKaTJ3vXobsxHVh-F7EFt5fsKA04KjdCVFVI60cAdH_5VA5P3frYSM_9iDW-oAZYdGueOQ-fanaGMdvqklLpuVpA6iSjvd9yoQSmljmhQuaneHEpqX1ln2EhaFMe7egk49MyAy1V226L4yevxgVvhgn07lzXH8EuVjox1PkPsZFj4_Art4_vP7F-Q8bY5wzTcQm6HLpima9djcyJAF1hTYYymalLtX9uhMpszGmOKUBbQsY2lpOVVLAtFN-U3rtMYZXcxjFkScBkSPFZm7yfyF35hQNDQXulCWBScnKxcseGQPLDga9veP-sfHg_5w9HHYP6SPCxYcD_dH9AxGo8PhaDAYnCx77Ocq5uH-cEA2NJ-tNtfVb0Y1bNjyL5I9xzY)

## Quick Start

### Create a Subscription


```bash
POST /subscription

{
  "frequency": "1M",
  "value": 29.99,
  "currency": "EUR",
  "method": "cc",
  "start_time": "2024-02-01 00:00",
  "max_captures": 12,
  "customer": {
    "name": "John Doe",
    "email": "john@example.com"
  },
  "capture": {
    "descriptive": "Monthly SaaS Subscription"
  },
  "retries": 3,
  "failover": true
}
```

Response:


```json
{
  "id": "sub-123",
  "status": "active",
  "frequency": "1M",
  "value": 29.99,
  "start_time": "2024-02-01 00:00"
}
```

## Subscription Types

### Finite Subscriptions

End after a specific date or number of captures:


```json
{
  "frequency": "1M",
  "value": 9.99,
  "start_time": "2024-01-01",
  "max_captures": 12  // 12 months
}
```

Or:


```json
{
  "frequency": "1M",
  "value": 9.99,
  "start_time": "2024-01-01",
  "expiration_time": "2024-12-31 23:59"  // Specific end date
}
```

### Unlimited Subscriptions

Continue until manually cancelled:


```json
{
  "frequency": "1M",
  "value": 9.99,
  "start_time": "2024-01-01",
  "unlimited_payments": true  // No end date
}
```

## Cycle Types

Each subscription creates payment cycles:

- **CAPTURE_NOW**: Immediate payment when subscription created
- **RENEWABLE**: Regular recurring cycles based on frequency
- **ONE_TIME_CHARGE**: Single isolated payment


## Managing Subscriptions

### Get Subscription Details


```bash
GET /subscription/{id}
```

### Update a Subscription


```bash
PATCH /subscription/{id}

{
  "value": 39.99,  // Update amount
  "frequency": "1Y"  // Change frequency
}
```

### Pause a Subscription


```bash
PATCH /subscription/{id}

{
  "status": "inactive"
}
```

**Effect**: All pending cycles are deleted, no further payments.

### Reactivate a Subscription


```bash
PATCH /subscription/{id}

{
  "status": "active"
}
```

**Effect**: New cycles created based on current configuration.

### Cancel a Subscription


```bash
DELETE /subscription/{id}
```

## Retry Logic

Configure automatic retries for failed payments:


```json
{
  "retries": 3  // Retry up to 3 times
}
```

**How it works**:

1. Initial charge attempt
2. If failed, retry
3. Continue until success or max retries reached
4. Trigger fallback if configured


## Fallback Payment Methods (Failover)

Enable fallback to provide alternative payment options:


```json
{
  "method": "cc",  // Primary method
  "failover": true
}
```

**How it works**:

1. Attempt payment with primary method
2. If fails after all retries, a failover checkout is created
3. The checkout includes all payment methods active for your account
4. If payment succeeds through the checkout, subscription continues
5. If no payment is made, the cycle is marked as failed


## Use Cases

### SaaS Subscription

Monthly software license:


```json
{
  "frequency": "1M",
  "value": 49.99,
  "method": "cc",
  "start_time": "2024-01-01",
  "unlimited_payments": true,
  "retries": 3
}
```

### Annual Membership

Yearly membership fee:


```json
{
  "frequency": "1Y",
  "value": 199.99,
  "method": "cc",
  "start_time": "2024-01-01",
  "unlimited_payments": true
}
```

### Installment Plan

12-month payment plan:


```json
{
  "frequency": "1M",
  "value": 83.33,
  "method": "dd",
  "start_time": "2024-01-01",
  "max_captures": 12  // Total: €999.96
}
```

### Quarterly Service

Quarterly billing:


```json
{
  "frequency": "3M",
  "value": 299.99,
  "method": "cc",
  "start_time": "2024-01-01",
  "unlimited_payments": true
}
```

## Webhooks

Receive notifications for subscription events:

- **subscription_created**: Sent when the user inserts their card details and the subscription is created
- **subscription_capture**: Sent after all retries are made for a payment attempt (whether successful or failed)


## Best Practices

1. **Clear Communication**: Inform customers about subscription terms upfront
2. **Grace Periods**: Consider grace periods before canceling for failed payments
3. **Easy Cancellation**: Make it simple for customers to cancel
4. **Update Payment Methods**: Allow customers to update payment details
5. **Transparent Pricing**: Clearly display total cost and billing frequency
6. **Trial Periods**: Consider free trials before first charge
7. **Prorated Charges**: Handle mid-cycle plan changes gracefully


## Common Scenarios

### Scenario 1: Monthly SaaS

Customer subscribes to monthly software, charged automatically on the 1st of each month, continues until cancelled.

### Scenario 2: Annual Membership

Customer pays yearly membership fee, receives reminder 30 days before renewal, can cancel or update payment method.

### Scenario 3: 12-Month Installment

Customer buys €1000 product, pays €83.33/month for 12 months, subscription automatically ends after final payment.

### Scenario 4: Quarterly Service

Service billed every 3 months, customer receives invoice 7 days before charge, payment auto-processed.

## Next Steps

- [Subscription API Reference](/openapi#tag/Subscription-Payment) - Complete API documentation
- [Webhooks Guide](/docs/guides/webhooks) - Handle subscription events
- [Checkout](/docs/products/checkout) - Accept subscriptions via Checkout
- [Payment Types Guide](/docs/guides/payment-types) - Learn about subscription payments