Update Billing Schedules

Manage existing billing schedules, modify frequencies, update items, and control schedule lifecycle

Update billing schedules to adapt to changing subscription needs, customer requirements, and business conditions. Change billing frequencies, add or remove billing items, configure autopay settings, pause or cancel schedules, and query schedules by various criteria. All schedule modifications preserve the complete invoice generation history while applying changes to future billing cycles.

Prerequisites

Before updating billing schedules, ensure you have:

Managing Billing Schedules

Retrieve, modify, and control the lifecycle of existing billing schedules.

Retrieve Schedule

from datetime import date
 
import payload
 
pl = payload.Session('secret_key_3bW9...', api_version='v2')
 
# Managing billing schedules
 
# Retrieve a billing schedule
schedule = pl.BillingSchedule.get('bscd_abc123')
 
print(f'Schedule: {schedule.description}')
print(f'Status: Active from {schedule.start_date}')
print(
    f'Recurring: ${schedule.totals['recurring_amount']} {schedule.recurring_schedule['type']}'
)
print(f'Total billed: ${schedule.totals['total']}')
print(f'Total paid: ${schedule.totals['paid']}')
print(f'Balance due: ${schedule.totals['balance_due']}')
 
# Update billing schedule - change frequency
schedule.update(
    recurring_schedule={
        'type': 'quarterly',
        'quarterly': {
            'q1': {'billing_month': 3, 'billing_day': 31},
            'q2': {'billing_month': 6, 'billing_day': 30},
            'q3': {'billing_month': 9, 'billing_day': 30},
            'q4': {'billing_month': 12, 'billing_day': 31},
        },
    }
)
 
print('\nUpdated to quarterly billing on last day of each quarter')
 
# Add a new item to the schedule
new_item = pl.BillingItem.create(
    billing_schedule_id=schedule.id,
    type='line_item',
    description='Additional Service Fee',
    start_date='2024-03-01',  # Start in the future
    line_item={'value': 25.00, 'qty': 1},
)
 
print(f'\nAdded new item: {new_item.description}')
 
# Cancel a billing schedule (set end_date to today)
today = date.today().isoformat()
 
schedule.update(
    end_date=today,
    attrs={
        'cancellation_reason': 'Customer requested cancellation',
        'cancelled_by': '[email protected]',
        'cancelled_date': today,
    },
)
 
print(f'\nSchedule cancelled, no new invoices after {today}')

Get complete schedule details including current configuration, financial totals, and billing items.

Change Billing Frequency

Update the billing frequency to match changing subscription needs.

# Change from monthly to quarterly
schedule = pl.BillingSchedule.get("bscd_abc123")
schedule.update(
    recurring_schedule={
        "type": "quarterly",
        "quarterly": {
            "q1": {"billing_month": 3, "billing_day": 31},
            "q2": {"billing_month": 6, "billing_day": 30},
            "q3": {"billing_month": 9, "billing_day": 30},
            "q4": {"billing_month": 12, "billing_day": 31}
        }
    }
)

Effect of frequency change:

• Next invoice generated on new schedule
• Previous invoices unaffected
• Billing items continue as configured
• Schedule totals maintain complete history

Update Autopay Settings

Enable or disable automatic payment collection.

Enable autopay:

schedule = pl.BillingSchedule.get("bscd_abc123")
schedule.update(
    autopay_settings={
        "allowed": True
    },
    payer={
        "account_id": "acct_customer123",
        "method_id": "pm_card_456"  # Optional: specify payment method
    }
)

Disable autopay:

schedule = pl.BillingSchedule.get("bscd_abc123")
schedule.update(
    autopay_settings={
        "allowed": False
    }
)

Cancel Schedule

Stop future invoice generation by setting an end date.

# Cancel immediately (no future invoices)
from datetime import date
 
