Setup a Billing Schedule
curl "https://api.payload.co/billing_schedules/" \
-u secret_key_3bW9JMZtPVDOfFNzwRdfE: \
-d "start_date=2020-01-01" \
-d "end_date=2020-12-31" \
-d "recurring_frequency=monthly" \
-d "type=subscription" \
-d "processing_id=acct_3bW9JMapnT7sw7neax7ui" \
-d "charges[0][type]=option_1" \
-d "charges[0][amount]=39.99" \
-d "customer_id=inv_3bW9JMorTV1q6mXkkXUTg"
billing_schedule = pl.BillingSchedule.create(
start_date=datetime.date(2020, 1, 1),
end_date=datetime.date(2020, 12, 31),
recurring_frequency='monthly',
type='subscription',
processing_id='acct_3bW9JMapnT7sw7neax7ui',
charges=[
pl.BillingCharge(type='option_1', amount=39.99)
],
customer_id='acct_3bW9JMorTV1q6mXkkXUTg'
)
billing_schedule = Payload::BillingSchedule.create(
start_date: '2020-01-01',
end_date: '2020-12-31',
recurring_frequency: 'monthly',
type: 'subscription',
processing_id: 'acct_3bW9JMapnT7sw7neax7ui',
charges: [
Payload::BillingCharge.new(
type: 'option_1',
amount: 39.99
)
],
customer_id: 'acct_3bW9JMorTV1q6mXkkXUTg'
)
<?php
$billing_schedule = Payload\BillingSchedule::create(array(
'start_date' => '2020-01-01',
'end_date' => '2020-12-31',
'recurring_frequency' => 'monthly',
'type' => 'subscription',
'processing_id' => 'acct_3bW9JMapnT7sw7neax7ui',
'charges' => array(
new Payload\BillingCharge(array(
'type' => 'option_1',
'amount' => 39.99
))
),
'customer_id' => 'acct_3bW9JMorTV1q6mXkkXUTg'
));
?>
const billing_schedule = await pl.BillingSchedule.create({
start_date: '2020-01-01',
end_date: '2020-12-31',
recurring_frequency: 'monthly',
type: 'subscription',
processing_id : 'acct_3bW9JMapnT7sw7neax7ui',
charges: [
pl.BillingCharge({
type: 'option_1',
amount: 39.99
})
],
customer_id: 'acct_3bW9JMorTV1q6mXkkXUTg'
})
var billing_schedule = await pl.BillingSchedule.CreateAsync(new {
start_date = "2020-01-01",
end_date = "2020-12-31",
recurring_frequency = "monthly",
type = "subscription",
processing_id = "acct_3bW9JMapnT7sw7neax7ui",
charges = new[] {
new pl.BillingCharge(new {
type = "option_1",
amount = 39.99
})
},
customer_id = "acct_3bW9JMorTV1q6mXkkXUTg"
});
If you have a preset or recurring billing schedule, you can use the Billing Schedule object to create and manage advanced billing settings. You can define charges, start dates, frequencies, enable automatic billing of invoices to a customer, and more.
Invoices will be automatically generated based on your billing
schedule's recurring_frequency
, with Line Items that
correspond with the Billing Charges in your charges
array.
Updating a Billing Frequency
curl "https://api.payload.co/billing_schedules/{id}" \
-u secret_key_3bW9JMZtPVDOfFNzwRdfE: \
-X PUT \
-d recurring_frequency="bimonthly" \
-d bimonthly[first_billing_day]=1 \
-d bimonthly[second_billing_day]=15
billing_schedule.update(
recurring_frequency='annually'
annually={
'billing_month': 12,
'billing_day': 31
}
)
billing_schedule.update(
recurring_frequency: 'monthly'
)
<?php
$billing_schedule->update(array( 'recurring_frequency'=>'quarterly' ));
?>
const updated_schedule = await billing_schedule.update({
recurring_frequency: 'quarterly',
quarterly: {
q1: {
billing_month: 2,
billing_day:28
},
q2: {
billing_month: 5,
billing_day: 31
},
q3: {
billing_month: 8,
billing_day: 31
},
q4: {
billing_month: 11,
billing_day: 30
}
}
})
await billing_schedule.UpdateAsync(new { recurring_frequency = "bimonthly" });
Billing schedules can run daily
, weekly
, biweekly
(every two weeks),
bimonthly
(twice a month), monthly
, quarterly
, or annually
.
If the recurring_frequency
is set to bimonthly
, monthly
, quarterly
, or
annually
, the billing day(s) and/or month(s) can be adjusted by updating the
corresponding nested object.
Within the bimonthly
, monthly
, quarterly
, and annually
objects, the fields
are integers that represent the day(s) and/or month(s) on which billing will occur.
In the example below, billing will occur on the 12th of every month, starting with
the first 12th of the month after the start_date
, and ending with the last 12th
of the month before the end_date
.
"monthly": {
"billing_day": 12
}
Recurring billing will occur on the following days if values are not provided:
daily
: Every day beginning on the start_date
weekly
: Every seven days, beginning on the start_date
biweekly
: Every fourteen days, beginning on the start_date
Note that automatic invoice generation does not occur for partial billing periods.
bimonthly |
default value |
---|---|
first_billing_day |
The day the Billing Schedule was created, or 14 days before |
second_billing_day |
The day the Billing Schedule was created, or 14 days after |
The default values for the bimonthly billing days are set dynamically based on
the day of the month on which the Billing Schedule was created. By default they
will always be 14 days apart, the first_billing_day
will always be lower, and
the second_billing_day
will never be 29, 30, or 31.
For example, if the Billing Schedule was created on the 22nd of the month, the
first_billing_day
will be 8, and the second_billing_day
will be 22.
If the Billing Schedule was created on the 3rd of the month, the first_billing_day
will be 3, and the second_billing_day
will be 17.
monthly |
default value |
---|---|
billing_day |
The day the Billing Schedule was created |
quarterly |
default value |
---|---|
q1[billing_day] and q1[billing_month] |
1 and 1 (the 1st of January) |
q2[billing_day] and q2[billing_month] |
1 and 4 (the 1st of April) |
q3[billing_day] and q3[billing_month] |
1 and 7 (the 1st of July) |
q4[billing_day] and q4[billing_month] |
1 and 10 (the 1st of October) |
By default, quarterly billing will occur on the first day of each quarter.
annually |
default value |
---|---|
billing_day |
The day the Billing Schedule was created |
billing_month |
The month the Billing Schedule was created |
For the bimonthly
, monthly
, quarterly
, and annually
recurring frequencies,
billing can be set to occur on any day of a given month, including the 29th - 31st.
For months with fewer than 31 days, billing will occur on the last available day of that month.
This means that in April, all billing for the 30th and the 31st of the month will occur on April 30th. In February, all billing for the 28th-31st of the month will occur on the 28th.
In leap years, all billing for the 29th-31st of February will occur on February 29th.