Invoice Review

1. Overview
2. Subscription Billable Event
3. Tracked Item Quantities Audit
4. Custom Charges and Credits
5. Running the Invoice

1 Overview

The Subscription Billable Event Hook is a special event hook with many uses. It offers the opportunity to execute logic based on a subscription's recurring invoice becoming due. This can be useful for updating tracked item quantities accurately as of the end of the billing period, or just double-checking things with your records.

Here's a pretty picture:

X----------------------------------------------------X--------...
^        ^   ^       ^   ^ ^               ^ ^       ^  ^
|        |   |       |   | |               | |       |  |
1        2   2       2   2 2               2 2       3  4

1. Subscription invoice billing period begins
   
2. Usage occurs
   
   • Update item quantity
3. Subscription invoice becomes billable (billing period ends)
   
   • Subscription Billable event hook is sent
   • Hook is received by your hook listener and processed
     • e.g., update item quantity to accurate value as of the end of the billing period
4. Subscription invoice is executed

2 Subscription Billable Event

This whole concept is based on the Subscription Billable Event. This event occurs when Cheddar's transaction engine runs across a billable invoice during the normal course of subscription transaction execution. If you have registered a listener for this event hook, Cheddar's recurring engine will send the hook instead of transacting the invoice, leaving the invoice in an "outstanding" state. This enables your hook listener to execute actions on the outstanding invoice prior to transacting.

3 Tracked Item Quantities Audit

One of the primary uses for the Subscription Billable Event is to trigger an update of Cheddar's record of the tracked item quantities for a particular customer's billing period.

A billing period in Cheddar is considered to be from one invoice billingDatetime to the next invoice billingDatetime. As such, you probably want your customers usage quantities to be accurate as of the moment of the billingDatetime. When you listen for the Subscription Billable hook, you are then able to update Cheddar's quantities of your tracked items according to your records as of the outstanding invoice billingDatetime.

You can use the Set Item Quantity API method as you normally would and include the invoicePeriod parameter. By default, the Set Item Quantity method updates the item quantity for the current open period. In the case of the audit, you want to finalize the quantity for the outstanding invoice period. Passing invoicePeriod=outstanding will cause the Set Item Quantity method to update that outstanding period.

Note: Pass in anything other than 'outstanding' or nothing at all for the invoicePeriod, and you are interacting with the current open invoice that started when the last billingDateTime passed. (See "Current vs Outstanding Invoice Period" in the API docs for further explanation.)

4 Custom Charges and Credits

You can also use the Subscription Billable event hook to trigger adding/editing/deleting custom charges and credits on the outstanding invoice.

Use the Add a Custom Charge/Credit or the Delete a Custom Charge/Credit as usual except include the invoicePeriod parameter set to outstanding to alter the outstanding invoice.

5 Running the Invoice

By default, Cheddar's recurring engine will pick up the outstanding invoice and run it automatically at least 1 hour after all Subscription Billable hooks are successfully processed. So, there is no need to run the outstanding invoice. However, if you'd like to execute the invoice immediately after your listener logic completes, you can do that. Invoices are locked during execution so there's no danger of them being run by both processes simultaneously.

Using the Run an Outstanding Invoice API Method, you can execute the outstanding invoice.

View Plans and Pricing   or   Get Started with Cheddar now →