Create Billing Schedules

Set up recurring billing schedules with flexible frequencies and automatic invoice generation

Create billing schedules to automate recurring invoice generation for subscriptions, contracts, and periodic billing. Configure billing frequencies from daily to annually, add line items that appear on each invoice, enable autopay for automatic payment collection, and let Payload handle the rest. Billing schedules eliminate manual invoice creation and ensure consistent billing cycles.

Prerequisites

Before creating billing schedules, ensure you have:

Creating Billing Schedules

Create schedules with different frequencies based on your billing needs.

• Monthly
• Quarterly

import payload
pl = payload.Session('secret_key_3bW9...', api_version='v2')
 
# Create a monthly billing schedule
 
schedule = pl.BillingSchedule.create(
    start_date='2024-02-01',
    description='Monthly Pro Plan Subscription',
    payer={
        'account_id': 'acct_customer123'
    },
    biller={
        'account_id': 'acct_merchant456'
    },
    recurring_schedule={
        'type': 'monthly',
        'monthly': {
            'billing_day': 1  # Bill on the 1st of each month
        }
    },
    autopay_settings={
        'allowed': True  # Enable automatic payment
    },
    default_tax_rate=8.5,  # 8.5% tax
    items=[
        {
            'type': 'line_item',
            'description': 'Pro Plan - Monthly Subscription',
            'line_item': {
                'value': 49.99,
                'qty': 1
            }
        }
    ]
)
 
print(f'Billing schedule created: {schedule.id}')
print(f'Recurring amount: ${schedule.totals['recurring_amount']}')
print(f'Next billing: 1st of each month')
 
# View generated invoices
print(f'\nGenerated invoices: {len(schedule.invoices)}')
for invoice in schedule.invoices:
    print(f'  Invoice {invoice.number}: ${invoice.totals['total']} due {invoice.due_date}')

# Bill on first Monday of each month
pl.BillingSchedule.create(
    start_date="2024-01-01",
    recurring_schedule={
        "type": "monthly",
        "monthly": {
            "billing_weekday": 0,    # 0=Monday, 6=Sunday
            "billing_week": "first"  # or "last"
        }
    }
)

import payload
pl = payload.Session('secret_key_3bW9...', api_version='v2')
 
# Create a quarterly billing schedule
 
schedule = pl.BillingSchedule.create(
    start_date='2024-01-01',
    end_date='2024-12-31',  # One year term
    description='Quarterly Maintenance Contract',
    payer={
        'account_id': 'acct_customer123'
    },
    biller={
        'account_id': 'acct_merchant456'
    },
    recurring_schedule={
        'type': 'quarterly',
        'quarterly': {
            'q1': {
                'billing_month': 1,  # January
                'billing_day': 15    # 15th
            },
            'q2': {
                'billing_month': 4,  # April
                'billing_day': 15
            },
            'q3': {
                'billing_month': 7,  # July
                'billing_day': 15
            },
            'q4': {
                'billing_month': 10,  # October
                'billing_day': 15
            }
        }
    },
    autopay_settings={
        'allowed': True
    },
    items=[
        {
            'type': 'line_item',
            'description': 'Quarterly Maintenance Fee',
            'line_item': {
                'value': 500.00,
                'qty': 1
            }
        },
        {
            'type': 'line_item',
            'description': 'Support & Updates',
            'line_item': {
                'value': 250.00,
                'qty': 1
            }
        }
    ]
)
 
print(f'Quarterly billing schedule created: {schedule.id}')
print(f'Recurring amount: ${schedule.totals['recurring_amount']}')
print('Billing dates: Jan 15, Apr 15, Jul 15, Oct 15')
 
# View invoices for the year
print(f'\nTotal invoices for term: {len(schedule.invoices)}')
for invoice in schedule.invoices:
    print(f'  {invoice.due_date}: ${invoice.totals['total']}')

What happens when creating a schedule:

1. Billing schedule is created with specified frequency
2. First invoice is generated on or after start_date
3. Subsequent invoices auto-generate on scheduled billing days
4. Each invoice includes all active billing items
5. If autopay enabled, payments processed automatically on due date
6. Schedule tracks totals across all generated invoices

Billing Frequency Configuration

Configure different billing frequencies for various subscription models.

Daily Billing

Invoice generated every day starting from start_date:

pl.BillingSchedule.create(
    start_date="2024-01-01",
    recurring_schedule={
        "type": "daily"
        # No additional configuration needed
    },
    # ... payer, biller, items
)

Use cases: Daily rentals, per-day services, usage-based billing

Weekly Billing

Invoice every 7 days on the same day of week as start_date:

recurring_schedule: {
  type: "weekly"
  // Bills on same weekday as start_date
}

Use cases: Weekly subscriptions, recurring weekly services

Biweekly Billing

Invoice every 14 days starting from start_date:

recurring_schedule: {
  type: "biweekly"
  // Bills every two weeks from start_date
}

Use cases: Bi-weekly payments, payroll-aligned billing

Bimonthly Billing

Invoice twice per month on specified days:

recurring_schedule: {
    type: "bimonthly",
    bimonthly: {
        first_billing_day: 1,   // 1st of month
        second_billing_day: 15  // 15th of month
    }
}

Use cases: Semi-monthly billing, twice-per-month services

Monthly Billing

Invoice once per month on a specific day or weekday:

// Date-based: Bill on 1st of each month
recurring_schedule: {
    type: "monthly",
    monthly: {
        billing_day: 1  // 1-31
    }
}
 
