Subscription Billing Plans

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

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

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

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

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

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

{
  "value": 29.99,
  "valueType": "Standard"
}

Charges $29.99.

Discounts

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

{
  "value": 5.00,
  "valueType": "Discount"
}

Subtracts $5.00 from the total.

Percentage Discounts

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

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

Use descriptive names: Make plan names clear for reporting and reconciliation
Validate amounts: Check that values are correct before sending (>= 0, reasonable amounts)
Test combinations: Test how multiple plans work together
Keep it simple: Don’t over-complicate with too many plans
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 — See how billing plans are used when creating subscriptions
Invoice Line Items — Understand how line items relate to billing plans
Canceling Subscriptions — Learn what happens to billing plans when subscriptions are canceled

Getting Started

Authentication & Security

Core Concepts & Data Models

Integration Flows

Plugins

API Reference

Webhooks & Event Handling

Error Codes & Troubleshooting

Testing & Sandbox

Certification & Go-Live Checklist

Appendix / Glossary

FAQ

What are Billing Plans?

Understanding Billing Plans

Basic Concept

Billing Plan Fields

Value Types Explained

Cycle Count Explained

Start Cycle Delay Explained

Real-World Examples

Example 1: Simple Monthly Subscription

Example 2: Setup Fee + Monthly Fee

Example 3: Free Trial Then Monthly

Example 4: Promotional Pricing

Example 5: Subscription with Discount

Understanding Value and ValueType

Standard Charges

Discounts

Percentage Discounts

Best Practices

Common Questions

Next Steps

​What are Billing Plans?

​Understanding Billing Plans

​Basic Concept

​Billing Plan Fields

​Value Types Explained

​Cycle Count Explained

​Start Cycle Delay Explained

​Real-World Examples

​Example 1: Simple Monthly Subscription

​Example 2: Setup Fee + Monthly Fee

​Example 3: Free Trial Then Monthly

​Example 4: Promotional Pricing

​Example 5: Subscription with Discount

​Understanding Value and ValueType

​Standard Charges

​Discounts

​Percentage Discounts

​Best Practices

​Common Questions

​Next Steps

What are Billing Plans?

Understanding Billing Plans

Basic Concept

Billing Plan Fields

Value Types Explained

Cycle Count Explained

Start Cycle Delay Explained

Real-World Examples

Example 1: Simple Monthly Subscription

Example 2: Setup Fee + Monthly Fee

Example 3: Free Trial Then Monthly

Example 4: Promotional Pricing

Example 5: Subscription with Discount

Understanding Value and ValueType

Standard Charges

Discounts

Percentage Discounts

Best Practices

Common Questions

Next Steps