Credits

📘
Credits are an abstraction over currency that allow for flexible, pay-as-you go pricing models.

Credits allow you to abstract away the unit costs of your API from customers, or allow customers to pay on-the-fly for usage of your API. Credits can be helpful in marketing materials and conversations with customers, offering non-committal pay-as-you-go options, and collecting revenue upfront.

Credit-based plans are defined in terms of credits rather than currency. Instead of defining a plan that costs "$0.10 per API request," you may instead define that plan as "1 credit per API request."

To use credit-based plans, your customers must be able to purchase credits. Those purchased credits are then used to fund credit-based plans. Customers typically pay for credits in one of three ways:

Subscription plans can be configured with a credit purchase amount
Ad-hoc credit grants can be purchased using the credit grant API
Credit overage costs are paid for any usage overages that go beyond a customer's available credit balance

🚧
Even though they are listed here in different sections, it is very common for a business to leverage subscription credit plans, ad-hoc credit grants, and credit overages at the same time.

Subscription Credit Plans

In traditional usage-based billing, customers pay for their usage in arrears, at the end of a billing cycle (read more about arrears here. Perhaps, though, you want to charge customers in advance, to generate revenue earlier in the billing cycle. Perhaps you also have an easier time marketing your product by advertising fixed upfront monthly fees.

Subscription credit plans are a way to move billing to the start of the month (rather than the end). A customer pays for their subscription upfront (in advance), purchasing a pre-configured number of credits. Those credits are then available to fund usage-based plans throughout the month.

Credits generated by subscription plans will automatically expire at the end of each billing cycle.

🚧
You must configure a credit overage cost in a given currency before defining subscription credit plans for customers configured with that currency.

Ad-hoc Credit Grants

Sometimes, instead of billing for usage in arrears, businesses prefer to offer a flexible pay-what-you-want, pay-as-you-go option, while still collecting payment before providing access to an API. If this is you, ad-hoc credit grants may be the right choice.

Ad-hoc credit grants allow you to issue new credit grants to customers at any point in their billing cycle. These ad-hoc grants are often be referred to as "top-up grants," as they allow a customer to "top-up" their credit balance in the middle of a billing cycle. Credits issued ad-hoc do not expire automatically in the same way those generated by subscription plans do.

When a chargeAmount is included in the create credit grant API, Kable will immediately charge that customer's default on-file payment method. If the charge is successful, a new credit grant will be issued. If the charge fails, the credit grant will not be issued. This is a great way to ensure your customers pay upfront for additional usage of your API.

🚧
Credit grants with a chargeAmount are therefore only supported in the Live environment for businesses with a configured payment integration and customers customers configured with a default payment method.

Credit Overage Costs

A credit overage costs is a cost, defined in currency, for any overages incurred by a customer on a credit-based plan. The easiest way to define credit overage costs is with an example, so consider the following:

Let's say that Mailman from our Quick Start example wanted to use credit-based usage plans. They may set their customers up with a package that consists of two plans:

a subscription credit plan that costs $99/month and includes 10,000 credits
a credit-based usage plan that costs 1 credit per message sent

Mailman also defines the USD credit overage cost as $0.02 per credit.

Now, let's say that one of Mailman's customers is Drivr, a ride-share app. Drivr historically sends 6,000-8,000 messages per month through Mailman. Each month Drivr pays $99, and their invoice contains a single line item:

Subscription Plan: $99, including 10,000 credits

But in August, Drivr has a busier-than-normal month, and sends 11,000 messages through Mailman. At the start of the month, they paid their $99 subscription, and throughout the month they exceeded their 10,000 credit quota for August. On their next bill, at the end of August, Drivr will see a second line item on their invoice:

Subscription Plan: $99, including 10,000 credits
USD Credit Overages: $20 (1,000 overage credits * $0.02 per overage credit)

🚧
If Mailmain also supported ad-hoc credit grants, rather than incurring credit overage costs, Drivr may have instead chosen mid-month to purchase a top-up grant of additional credits.
How you price your ad-hoc credit grants, and what flexibility you offer your customers in purchasing these grants is entirely up to you.

📘
If you're looking for variable credit overage costs based on the plans to which a customer is subscribed, check out the section on credit overages in bundles.