// Weekday-based: Bill on last Friday
recurring_schedule: {
    type: "monthly",
    monthly: {
        billing_weekday: 4,      // 0=Mon, 4=Fri
        billing_week: "last"     // "first" or "last"
    }
}

Use cases: Monthly subscriptions, monthly membership fees

Quarterly Billing

Invoice once per quarter with specific dates for each quarter:

recurring_schedule: {
    type: "quarterly",
    quarterly: {
        q1: {
            billing_month: 1,  // January
            billing_day: 31    // 31st
        },
        q2: {
            billing_month: 4,  // April
            billing_day: 30    // 30th
        },
        q3: {
            billing_month: 7,  // July
            billing_day: 31    // 31st
        },
        q4: {
            billing_month: 10,  // October
            billing_day: 31     // 31st
        }
    }
}

Use cases: Quarterly maintenance, seasonal billing, quarterly memberships

Annual Billing

Invoice once per year on a specific month and day:

recurring_schedule: {
    type: "annually",
    annually: {
        billing_month: 1,  // January (1-12)
        billing_day: 1     // 1st (1-31)
    }
}

Use cases: Annual subscriptions, yearly licenses, annual memberships

Adding Billing Items

Define the charges that appear on each generated invoice.

Billing Item Configuration

• Basic
• Multiple Items
• Percentage-Based
• Time-Limited
• Item Groups

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

items: [
  {
    type: "line_item",
    description: "Base Platform Fee",
    line_item: {
      value: 29.99,
      qty: 1
    }
  },
  {
    type: "line_item",
    description: "Premium Support",
    line_item: {
      value: 20.0,
      qty: 1
    }
  },
  {
    type: "line_item",
    description: "Additional Users",
    line_item: {
      value: 10.0, // Per user
      qty: 5 // 5 users = $50.00
    }
  }
]

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

{
    type: "line_item",
    description: "Promotional Discount",
    start_date: "2024-01-01",  // Starts appearing on this date
    end_date: "2024-03-31",    // Stops appearing after this date
    line_item: {
        value: -10.00,  // Negative for discount
        qty: 1
    }
}

items: [
  {
    type: "item_group",
    description: "Core Services",
    item_group: {
      items: [
        {
          type: "line_item",
          description: "Platform Access",
          line_item: { value: 29.99, qty: 1 }
        },
        {
          type: "line_item",
          description: "API Access",
          line_item: { value: 15.0, qty: 1 }
        }
      ]
    }
  },
  {
    type: "item_group",
    description: "Add-Ons",
    item_group: {
      items: [
        {
          type: "line_item",
          description: "Priority Support",
          line_item: { value: 25.0, qty: 1 }
        }
      ]
    }
  }
]

Configuring Autopay

Enable automatic payment collection when invoices are generated.

Enable Autopay

pl.BillingSchedule.create(
    start_date="2024-01-01",
    autopay_settings={
        "allowed": True  # Enable automatic payment (default)
    },
    payer={
        "account_id": "acct_customer123",
        "method_id": "pm_card_456"  # Optional: specific payment method
    },
    # ... rest of configuration
)

Autopay behavior:

• Invoices automatically charged on due_date
• Requires payer to have valid payment method
• Failed payments leave invoice unpaid for retry/manual payment
• Successful payments transition invoice directly to paid status

Disable Autopay

autopay_settings: {
  allowed: false // Require manual payment
}

When to disable:

• Customer prefers manual payments
• Payment arrangements require approval
• Testing or development environments
• Invoice review before payment

Additional Configuration

Fine-tune your billing schedule with additional settings.

Tax Configuration

Apply tax to all invoices generated from the schedule:

pl.BillingSchedule.create(
    default_tax_rate=8.5,  # 8.5% tax rate
    # ... rest of configuration
)

Tax is automatically calculated and applied to taxable line items on each generated invoice.

Schedule Duration

Indefinite billing:

{
    start_date: "2024-01-01",
    end_date: null  // or omit - continues indefinitely
}

Fixed-term billing:

{
    start_date: "2024-01-01",
    end_date: "2024-12-31"  // Stops after this date
}

Use cases for end_date:

• Fixed-term contracts (1 year, 6 months, etc.)
• Trial periods with defined end
• Seasonal services
• Project-based billing

Descriptive Information

Add context to help identify and organize schedules:

{
    description: "Enterprise Plan - Annual Contract",
    attrs: {
        contract_id: "CNT-2024-001",
        sales_rep: "[email protected]",
        customer_segment: "enterprise",
        renewal_date: "2025-01-01"
    }
}

Schema Reference

Fields relevant to billing schedule creation:

BillingSchedule Creation Fields

BillingItem Creation Fields

Next Steps

Manage your billing schedules and automate payment workflows

Manage Billing Schedules

Modify and maintain schedules with Update Billing Schedules to change frequencies and billing items, track invoice lifecycle with Invoice Statuses to monitor generated invoices and payment status, and attach supporting documents with Invoice Attachments for receipts and documentation.

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.

Monitor and Analyze

Automate workflows with Webhook Events to receive real-time invoice generation notifications, track subscription metrics with Reporting Overview for MRR, ARR, and churn analysis, and analyze payment data with Transaction Reports for detailed financial reporting.

Related articles

• Billing Schedules Overview - Understand billing schedule concepts
• Update Billing Schedules - Manage schedule lifecycle
• Automatic Payments - Configure autopay settings
• Creating Invoices - Understand invoice structure
• Invoice Statuses - Track invoice lifecycle
• Billing Schedules API Reference - Complete API documentation