Using 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.

Why Credits?

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.

Granting Credits

Credits can be granted through the Octane Portal or API. Customers are invoiced for the cost of credits at the time the credits are granted.


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.

Using Credits

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.

Grant IDEffective AtExpires AtAmount

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.

Voiding Credits

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.


Voiding a grant only voids unused credits

If the original grant was for $100 and the customer already used $25 in an invoice, only the remaining $75 will be voided. We generally recommend you void grants before they are used to avoid confusion.

Credit Ledger

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:

  • Grants - when credits are granted to a customer
  • Voids - when a credit grant is voided
  • Subscription deductions - when credits are deducted to pay for a bill for an active subscription
  • Expiration - when credits expire

Credit Grant Definition

Field NameDescriptionTypeRequired
customer_nameThe name of the customer receiving the grantStringRequired
amountNumber of credits to grantFloatRequired
priceTotal price paid for the credits, in cents. Defaults to $1 (100 cents) per credit if not specifiedFloatOptional
effective_atThe date at which the grant is effective. Defaults to the current time if not specifiedDatetimeOptional
expires_atThe date at which the grant expires. Grants with no expires_at will never expireDatetimeOptional
descriptionAn optional description for bookkeepingStringOptional