Credits

Credits allow you to give your customers a balance that can be drawn down from when paying for a subscription. Octane supports granting credits in dollar amounts, drawing down from existing balances, and tracking customer balances.

Credits are a useful tool for adding a measure of predictability to consumption-based billing. Credit-based pricing models are useful for businesses with consumption-based pricing because they can capture revenue for their customers’ usage upfront. Credits can also be given out for free or at a discounted rate as a way to incentivize use of a product.

Credits can be created through the Octane Portal or API. When credit grants are created, an invoice is automatically generated for the cost of credits. By default, the credits are granted immediately (i.e., added to the customer's ledger balance) and the invoice is issued and paid according to the normal billing settings. You can change this behavior using two parameters grant_immediately and charge_immediately. When grate_immediately = False the credit grant and corresponding invoice will be generated, but the credits will not be added to the ledger until the invoice is paid or the credit grant is explicitly granted. This parameter is ignored if charge_immediately = True. In that case, Octane will create the credit grant and corresponding invoice and immediately try to charge the customer. The credits are only added to the ledger (and in turn the customer's balance) if payment is successful.

There is an important distinction between the amount and cost - the amount is the number of dollars to add to the customer’s credit balance whereas the price reflects how much the customer must pay for them. For example, you might want to make $100 of credits available to your customer for a discounted cost of $80.

You can also set an expiration date on a credit grant. Those credits will automatically expire when the expiration date is reached and will no longer be available to use by the customer. Credits with no expiration set will be available forever.



Credits are automatically deducted when invoicing occurs and will appear on the invoice as a negative line item. If a customer has an outstanding balance at the end of a billing cycle, any available credits will be applied to the balance before the final invoice is generated.



In this invoice, the customer initially owes $8000 from the base rate and usage. They have $5000 in available credits so their final bill comes out to $3000.

Credits are used in priority of expiration, with those expiring soonest having higher priority. If two grants have the same expiration date, the credits granted first will be used first.

Suppose we have the three credit grants above. Credits from grant 3 will be used first because it has the earliest expiration date; grant 1 is used next because it has the same expiration date as grant 2 but was granted earlier.

A list of all credits-related transactions is available through the credit ledger. The ledger provides a full audit log for the current credit balance for a customer. In order to keep a thorough log the ledger is append-only, meaning a transaction can never be deleted. For example, if you create a credit grant and void it immediately after, there will always be two entries reflecting those changes even though there is no net change to the overall credit balance. Transactions included in the ledger are:



Octane also allows you to void credits. This may be useful if you’ve granted credits erroneously or need to manually expire a grant. For example, in the process of giving a customer a one-time sign-on bonus of $100, you might have accidentally created two credit grants for $100 each. You can void one of those grants to make it unavailable.

If a credit grant was not immediately granted (i.e., added to the ledger) and it's corresponding invoice has not yet been paid, then voiding that credit grant will also void it's corresponding invoice.