> ## Documentation Index
> Fetch the complete documentation index at: https://docs.revolv3.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Subscription Billing Plans

> Learn how to create flexible subscription billing plans with different pricing, cycles, and value types. Understand how billing plans work together.

## What are Billing Plans?

A **billing plan** defines how much to charge and when to charge it within a subscription. Think of it as a "pricing rule" that tells Revolv3:

* How much to charge
* How many times to charge it
* When to start charging it
* What type of charge it is (regular price, discount, etc.)

**Why use billing plans:**

* **Flexible pricing**: Different plans for different tiers or features
* **Complex subscriptions**: Setup fees, recurring fees, discounts all in one subscription
* **Trial periods**: Free periods before billing starts
* **Promotional pricing**: Discounts that expire after a certain number of cycles

## Understanding Billing Plans

### Basic Concept

A subscription can have **multiple billing plans** that work together:

**Example**: A subscription with setup fee + monthly fee

* **Plan 1**: \$50 setup fee (charged once, immediately)
* **Plan 2**: \$29.99 monthly fee (charged every month, unlimited)

Both plans are part of the same subscription and work together.

### Billing Plan Fields

| Field             | Type    | Description                                              | Required |
| ----------------- | ------- | -------------------------------------------------------- | -------- |
| `name`            | string  | Human-friendly name (for your records and reports)       | Yes      |
| `value`           | number  | Amount to charge (decimal, must be >= 0)                 | Yes      |
| `cycleCount`      | integer | How many times to charge (-1 = unlimited)                | No       |
| `valueType`       | string  | How to interpret the value                               | No       |
| `startCycleDelay` | integer | Cycles to wait before this plan starts (0 = immediately) | No       |

## Value Types Explained

The `valueType` field tells Revolv3 how to interpret the `value`:

| Value Type           | What It Means                 | Example                                             |
| -------------------- | ----------------------------- | --------------------------------------------------- |
| `Standard`           | Regular charge amount         | `value: 29.99` = Charge \$29.99                     |
| `Discount`           | Fixed dollar discount         | `value: 5.00` = Discount \$5.00                     |
| `DiscountPercentage` | Percentage discount (0-100)   | `value: 10` = 10% discount                          |
| `FinalDiscount`      | Discount applied to the total | `value: 5.00` = Final \$5 discount                  |
| `PriceOverride`      | Override the standard price   | `value: 19.99` = Charge \$19.99 instead of standard |

## Cycle Count Explained

The `cycleCount` field controls how many times a plan charges:

| Value | Meaning                    | Example                                        |
| ----- | -------------------------- | ---------------------------------------------- |
| `-1`  | Unlimited (charge forever) | Monthly fee that never stops                   |
| `1`   | Charge once                | Setup fee, one-time charge                     |
| `12`  | Charge 12 times            | Annual plan that charges monthly for 12 months |
| `0`   | Don't charge               | Not typically used                             |

## Start Cycle Delay Explained

The `startCycleDelay` field controls when a plan starts charging:

| Value | Meaning              | Example                                   |
| ----- | -------------------- | ----------------------------------------- |
| `0`   | Start immediately    | Setup fee charged right away              |
| `1`   | Start after 1 cycle  | Monthly fee starts after first month      |
| `3`   | Start after 3 cycles | Promotional pricing starts after 3 months |

## Real-World Examples

### Example 1: Simple Monthly Subscription

**Scenario**: \$29.99/month, no setup fee, unlimited

```json theme={null}
{
  "SubscriptionBillingPlans": [
    {
      "name": "Monthly Plan",
      "value": 29.99,
      "cycleCount": -1,  // Unlimited
      "valueType": "Standard",
      "startCycleDelay": 0  // Start immediately
    }
  ]
}
```

**Result**: Customer is charged \$29.99 every month, forever (until canceled).

### Example 2: Setup Fee + Monthly Fee

**Scenario**: \$50 setup fee (one-time) + \$19.99/month

```json theme={null}
{
  "SubscriptionBillingPlans": [
    {
      "name": "Setup Fee",
      "value": 50.00,
      "cycleCount": 1,  // Charge once
      "valueType": "Standard",
      "startCycleDelay": 0  // Charge immediately
    },
    {
      "name": "Monthly Fee",
      "value": 19.99,
      "cycleCount": -1,  // Unlimited
      "valueType": "Standard",
      "startCycleDelay": 0  // Also start immediately
    }
  ]
}
```

