Billing Schedule Schema
Recurring payment arrangements with scheduling patterns and autopay settings
The Billing Schedule schema defines the structure and properties of billing schedule objects in the Payload API. Billing schedules represent recurring payment arrangements between billers and payers, supporting complex scheduling patterns, autopay settings, and comprehensive billing management.
Billing Schedule Object Properties
Complete reference for all properties available in the Billing Schedule schema
attrsobject
Custom attributes for extending the resource with additional key-value pairs. Maximum length is 255 characters when serialized.
autopay_settingsobject
Configuration for automatic payment behavior on this billing schedule. Controls whether invoices generated from this schedule will automatically charge the payer's payment method, or if manual payment is required. Essential for subscription and recurring billing scenarios.
allowedboolean
Controls whether automatic payments are allowed for this billing schedule. When set to true, invoices will be automatically charged to the payer's payment method when due. When false, invoices must be paid manually. This provides control over whether the payer has opted into autopay for recurring billing.
billerobject
Information about the merchant or service provider who will receive payments from this billing schedule. Includes the biller account and optionally the specific payment method for receiving funds. The biller issues invoices and receives payments from the payer.
accountAccountobject
The expanded biller account object. When included, this provides full account details for the merchant or service provider who will receive payments from this billing schedule.
Visibility: explicit
account_id ID of Accountstring
The unique identifier of the processing account that will receive payments from this billing schedule. This is the merchant or service provider being paid. If not specified, the system will attempt to select an applicable biller account automatically. Required if biller account is not provided inline. (ID prefix: acct)
Pattern:
^acct_[A-Za-z0-9]+$Required if:
biller[account]=nullmethodPaymentMethodobject
The expanded payment method object for funding. When included, this shows where the funds from this billing schedule will be deposited (the merchant's bank account or payment destination).
Visibility: explicit
method_id ID of PaymentMethodstring
The unique identifier of the payment method where funds will be deposited. If specified, payments from this schedule will be sent to this payment method. If not set, the biller account's default funding method will be used. Must belong to the biller account. (ID prefix: pm)
Pattern:
^pm_[A-Za-z0-9]+$created_atstring (date-time)Read-only
Timestamp when the resource was created. Automatically set by the system and immutable.
default_tax_ratenumber (double)
The default tax rate (as a percentage) to apply to taxable items on invoices generated from this billing schedule. For example, 8.5 represents an 8.5% tax rate. This rate is applied automatically to line items unless overridden at the item level. Used for calculating the tax portion of invoice totals.
descriptionstring
Optional text description of this billing schedule. Use this to provide context about what the schedule is for, such as "Monthly subscription for Premium Plan" or "Quarterly maintenance billing". Helpful for identifying and organizing billing schedules, especially when managing multiple schedules for a customer.
Max length: 128
end_datestring (date)
The date when this billing schedule expires and stops generating invoices. After this date, no new invoices will be created automatically. Leave empty for indefinite billing schedules. Use this to limit billing to a specific period, such as for fixed-term contracts or trial periods.
idstringRead-only
Unique identifier for the resource. Automatically generated upon creation and cannot be modified. (ID prefix: bscd)
Pattern:
^bscd_[A-Za-z0-9]+$invoicesInvoicearray
Collection of all invoices that have been generated from this billing schedule. Each invoice represents a billing period. Expanded by default to show all related invoices.
itemsBillingItemarray
No description
modified_atstring (date-time)Read-only
Timestamp when the resource was last modified. Automatically updated whenever any field changes.
objectenum[string]Read-only
String representing the object type for this resource.
Values:
billing_schedulepayerobject
Information about the customer who will be charged according to this billing schedule. Includes the payer account and optionally the specific payment method to use for autopay. The payer receives invoices and is responsible for payment.
accountAccountobject
The expanded payer account object. When included, this provides full account details for the customer who will be charged according to this billing schedule.
Visibility: explicit
account_id ID of Accountstring
The unique identifier of the account that will be charged for this billing schedule. This is the payer who will receive invoices and from whom payments will be collected. Required if payer account is not provided inline. (ID prefix: acct)
Pattern:
^acct_[A-Za-z0-9]+$Required if:
payer[account]=nullmethodPaymentMethodobject
The expanded payment method object for autopay. When included, this shows the specific payment method (card, bank account, etc.) that will be charged automatically if autopay is enabled.
Visibility: explicit
method_id ID of PaymentMethodstring
The unique identifier of the payment method to use for automatic payments. If specified, this payment method will be charged when autopay is enabled. If not set, the account's default payment method will be used. Must belong to the payer account. (ID prefix: pm)
Pattern:
^pm_[A-Za-z0-9]+$recurring_scheduleobject
Defines when and how often invoices are automatically generated from this billing schedule. The type determines the billing frequency, and additional fields specify the exact timing (day of month, day of week, etc.) based on the chosen frequency. Essential for subscription and recurring payment scenarios. Frequencies like daily, weekly, and biweekly use simple intervals, while monthly, quarterly, and annually allow precise date control.
annuallyobject
Configuration for annual billing. Specifies the exact month and day each year when the invoice will be generated (e.g., January 1 or December 31). Required when type is "annually". Hidden for other billing frequencies.
billing_dayenum[integer (int64)]
The day of the month (1-31) on which billing will occur each year. For example, if set to 15, invoices will be generated on the 15th of the specified billing_month. If the day exceeds the days in the selected month (e.g., 31st in February), billing occurs on the last day of that month. Required for annual billing.
Values:
1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31billing_monthenum[integer (int64)]
The month of the year (1-12) on which billing will occur, where 1=January, 2=February, etc. Combined with billing_day to specify the exact date each year when invoices will be generated (e.g., January 1, December 31). Required for annual billing.
Values:
1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12bimonthlyobject
Configuration for bimonthly billing. Specifies the two days of each month on which invoices will be generated (e.g., 1st and 15th). Required when type is "bimonthly". Hidden for other billing frequencies.
first_billing_dayenum[integer (int64)]
The first day of the month (1-31) on which billing will occur for bimonthly schedules. For example, if set to 1, invoices will be generated on the 1st of each month. Must be different from second_billing_day. If the day exceeds the days in a month (e.g., 31st in February), billing occurs on the last day of that month. Required for bimonthly billing.
Values:
1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31second_billing_dayenum[integer (int64)]
The second day of the month (1-31) on which billing will occur for bimonthly schedules. For example, if set to 15, invoices will be generated on the 15th of each month. Must be different from first_billing_day. If the day exceeds the days in a month, billing occurs on the last day of that month. Required for bimonthly billing.
Values:
1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31monthlyobject
Configuration for monthly billing. Specifies the day of the month, or day of the week, on which invoices will be generated each month (e.g., 1st of the month, or last Friday). Required when type is "monthly". Hidden for other billing frequencies.
billing_dayenum[integer (int64)]
The specific day of the month (1-31) on which billing will occur for monthly schedules. For example, if set to 1, invoices will be generated on the 1st of each month. If the day exceeds the days in a month (e.g., 31st in February), billing occurs on the last day of that month. Use this for date-based monthly billing. Mutually exclusive with billing_weekday and billing_week (use one or the other, not both).
Values:
1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31billing_weekenum[string]
Specifies which occurrence of the billing_weekday to use: "first" (first occurrence in the month) or "last" (last occurrence in the month). For example, billing_weekday=0 (Monday) and billing_week="first" means billing occurs on the first Monday of each month. Must be used with billing_weekday. Not applicable when using billing_day.
Values:
first, lastbilling_weekdayenum[integer (int64)]
The day of the week (0-6) on which billing will occur for monthly schedules, where 0 is Monday and 6 is Sunday. Used in combination with billing_week to specify patterns like "first Monday" or "last Friday" of each month. Use this for weekday-based monthly billing. Mutually exclusive with billing_day.
Values:
0, 1, 2, 3, 4, 5, 6quarterlyobject
Configuration for quarterly billing. Specifies the exact month and day within each quarter when invoices will be generated (e.g., January 15, April 15, July 15, October 15). Required when type is "quarterly". Hidden for other billing frequencies.
q1object
Billing schedule for the first quarter (January-March). Specifies the exact month and day.
billing_dayenum[integer (int64)]
The day of the month (1-31) on which billing will occur in Q1. If the day exceeds the days in the selected month, billing occurs on the last day of that month.
Values:
1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31billing_monthenum[integer (int64)]
The month within Q1 (1-3) on which billing will occur, where 1=January, 2=February, 3=March. Determines which month of the first quarter to generate invoices.
Values:
1, 2, 3q2object
Billing schedule for the second quarter (April-June). Specifies the exact month and day.
billing_dayenum[integer (int64)]
The day of the month (1-31) on which billing will occur in Q2. If the day exceeds the days in the selected month, billing occurs on the last day of that month.
Values:
1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31billing_monthenum[integer (int64)]
The month within Q2 (4-6) on which billing will occur, where 4=April, 5=May, 6=June. Determines which month of the second quarter to generate invoices.
Values:
4, 5, 6q3object
Billing schedule for the third quarter (July-September). Specifies the exact month and day.
billing_dayenum[integer (int64)]
The day of the month (1-31) on which billing will occur in Q3. If the day exceeds the days in the selected month, billing occurs on the last day of that month.
Values:
1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31billing_monthenum[integer (int64)]
The month within Q3 (7-9) on which billing will occur, where 7=July, 8=August, 9=September. Determines which month of the third quarter to generate invoices.
Values:
7, 8, 9q4object
Billing schedule for the fourth quarter (October-December). Specifies the exact month and day.
billing_dayenum[integer (int64)]
The day of the month (1-31) on which billing will occur in Q4. If the day exceeds the days in the selected month, billing occurs on the last day of that month.
Values:
1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31billing_monthenum[integer (int64)]
The month within Q4 (10-12) on which billing will occur, where 10=October, 11=November, 12=December. Determines which month of the fourth quarter to generate invoices.
Values:
10, 11, 12typeenum[string]
The frequency at which invoices will be generated and the payer will be billed. Possible values: "daily" (every day), "weekly" (every week), "biweekly" (every two weeks), "bimonthly" (twice per month), "monthly" (once per month), "quarterly" (once per quarter), or "annually" (once per year). Determines which additional scheduling fields are required.
Values:
daily, weekly, biweekly, bimonthly, monthly, quarterly, annuallystart_datestring (date)
The date when this billing schedule becomes active and begins generating invoices. Invoices will not be created before this date. For recurring schedules, this determines when the first billing cycle starts. Use this to schedule billing to begin at a future date or to align with contract start dates.
totalsobject
Financial summary of this billing schedule, including total amounts due, paid, and outstanding. All fields are read-only and automatically calculated based on the invoices and payments associated with this schedule. Provides a quick overview of the billing schedule's financial status and payment history.
balance_duenumber (double)Read-only
The remaining unpaid balance across all invoices from this billing schedule (total - paid). Read-only field that represents the outstanding amount the payer still owes. When this reaches zero, all invoices have been fully paid.
paidnumber (double)Read-only
The total amount that has been successfully paid across all invoices from this billing schedule. Read-only field that updates as payments are received. Use this to track total revenue collected from this schedule.
recurring_amountnumber (double)Read-only
The amount that will be charged on each recurring billing cycle. This is the sum of all recurring line items and represents the expected charge for each billing period. Read-only field useful for understanding the periodic cost of this subscription or recurring billing arrangement.
totalnumber (double)Read-only
The total amount due across all invoices generated from this billing schedule. This is the sum of all charges, including tax. Read-only field that updates as invoices are generated. Represents the lifetime billing amount for this schedule.