ChargeOver supports metered billing / usage-based billing extracted from other systems. For example:
There are two main ways to feed ChargeOver usage/meter data:
usage endpoint
Please feel free to contact us for help getting integrated.
Usage URLs are endpoints you set up to provide ChargeOver with metered usage data. ChargeOver will poll these endpoints at the time of invoicing to fetch usage data from your system.
Here are a few guidelines for best practices when using usage URLs to provie ChargeOver with usage data:
200 OK HTTP response if you were able to return usage successfully to ChargeOver
200 OK HTTP response if an error occurred on your end and you were unable to return accurate usage. Instead return a 400 Bad Request or 500 Internal Server Error or other meaningful HTTP status code to indicate that an error occurred.
For each individual line on a package, ChargeOver will send a HTTP POST request to the URL that you specify.
You are expected to return a JSON response in the following format:
{
"line_items": [
{
"usage_amount": 25
}
]
}
usage_amount property should contain the usage used for the period.
Make special note of these properties that are sent to you in the HTTP POST:
package: This is the recurring package for which we are requesting usage.
this_line_item: This is the specific line item on the recurring package for which we are requesting usage.
this_line_item.external_key: It is a good idea to store your subscription id or unique identifer in this field so that you can easily know which subscription id ChargeOver wants usage for.
this_line_item.item_name: This will tell you the type of item/product usage is being requested for.
from_datetime: This is the start of the date range usage is being requested for.
to_datetime: This is the end of the date range usage is being requested for.
security_token: This is a shared secret token you can use to validate that requests are coming from ChargeOver, and not some other source.
{
"customer": {
"superuser_id": 348,
"external_key": null,
"token": "ac4kjusp2zv1",
"company": "John Doe's Company, Ltd",
...
"superuser_name": "John Doe",
"superuser_first_name": "John",
"superuser_last_name": "Doe",
"superuser_phone": "",
"superuser_email": "johndoe@ChargeOver.com",
"superuser_token": "krwnoyuxgh43",
"superuser_username": "johndoe@ChargeOver.com",
"customer_id": 1,
},
"package": {
"terms_id": 2,
"currency_id": 1,
"external_key": null,
"token": "bmaczldxr841",
"nickname": "",
"paymethod": "inv",
"paycycle": "mon",
...
"package_id": 572,
"customer_id": 1,
"package_status_id": 2,
"package_status_name": "Current",
"package_status_str": "active-current",
"package_status_state": "a",
"line_items": [
{
"line_item_id": 573,
"item_id": 4,
"tierset_id": 11,
"external_key": null,
"nickname": "",
"descrip": "Test",
...
"item_name": "Test Usage",
"item_external_key": null,
"item_accounting_sku": null,
"item_token": "x9lq15y0vuwr",
"item_type": "service",
"item_units": "minute",
}
]
},
"this_line_item": {
"line_item_id": 573,
"item_id": 4,
"tierset_id": 11,
"external_key": null,
"nickname": "",
"descrip": "Test",
"custom_1": null,
"custom_2": null,
"custom_3": null,
"subscribe_datetime": "2015-06-15 22:54:02",
"subscribe_prorate_from_datetime": null,
"subscribe_prorate_to_datetime": null,
"cancel_datetime": null,
"expire_datetime": null,
"expire_recurs": null,
"license": "",
"item_name": "Test Usage",
"item_external_key": null,
"item_accounting_sku": null,
"item_token": "x9lq15y0vuwr",
"item_type": "service",
"item_units": "minute"
},
"from_datetime": "2015-05-15 00:00:00",
"to_datetime": "2015-06-14 23:59:59",
"security_token": "DsxhTawizIFYGlJcjQ4y1vNproPdbXqU"
}
As an alternative to usage URLs, you can also use the ChargeOver REST API to send usage / metered data to ChargeOver. View the full REST API documentation.
Make sure you send data regularly to ensure that when new invoices are generated, ChargeOver has the most up-to-date usage data. You can send data daily and ChargeOver will sum up the usage values at the end of each billing cycle automatically.
Our REST API usage endpoint can operate in two different modes:
Common scenarios for the cumulative approach:
The cumulative mode is used when you want ChargeOver to add up all of a customer's usage data for you, and charge the customer for the total sum of the usage data. For example:
ChargeOver treats usage as if it is cumulative usage by default. For the cumulative scenario, most commonly you'd send ChargeOver usage on a routine basis (e.g. every day, or every hour etc.) via a payload that looks something like this:
{
"line_item_id": 590,
"usage_value": 265.2
}
Common scenarios for the maximum value approach:
The maximum value mode is used when you want ChargeOver to use the maximum value out of all the you've sent it as the usage to charge the customer for. For example:
You can tell ChargeOver to calculate usage based on the maximum value instead of the cumulative sum. For this scenario, you'd most commonly send ChargeOver usage on a routine basis (e.g. every day, every hour, etc.) via a payload that looks something like this:
{
"line_item_id": 590,
"usage_value": 265.2,
"type": "max”
}
"type": "max" tells ChargeOver to calculate based on the maximum usage value rather than the sum of all usage.
Below are several examples of ways to send usage data to ChargeOver.
Have another scenario that would make your metered-billing easier? Reach out and contact us! We have some flexibility here!
One method of sending usage data to ChargeOver via the REST API is to name the specific line item you are sending usage data for.
line_item_id: This is the specific line item on a package that you are providing usage for. You may
also use line_item_external_key if an external_key is set for the line item.
from: This is the start of the date range for the usage.
to: This is the end of the date range for the usage.
The usage_value value should contain the usage amount of this time period.
If you know you'll only ever have exactly ONE usage-based/metered line item on a subscription, then you can simply send usage data to ChargeOver using the package_id (the subscription ID #) rather than to a specific line item.
Only use this if you are 100% sure you will always have exactly one metered line item on each subscription you are pushing usage to. If you have MORE THAN ONE metered line item on a subscription, you MUST use the previous method of supplying a line_item_id. You can have other line items, but ONLY ONE METERED one, on the subscription.
package_id: This is the specific package that you are providing usage for. There must be only one usage based line item on this package in order to use this method to supply usage data via API.
from: This is the start of the date range for the usage.
to: This is the end of the date range for the usage.
The usage_value value should contain the usage amount of this time period.
If you are using external keys and know that a customer has only one subscription that contains a specific usage-based line item on it, you can send usage data to ChargeOver using the customer.external_key and item.external_key values.
ChargeOver will search all of the specified customer's subscriptions to find the one with your item.external_key on it.
When using this method, you have to make sure you don't have multiple subscriptions for the same customer with the same item.external_key on each of them, because then it is ambiguous which subscription the usage should be applied to.
customer_external_key: This is the external key value for the customer whose subscription line item you are supplying usage for.
line_item.item_external_key: This is the external key value for the item you are supplying usage for.
from: This is the start of the date range for the usage.
to: This is the end of the date range for the usage.
The usage_value value should contain the usage amount of this time period.