Create Billing Runs

An ad hoc bill run lets you create a bill run for a specific and usually one-time purpose. Invoices or credit memos are generated from the bill run depending on the changes made to the subscriptions. You can use the Create a bill run operation to create an ad hoc bill run.

To create a bill run, you must specify the following required fields:

  • invoice_date : the date displayed on the billing document.
  • target_date : all unbilled items before this date will be included in the bill run.

Suppose that a batch of your customers (Batch1) subscribed to your delivery service for 1 year, and you have posted the 1 year’s invoices to them. However, on April 10th, some customers canceled their recurring and one-time subscriptions starting from July 1st. In this case, the target_date should be specified as a date on or later than 2023-07-01, and the invoice date can be specified as 2023-04-10.

curl --request POST \
  --url \
  --header 'Authorization: Bearer 9ebfa50a12ef4d77b3de8c2c17923250' \
  --header 'Content-Type: application/json' \
  --data '{
        	"invoice_date": "2023-04-10",
            "target_date": "2023-07-01",
            "batches": "Batch1",
            "charges_excluded": "Usage"

If the bill run request succeeds, you will get the following 201 Created response:

	"id": "8ad094b987554ccd018755d23115741f",
	"updated_by_id": "8ad09bce80507dab0180688bdabc20cb",
	"updated_time": "2023-04-06T02:07:31-07:00",
	"created_by_id": "8ad09bce80507dab0180688bdabc20cb",
	"created_time": "2023-04-06T02:07:31-07:00",
	"custom_fields": {},
	"custom_objects": {},
	"account_id": "",
	"email": false,
	"post": false,
	"renew": false,
	"day_of_month": "AllBillCycleDays",
	"bill_run_number": "BR-00000130",
	"bill_run_time": "",
	"invoice_date": "2023-04-10",
	"target_date": "2023-07-01",
	"state": "pending",
	"batches": "Batch1",
	"charges_excluded": "Usage",
	"email_zero_amount_invoices": true,
	"invoices_sent": false,
	"last_invoice_sent_time": "",
	"accounts_processed": 0,
	"invoices_generated": 0,
	"credit_memos_generated": 0