Skip to main content

​
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

FieldTypeRequiredDescription
NamestringYesTitle/name of the charge (shown on invoice)
DescriptionstringNoBrief explanation of what this charge is for
ValuenumberYesAmount in USD (decimal)
ValueTypestringYesType of charge (see below)

​
Value Types for Line Items

Value TypeWhat It MeansExample
StandardRegular chargeProduct price, service fee
DiscountFixed dollar discount”$5 off” discount
DiscountPercentagePercentage discount (0-100)“10% off” (value = 10)
FinalDiscountDiscount applied to totalFinal “$10 off” after all charges
PriceOverrideOverride standard priceSpecial pricing for this item

​
Example: Invoice with Line Items

{
  "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

FieldTypeRequiredDescription
namestringYesPlan name (for your records)
valuenumberYesAmount to charge (decimal, >= 0)
cycleCountintegerNoHow many times to charge (-1 = unlimited)
valueTypestringNoType of charge (Standard, Discount, etc.)
startCycleDelayintegerNoCycles to wait before starting (0 = immediately)

​
Example: Subscription with Multiple Plans

{
  "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: 
{
  "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: 
{
  "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 
{
  "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 
{
  "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 
{
  "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: 
{
  "value": 29.99,
  "valueType": "Standard"
}
Charges $29.99.

​
Discount

Fixed dollar amount discount: 
{
  "value": 5.00,
  "valueType": "Discount"
}
Subtracts $5.00 from the total.

​
DiscountPercentage

Percentage discount (value is 0-100): 
{
  "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: 
{
  "value": 10.00,
  "valueType": "FinalDiscount"
}
Applies $10 discount to the total after all other charges.

​
PriceOverride

Override the standard price: 
{
  "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