Usage/Metered Billing

ChargeOver supports metered billing / usage-based billing extracted from other systems. For example:

  • Charge for megabytes of data used (useful for ISPs, CDNs, mobile data, or other types of data providers)
  • Charge for minutes or hours used (useful for VoIP or answering service providers)
  • Charge for SMS text messages sent (useful for monitoring services, mobile data, or other cell-enabled providers)

There are two main ways to feed ChargeOver usage/meter data:

  1. REST API usage endpoint
  2. Usage URLs

Please feel free to contact us for help getting integrated.

Usage URLs

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.

Usage URL Example

Usage URL Example

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
    }
  ]
}

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

Usage URL Example

JSON Request

{
  "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"
}

JSON Response

{
  "line_items": [
    {
      "usage_amount": 25
    }
  ]
}

REST API Usage

The ChargeOver REST API allows you to send metered usage data to ChargeOver. View the full REST API documentation.

Cumulative vs. Maximum Value Settings

Our REST API usage endpoint can operate in two different modes:

  • Cumulative - Have ChargeOver add up all the usage data you send, and use the total sum of this data as the usage to bill the customer for.
  • Maximum value - You send usage data to ChargeOver routinely, and the customer should be charged for the maximum value within that data.

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:

  • A customer uses bandwidth every day, and you want to bill them at the end of the month for the total bandwidth they used.
  • The customer talks on their phone for a variable number of minutes every day, and you want to bill them for the total # of minutes they talked at the end of the month.

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:

  • The customer uses gigabytes of memory, and you want to bill the customer for the maximum amount of memory used during the month (e.g. if they used 15gb of data on the 15th, and then deleted all of the files later, they would still get charged for that 15gb of data they used at one point during the billing cycle)
  • The customer is charged based on the maximum number of photos stored at any point in time during their billing cycle (vs. the # stored right at the end of the billing cycle)

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” }

The additional "type": "max" tells ChargeOver to calculate based on the maximum usage value rather than the sum of all usage.

REST API Example

REST API Example

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.

REST API Example

JSON Request

POST /api/v3/usage HTTP/1.1
Authorization: Basic N3N1dFdGRU8yektWWUlHbVpNSjNOaWo1aGZMeERSYjg6OXZDSmJtZFpLU2llVmNoeXJSSXRGUXc4TUJONGxPSDM=
Host: dev.chargeover.com
Content-Type: application/json
 
{
    "line_item_id": 609,
    "usage_value": 265.2,
    "from": "2013-10-16",
    "to": "2013-10-16"
}

JSON Response

HTTP/1.1 201 Created
Location: http://dev.chargeover.com/api/v3/usage/52
Content-Type: application/json
 
{
	"code": 201,
	"status": "OK",
	"message": "",
	"response": {
		"id": 52
	}
}
0.066 (gen) on Sat, 21 Apr 2018 10:06:42 -0500