> ## 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.

# Invoice Line Items & Subscription Plans

> Understand how invoice line items and subscription billing plans work together to create structured billing for one-time charges and recurring payments.

## What are Invoice Line Items and Billing Plans?

**Invoice Line Items** and **Subscription Billing Plans** are the building blocks of structured billing in Revolv3. They let you break down charges into individual components, making it easier to:

* Show customers what they're being charged for
* Apply discounts and adjustments
* Handle complex pricing structures
* Generate detailed invoices

**Think of it like an itemized receipt:**

* **Line items**: Individual charges on a one-time invoice (product \$50, shipping \$5, tax \$4 = \$59 total)
* **Billing plans**: Pricing rules for subscriptions (setup fee \$50, monthly fee \$29.99)

## Invoice Line Items

**Invoice Line Items** represent individual charges on a single invoice. Each line item is a separate charge that gets added together to create the total.

### When to Use Line Items

Use line items for:

* ✅ **One-time invoices**: Breaking down a purchase into components
* ✅ **Itemized billing**: Showing customers what they're paying for
* ✅ **Discounts and adjustments**: Applying discounts to specific items
* ✅ **Complex pricing**: Multiple products, fees, taxes, etc. in one invoice

### Line Item Fields

| Field         | Type   | Required | Description                                  |
| ------------- | ------ | -------- | -------------------------------------------- |
| `Name`        | string | Yes      | Title/name of the charge (shown on invoice)  |
| `Description` | string | No       | Brief explanation of what this charge is for |
| `Value`       | number | Yes      | Amount in USD (decimal)                      |
| `ValueType`   | string | Yes      | Type of charge (see below)                   |

### Value Types for Line Items

| Value Type           | What It Means               | Example                            |
| -------------------- | --------------------------- | ---------------------------------- |
| `Standard`           | Regular charge              | Product price, service fee         |
| `Discount`           | Fixed dollar discount       | "\$5 off" discount                 |
| `DiscountPercentage` | Percentage discount (0-100) | "10% off" (value = 10)             |
| `FinalDiscount`      | Discount applied to total   | Final "\$10 off" after all charges |
| `PriceOverride`      | Override standard price     | Special pricing for this item      |

### Example: Invoice with Line Items

```json theme={null}
{
  "Invoice": {
    "MerchantInvoiceRefId": "ORDER-12345",
    "Amount": {
      "value": 59.00  // Total of all line items
    },
    "InvoiceLineItems": [
      {
        "Name": "Product A",
        "Description": "Widget purchase",
        "Value": 50.00,
        "ValueType": "Standard"
      },
      {
        "Name": "Shipping",
        "Description": "Standard shipping",
        "Value": 5.00,
        "ValueType": "Standard"
      },
      {
        "Name": "Tax",
        "Description": "Sales tax",
        "Value": 4.00,
        "ValueType": "Standard"
      }
    ]
  }
}
```

**Total**: \$50 + \$5 + \$4 = \$59.00

## Subscription Billing Plans

**Subscription Billing Plans** define the pricing structure for recurring subscriptions. They tell Revolv3 how much to charge and when.

### When to Use Billing Plans

Use billing plans for:

* ✅ **Recurring subscriptions**: Monthly, weekly, yearly charges
* ✅ **Setup fees**: One-time charges when subscription starts
* ✅ **Tiered pricing**: Different prices for different subscription tiers
* ✅ **Promotional pricing**: Discounts that expire after a certain number of cycles

### Billing Plan Fields

| Field             | Type    | Required | Description                                      |
| ----------------- | ------- | -------- | ------------------------------------------------ |
| `name`            | string  | Yes      | Plan name (for your records)                     |
| `value`           | number  | Yes      | Amount to charge (decimal, >= 0)                 |
| `cycleCount`      | integer | No       | How many times to charge (-1 = unlimited)        |
| `valueType`       | string  | No       | Type of charge (Standard, Discount, etc.)        |
| `startCycleDelay` | integer | No       | Cycles to wait before starting (0 = immediately) |

### Example: Subscription with Multiple Plans

```json theme={null}
{
  "BillingFrequency": {
    "intervalCount": 1,
    "intervalType": "Months"
  },
  "SubscriptionBillingPlans": [
    {
      "name": "Setup Fee",
      "value": 50.00,
      "cycleCount": 1,  // Charge once
      "valueType": "Standard",
      "startCycleDelay": 0  // Charge immediately
    },
    {
      "name": "Monthly Fee",
      "value": 29.99,
      "cycleCount": -1,  // Unlimited (charge forever)
      "valueType": "Standard",
      "startCycleDelay": 0  // Start immediately
    }
  ]
}
```

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

