Billing Schedules Overview

Automate recurring billing with flexible scheduling and automatic invoice generation

Billing schedules automate recurring invoice generation for subscriptions, contracts, and periodic billing. Set up schedules with flexible frequencies from daily to annually, configure autopay for automatic payment collection, and define line items that appear on every invoice. Billing schedules eliminate manual invoice creation, ensure consistent billing cycles, and provide customers with predictable payment schedules.

Common Use Cases

• Subscription Services - Monthly SaaS, annual licenses, tiered memberships, usage-based billing
• Contracts and Agreements - Quarterly maintenance, annual service agreements, retainer billing
• Recurring Services - Weekly/biweekly charges, monthly rentals, daily equipment rentals
• Membership and Clubs - Gym memberships, annual club dues, quarterly fees, weekly classes

Prerequisites

Before creating billing schedules, ensure you have:

Understanding Billing Schedules

Billing schedules define when and how often to automatically generate invoices.

Recurring Schedule

Defines billing frequency including daily, weekly, biweekly, bimonthly, monthly, quarterly, and annually. Each frequency specifies exact billing days or months based on the schedule type, controlling when automatic invoice generation occurs for predictable billing cycles.

Billing Items

Line items that appear on every generated invoice with value, quantity, and description. Items can have start and end dates for time-limited charges, and can be grouped for better invoice organization and structured billing presentation.

Schedule Dates

The start_date defines when billing begins and the first invoice is generated, while end_date optionally specifies when billing stops (leave empty for indefinite billing). Items can have independent start and end dates within the schedule for flexible charge timing.

Autopay Settings

The autopay_settings.allowed field controls automatic payment and defaults to true. When enabled, invoices are automatically charged on their due date, requiring the payer to have a payment method configured for seamless payment collection.

Financial Tracking

Track schedule performance with totals.recurring_amount showing the amount charged each billing cycle, totals.total for lifetime total across all generated invoices, totals.paid for total amount successfully paid, and totals.balance_due for outstanding unpaid balance.

Billing Frequencies

Billing Items

Billing items define the charges that appear on each generated invoice.

Billing Item Types

• Basic
• Quantity-Based
• Percentage-Based
• Time-Limited
• Item Groups

{
    type: "line_item",
    description: "Pro Plan Subscription",
    line_item: {
        value: 49.99,
        qty: 1
    }
}

{
    type: "line_item",
    description: "User Licenses",
    line_item: {
        value: 10.00,  // Per user
        qty: 5         // 5 users = $50.00 total
    }
}

{
    type: "line_item",
    description: "Processing Fee",
    line_item: {
        value: 2.5,           // 2.5%
        value_units: "percentage",
        qty: 1
    }
}

{
    type: "line_item",
    description: "Holiday Promotion Discount",
    start_date: "2024-12-01",
    end_date: "2024-12-31",
    line_item: {
        value: -10.00,  // Negative for discount
        qty: 1
    }
}

{
    type: "item_group",
    description: "Base Services",
    item_group: {
        items: [
            {
                type: "line_item",
                description: "Platform Access",
                line_item: { value: 29.99, qty: 1 }
            },
            {
                type: "line_item",
                description: "Support",
                line_item: { value: 10.00, qty: 1 }
            }
        ]
    }
}

Managing Billing Items

• Add Item
• Update Item
• Remove Item

item = pl.BillingItem.create(
    billing_schedule_id="bscd_abc123",
    type="line_item",
    description="Additional Feature",
    start_date="2024-03-01",  # Starts in future
    line_item={
        "value": 15.0,
        "qty": 1
    }
)

item = pl.BillingItem.get("bcrg_abc123")
item.update(
    line_item={
        "value": 59.99,  # New price
        "qty": 1
    }
)

# Set end_date to stop including in future invoices
item = pl.BillingItem.get("bcrg_abc123")
item.update(
    end_date="2024-12-31"
)
 
# Or delete immediately
item_to_delete = pl.BillingItem.get("bcrg_abc123")
item_to_delete.delete()

How Billing Schedules Work

Understand the complete workflow of billing schedules.

Invoice Generation Process

Schema Reference

Fields relevant to billing schedule configuration:

BillingSchedule Fields

BillingItem Fields

Next Steps

Enhance your recurring billing with automated schedules and payment workflows

Set Up Billing Schedules

Create and manage recurring billing with Create Billing Schedules to set up new recurring billing with flexible frequencies, modify existing schedules with Update Billing Schedules to change frequencies and billing items, and understand invoice generation with Creating Invoices for generated invoice structure and configuration.

Configure Payment Collection

Enable automatic payments with Automatic Payments to charge customers on invoice due dates, process manual payments with Payment API for programmatic invoice payment processing, and send payment requests with Payment Requests to share payment links via email or SMS.

Track Schedule Performance

Monitor invoice lifecycle with Invoice Statuses to track generated invoice payment status, automate post-invoice workflows with Webhook Events for real-time billing notifications, and analyze revenue metrics with Reporting Overview to track MRR, ARR, and churn.

Related articles

• Create Billing Schedules - Set up recurring billing schedules
• Update Billing Schedules - Manage schedule lifecycle
• Automatic Payments - Configure autopay settings
• Creating Invoices - Understand invoice structure
• Invoice Statuses - Track generated invoice lifecycle
• Billing Schedules API Reference - Complete API documentation