Tech dive into the ChargeOver REST API for metered / usage billing

Share article

In this article:

SaaS businesses and utility companies are typical users of metered billing. Metered billing has significant advantages for businesses and their customers. Customers can economize by paying only for what they need. At the same time, SaaS and other businesses can compete in crowded marketplaces with flexible offerings that are lower in cost and pay-as-you-go.

Often developers and business owners ask if ChargeOver supports metered billing (also known as usage-based billing or variable billing). The answer? A big YES! ChargeOver absolutely offers metered billing, and it's pretty slick.

If you're a techie and need an automated way to charge per gigabyte, per minute, per user, or per hour, this article is for you.

Since you already know what you need, let's just skip to the good part: the making things work part.

What are we going to build?

We're going to build a simple but powerful integration between an external service and ChargeOver for metered billing.

The external application could be your website or application. It will send metered data to ChargeOver via the ChargeOver REST API. Here for an example we'll use the minutes spent on the phone for a voice-over-IP phone (VOIP) service.

ChargeOver will then generate invoices based on the metered data. The VOIP in our example charges customers $.05/minute for plus a $10 monthly fee.

In this article, we're focusing on the REST API, but you can send metered data to ChargeOver through usage URLs and even spreadsheets. (Look for another post coming up where we'll walk through usage URLs.)

Let's get started!

First, we need to set up the VoIP Service in ChargeOver. In ChargeOver, go to Configuration, and then to Services & Products on the left-side menu. You're going to need to set a few things up so that ChargeOver knows what to charge ($0.05 per minute) and to charge based on the metered usage data we're going to send in via the REST API. You can name the service whatever you'd like, but make sure you turn on the usage data/metered billing option.

We're going to use Unit Pricing for our example -- Unit Pricing lets us (optionally) charge a base fee (i.e. even if they don't use any minutes, we're still going to charge them a base flat fee) on top of a per-unit price ($0.05 per minute). If we wanted to, Unit Pricing also allows us to use tiers based on the amount of usage -- for example, we could charge $0.05 per minute for the first 100 minutes, and then $0.04 per minute for the next 500 minutes, etc.  We'll keep in simple for this example and just use a single tier at $0.05 per minute.

You only have to configure this VoIP service once -- then you can re-use this for every one of your customers. Let's set up the customer and the recurring package/subscription next!

Create your Recurring Package and plop the new VoIP service you created onto the package. The recurring package is essentially a template for how to generate invoices (and recurring payments) for a customer each month (or week, or quarter, or etc. if you don't bill monthly).

The recurring package will give you a summary of what the charges are going to be.

Let's Get Techy

We grabbed our REST API credentials from the ChargeOver Configuration > API & Web Hooks menu, and are going to make our first REST API call to fetch some details about this package from the API. (Hint: Our open-source code libs on GitHub make it easy to get started with the API). Here's the endpoint we're going to hit:

GET /api/v3/package/713

You're going to get back a JSON document that looks something like this:














The key element here is the _line_itemid value (in this example, 854). This is a globally unique identifier for the particular line on the package/subscription. This is what we're going to send our metered data to. Let's send some metered data to ChargeOver -- our customer used 22 minutes on September 15:

POST /api/v3/usage




   "from":"2015-09-15 00:00:00",  

   "to":"2015-09-15 23:59:59"


Pretty straightforward, right? You'll send the _line_itemid we got from the package, a _usagevalue (the number of minutes used) and a date range (for our example, we're going to send the total minutes for a full day's worth of usage).

If you go back to ChargeOver, and click the little chart/graph icon on the package line, you'll get a pretty graph showing you the data that was submitted to ChargeOver (the example image below shows a few days worth of data).

Wait... It's that easy to automate my metered billing?!

That's right, that's it. At this point, you've successfully sent usage/metered data to ChargeOver, and ChargeOver is going to use that metered data to create an invoice automatically the next time an invoice is due for this customer. The customer will get a nicely formatted email invoice, and a copy of the invoice in PDF format, that will indicate the minutes they were billed for based on the unit pricing tiers you set up.

Here's an example of what the invoice is going to look like:

Notice the flat fee ($10) that we're charging, and then the second line item for the $0.05 per minute charge (361 minutes).

From a technical perspective, you can submit usage to ChargeOver as often or seldom as you want. Send it once per day, or many times a day, it's up to you. ChargeOver will automatically charge for the correct usage based on the invoice date and period for which the customer is being billed.

Of course, you can also customize how your PDF invoices look in ChargeOver, how often invoices are generated (i.e. you can bill monthly, quarterly, weekly, etc.) and much, much more.

Automate your metered / usage-based / variable billing today.

Start your trial now: sandbox account included! Need help? Reach out and get in touch with a real person who can help you automate and integrate today.

Get the inside scoop on recovering payments: Download the FREE eBook on maximizing your payment recovery

Subscribe for weekly emails about improving recurring billing and growing your business.

Thank you! Your submission has been received!
Oops! Something went wrong while submitting the form.

Ready to make your subscription billing easier?

Here’s a 4-min tour of how ChargeOver can decrease the time you spend on billing.

Automating your invoices starts here