## How They Work Together

### Line Items for One-Time Invoices

For one-time payments, use `InvoiceLineItems` to break down the charge:

```json theme={null}
{
  "Invoice": {
    "Amount": { "value": 100.00 },
    "InvoiceLineItems": [
      {
        "Name": "Product",
        "Value": 90.00,
        "ValueType": "Standard"
      },
      {
        "Name": "Shipping",
        "Value": 10.00,
        "ValueType": "Standard"
      }
    ]
  }
}
```

### Billing Plans for Subscriptions

For subscriptions, use `SubscriptionBillingPlans` to define recurring charges:

```json theme={null}
{
  "SubscriptionBillingPlans": [
    {
      "name": "Monthly Plan",
      "value": 29.99,
      "cycleCount": -1,
      "valueType": "Standard"
    }
  ]
}
```

### They Can Overlap

Subscriptions can also have line items on individual invoices. When a subscription generates an invoice, that invoice can have line items that break down what the customer is being charged for in that billing cycle.

## Real-World Examples

### Example 1: E-Commerce Order (Line Items)

**Scenario**: Customer buys a product with shipping and tax

```json theme={null}
{
  "Invoice": {
    "Amount": { "value": 59.00 },
    "InvoiceLineItems": [
      {
        "Name": "Widget",
        "Description": "Blue widget",
        "Value": 50.00,
        "ValueType": "Standard"
      },
      {
        "Name": "Shipping",
        "Value": 5.00,
        "ValueType": "Standard"
      },
      {
        "Name": "Tax",
        "Value": 4.00,
        "ValueType": "Standard"
      }
    ]
  }
}
```

### Example 2: Subscription with Setup Fee (Billing Plans)

**Scenario**: SaaS subscription with \$50 setup + \$29.99/month

```json theme={null}
{
  "SubscriptionBillingPlans": [
    {
      "name": "Setup Fee",
      "value": 50.00,
      "cycleCount": 1,
      "valueType": "Standard",
      "startCycleDelay": 0
    },
    {
      "name": "Monthly Subscription",
      "value": 29.99,
      "cycleCount": -1,
      "valueType": "Standard",
      "startCycleDelay": 0
    }
  ]
}
```

### Example 3: Subscription with Discount (Billing Plans)

**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"
    },
    {
      "name": "Promotional Discount",
      "value": 5.00,
      "cycleCount": 6,  // Apply for 6 months
      "valueType": "Discount"  // Subtracts $5
    }
  ]
}
```

**Result**: Customer pays \$24.99/month for first 6 months, then \$29.99/month.

## Value Types Explained

### Standard

Regular charge amount:

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

Charges \$29.99.

### Discount

Fixed dollar amount discount:

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

Subtracts \$5.00 from the total.

### DiscountPercentage

Percentage discount (value is 0-100):

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

Applies a 10% discount.

**Important**: For percentage discounts, use the whole number (10 = 10%), not a decimal (0.10).

### FinalDiscount

Discount applied to the final total:

```json theme={null}
{
  "value": 10.00,
  "valueType": "FinalDiscount"
}
```

Applies \$10 discount to the total after all other charges.

### PriceOverride

Override the standard price:

```json theme={null}
{
  "value": 19.99,
  "valueType": "PriceOverride"
}
```

Charges \$19.99 instead of the standard price.

## Best Practices

1. **Use clear names**: Make line item and plan names descriptive for reporting
2. **Validate values**: Ensure amounts are correct (>= 0, reasonable)
3. **Test calculations**: Verify that line items/plans add up correctly
4. **Keep it organized**: Don't create too many line items or plans—keep it manageable
5. **Document your logic**: Keep notes on how your billing structure works

## Common Questions

**Q: What's the difference between line items and billing plans?**
A: Line items are for one-time invoices (breaking down a single charge). Billing plans are for subscriptions (defining recurring charges).

**Q: Can I use both in the same request?**
A: For subscriptions, you use billing plans. The subscription will generate invoices, and those invoices can have line items.

**Q: How do discounts work with multiple plans?**
A: Discount plans subtract from other charges. The order and calculation depend on how Revolv3 processes them—test to verify.

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

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

## Next Steps

* **[Create a Subscription](/docs/core-concepts/subscription/create-subscription)** — See how billing plans are used
* **[Billing Plans](/docs/core-concepts/subscription/billing-plans)** — Detailed guide to billing plan options
* **[Make a Payment](/docs/getting-started/make-a-payment)** — See how line items work in one-time payments

***