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.)
- 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)
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
ThevalueType 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
ThecycleCount 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
ThestartCycleDelay 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, unlimitedExample 2: Setup Fee + Monthly Fee
Scenario: $50 setup fee (one-time) + $19.99/monthExample 3: Free Trial Then Monthly
Scenario: 14 days free, then $9.99/monthExample 4: Promotional Pricing
Scenario: First 3 months at $9.99, then $29.99/month- 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 monthsUnderstanding Value and ValueType
Standard Charges
WhenvalueType is Standard, value is the amount to charge:
Discounts
WhenvalueType is Discount, value is subtracted from other charges:
Percentage Discounts
WhenvalueType is DiscountPercentage, value is a percentage (0-100):
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