Create a Billing Schedule

Setup a Billing Schedule

curl "https://api.payload.com/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.

Specify Billing Frequency

Updating a Billing Frequency

curl "https://api.payload.com/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
}

Default Behavior

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

Edge Cases

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.