- Subscription Billable Event
- Tracked Item Quantities Audit
- Custom Charges and Credits
- Running the Invoice
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
- Subscription invoice billing period begins
- Usage occurs
- Update item quantity
- 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
- Subscription invoice is executed
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.
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
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.)
You can also use the Subscription Billable event hook to trigger adding/editing/deleting custom charges and credits on the outstanding 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.