today = date.today().isoformat()
schedule = pl.BillingSchedule.get("bscd_abc123")
schedule.update(
    end_date=today,
    attrs={
        "cancellation_reason": "Customer requested cancellation",
        "cancelled_by": "[email protected]",
        "cancelled_date": today
    }
)

Cancellation effects:

• No new invoices generated after end_date
• Existing unpaid invoices remain due
• Schedule remains accessible for history
• Financial totals reflect all historical activity

Scheduled cancellation:

# Cancel at end of current billing period
schedule = pl.BillingSchedule.get("bscd_abc123")
schedule.update(
    end_date="2024-12-31",  # Last day of service
    attrs={
        "cancellation_reason": "Contract end",
        "cancellation_type": "scheduled"
    }
)

Pause Schedule

Temporarily stop invoice generation without cancelling the schedule.

Pause by setting near-future end date:

from datetime import date
 
schedule = pl.BillingSchedule.get("bscd_abc123")
schedule.update(
    end_date="2024-03-31",  # Pause until this date
    attrs={
        "pause_reason": "Customer requested service pause",
        "paused_date": date.today().isoformat()
    }
)

Resume by clearing end date:

from datetime import date
 
schedule = pl.BillingSchedule.get("bscd_abc123")
schedule.update(
    end_date=None,  # Resume indefinite billing
    attrs={
        "resumed_date": date.today().isoformat(),
        "resumed_by": "[email protected]"
    }
)

Resume by extending end date:

schedule = pl.BillingSchedule.get("bscd_abc123")
schedule.update(
    end_date="2025-12-31",  # Extend for another year
    attrs={
        "extension_reason": "Contract renewal"
    }
)

Pause use cases:

• Seasonal businesses (pause during off-season)
• Customer requests temporary service hold
• Payment dispute resolution
• Service interruption or maintenance
• Trial extensions

Managing Billing Items

Add, update, or remove items that appear on generated invoices.

Add Item to Schedule

Add new charges that will appear on future invoices.

• Add Immediately
• Future Start Date

import payload
pl = payload.Session('secret_key_3bW9...', api_version='v2')
 
# Add item to schedule - appears on next invoice
 
schedule_id = 'bscd_abc123'
 
new_item = pl.BillingItem.create(
    billing_schedule_id=schedule_id,
    type='line_item',
    description='Premium Support',
    line_item={
        'value': 25.00,
        'qty': 1
    }
)
 
print(f'Added item: {new_item.description}')
print(f'Item ID: {new_item.id}')
print('Will appear on next invoice')

import payload
pl = payload.Session('secret_key_3bW9...', api_version='v2')
 
# Add item with future start date
 
schedule_id = 'bscd_abc123'
 
future_item = pl.BillingItem.create(
    billing_schedule_id=schedule_id,
    type='line_item',
    description='Seasonal Feature Access',
    start_date='2024-06-01',  # Starts June 1st
    end_date='2024-08-31',    # Ends August 31st
    line_item={
        'value': 15.00,
        'qty': 1
    }
)
 
print(f'Added seasonal item: {future_item.description}')
print(f'Active from {future_item.start_date} to {future_item.end_date}')
print('Will not appear until start_date')

What happens when adding items:

• Item appears on all invoices generated after start_date
• If start_date not specified, appears on next invoice
• Item stops appearing after end_date (if specified)
• Schedule totals update to include new recurring charges

Update Item Pricing

Modify pricing for existing billing items.

• Change Price
• Change Quantity

import payload
 
pl = payload.Session('secret_key_3bW9...', api_version='v2')
 
# Update item price
 
item_id = 'bcrg_abc123'
 
updated = pl.BillingItem.get(item_id)
 
 
updated.update(line_item={'value': 59.99, 'qty': 1})  # New price
 
print(f'Updated price to ${updated.line_item}')
print('New price applies to next invoice')
print('Previous invoices remain unchanged')

import payload
 
pl = payload.Session('secret_key_3bW9...', api_version='v2')
 