**Result**: Customer is charged \$50 + \$19.99 immediately, then \$19.99/month going forward.

### Example 3: Free Trial Then Monthly

**Scenario**: 14 days free, then \$9.99/month

```json theme={null}
{
  "TrialDuration": 14,  // Free trial (set at subscription level)
  "SubscriptionBillingPlans": [
    {
      "name": "Monthly Plan",
      "value": 9.99,
      "cycleCount": -1,
      "valueType": "Standard",
      "startCycleDelay": 0  // Starts after trial
    }
  ]
}
```

**Result**: Customer gets 14 days free, then charged \$9.99/month starting on day 15.

### Example 4: Promotional Pricing

**Scenario**: First 3 months at \$9.99, then \$29.99/month

```json theme={null}
{
  "SubscriptionBillingPlans": [
    {
      "name": "Promotional Rate",
      "value": 9.99,
      "cycleCount": 3,  // Charge 3 times
      "valueType": "Standard",
      "startCycleDelay": 0  // Start immediately
    },
    {
      "name": "Regular Rate",
      "value": 29.99,
      "cycleCount": -1,  // Unlimited
      "valueType": "Standard",
      "startCycleDelay": 3  // Start after 3 cycles
    }
  ]
}
```

**Result**:

* Months 1-3: \$9.99/month
* Month 4+: \$29.99/month

### Example 5: Subscription with Discount

**Scenario**: \$29.99/month with \$5 discount for first 6 months

```json theme={null}
{
  "SubscriptionBillingPlans": [
    {
      "name": "Monthly Fee",
      "value": 29.99,
      "cycleCount": -1,
      "valueType": "Standard",
      "startCycleDelay": 0
    },
    {
      "name": "Promotional Discount",
      "value": 5.00,
      "cycleCount": 6,  // Apply discount 6 times
      "valueType": "Discount",  // Fixed dollar discount
      "startCycleDelay": 0
    }
  ]
}
```

**Result**: Customer pays \$24.99/month (\$29.99 - \$5.00) for first 6 months, then \$29.99/month after.

## Understanding Value and ValueType

### Standard Charges

When `valueType` is `Standard`, `value` is the amount to charge:

```json theme={null}
{
  "value": 29.99,
  "valueType": "Standard"
}
```

Charges \$29.99.

### Discounts

When `valueType` is `Discount`, `value` is subtracted from other charges:

```json theme={null}
{
  "value": 5.00,
  "valueType": "Discount"
}
```

Subtracts \$5.00 from the total.

### Percentage Discounts

When `valueType` is `DiscountPercentage`, `value` is a percentage (0-100):

```json theme={null}
{
  "value": 10,  // 10%, not 0.10
  "valueType": "DiscountPercentage"
}
```

Applies a 10% discount.

**Important**: For percentage discounts, `value` is the percentage number (10 = 10%), not a decimal (0.10).

## Best Practices

1. **Use descriptive names**: Make plan names clear for reporting and reconciliation
2. **Validate amounts**: Check that values are correct before sending (>= 0, reasonable amounts)
3. **Test combinations**: Test how multiple plans work together
4. **Keep it simple**: Don't over-complicate with too many plans
5. **Document your logic**: Keep notes on how your billing plans work together

## Common Questions

**Q: Can I have multiple billing plans in one subscription?**
A: Yes, you can have multiple plans. They work together (e.g., setup fee + monthly fee).

**Q: What's the difference between Discount and FinalDiscount?**
A: `Discount` is applied to specific line items, `FinalDiscount` is applied to the total after all other charges.

**Q: How do I create a free trial?**
A: Use `TrialDuration` at the subscription level, or create a plan with `value: 0` and `cycleCount: 1`.

**Q: Can I change billing plans after creating a subscription?**
A: You can update subscriptions, but check the API documentation for how plan changes are handled.

**Q: What if cycleCount is -1?**
A: `-1` means unlimited—the plan will charge forever (until subscription is canceled).

## Next Steps

* **[Create a Subscription](/docs/core-concepts/subscription/create-subscription)** — See how billing plans are used when creating subscriptions
* **[Invoice Line Items](/docs/core-concepts/subscription/invoice-line-items-subscription-plans)** — Understand how line items relate to billing plans
* **[Canceling Subscriptions](/docs/core-concepts/subscription/canceling-a-subscription)** — Learn what happens to billing plans when subscriptions are canceled

***