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 periodically 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"
}The ChargeOver REST API allows you to send metered usage data to ChargeOver. View the full REST API documentation.
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.
As an alternative to usage URLs, you can also use the ChargeOver REST API to send usage / metered data to ChargeOver.
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.
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.
View the full REST API documentation.