# Update item quantity (e.g., user count)
 
item_id = 'bcrg_userlic'
 
updated = pl.BillingItem.get(item_id)
 
 
updated.update(
    description='User Licenses (10 users)',
    line_item={'value': 10.00, 'qty': 10},  # Per user  # 10 users = $100.00
)
 
print(f'Updated quantity to {updated.line_item['qty']} users')
print(f'Total: ${updated.line_item['total']}')
print('Change applies to next invoice')

Price change effects:

• New price applies to next invoice
• Previously generated invoices unchanged
• Schedule recurring_amount updates automatically
• No proration for current billing period

Remove Item from Schedule

Stop charging for specific items on future invoices.

• Set End Date
• Delete Immediately

import payload
 
pl = payload.Session('secret_key_3bW9...', api_version='v2')
 
# Remove item by setting end date (recommended)
 
item_id = 'bcrg_abc123'
 
updated = pl.BillingItem.get(item_id)
 
 
updated.update(end_date='2024-12-31')  # Last invoice to include this item
 
print(f'Item will stop appearing after {updated.end_date}')
print('Item remains in schedule history')
print('Good for scheduled removals and audit trail')

import payload
 
pl = payload.Session('secret_key_3bW9...', api_version='v2')
 
# Delete item immediately
 
item_id = 'bcrg_xyz789'
 
item = pl.BillingItem.get(item_id)
item.delete()
 
print(f'Item {item_id} deleted immediately')
print('Will not appear on any future invoices')
print('Use for immediate removal or error correction')

When to use end_date vs delete:

• Use end_date for scheduled removal (end of contract, promotion expiry)
• Use end_date to maintain item in schedule history
• Use delete for immediate removal (customer downgrade, error correction)
• Use delete for items never yet invoiced

Time-Limited Items

Add temporary charges for promotions, trials, or seasonal features.

• Promotional Discount
• Trial Period

import payload
pl = payload.Session('secret_key_3bW9...', api_version='v2')
 
# Add limited-time promotional discount
 
schedule_id = 'bscd_abc123'
 
promo_discount = pl.BillingItem.create(
    billing_schedule_id=schedule_id,
    type='line_item',
    description='Holiday Promotion - 20% Off',
    start_date='2024-11-01',
    end_date='2024-12-31',
    line_item={
        'value': -9.99,  # Negative for discount
        'qty': 1
    }
)
 
print(f'Promotional discount added: {promo_discount.description}')
print(f'Active from {promo_discount.start_date} to {promo_discount.end_date}')
print('Automatically expires without manual removal')

import payload
pl = payload.Session('secret_key_3bW9...', api_version='v2')
 
# Add trial period pricing
 
schedule_id = 'bscd_abc123'
 
trial_discount = pl.BillingItem.create(
    billing_schedule_id=schedule_id,
    type='line_item',
    description='Trial Period Discount',
    start_date='2024-01-01',
    end_date='2024-03-31',
    line_item={
        'value': -25.00,  # $25 off during trial
        'qty': 1
    }
)
 
print(f'Trial discount added: {trial_discount.description}')
print('First 3 months at reduced rate')
print('Automatically ends after trial period')

Schema Reference

Fields relevant to billing schedule updates:

BillingSchedule Update Fields

BillingItem Update Fields

Next Steps

Continue building your recurring billing workflow with invoice and payment management

Manage Invoices

Track invoice lifecycle with Invoice Statuses to understand generated invoice progression from unpaid to paid, attach supporting documents with Invoice Attachments for receipts and documentation, and create one-time charges with Creating Invoices for non-recurring billing needs.

Process Payments

Configure automatic payment collection 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.

Analyze Performance

Monitor billing events with Webhook Events to receive real-time schedule and invoice generation notifications, track subscription metrics with Reporting Overview for MRR, ARR, and churn analysis, and analyze revenue data with Transaction Reports for detailed financial reporting.

Related articles

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