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 at the time of invoicing to fetch usage data from your system.

Best Practices for Usage URLs

Here are a few guidelines for best practices when using usage URLs to provie ChargeOver with usage data:

  • DO return a 200 OK HTTP response if you were able to return usage successfully to ChargeOver
  • DO always return valid JSON
  • DO return a meaningful error message if some error occurs (so that you and/or the ChargeOver team can troubleshoot later)
  • DO log the request from ChargeOver and your response (so that you can troubleshoot if required)
  • DO NOT return a 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.
  • DO NOT return invalid JSON
  • DO NOT return empty responses

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

API Request

POST /path/to/your/endpoint HTTP/1.1
Content-Type: application/json
 
{
  "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"
}

API Response

HTTP/1.1 200 OK
Content-Type: application/json
 
{
    "line_items": [
        {
            "usage_amount": 25
        }
    ]
}

REST API Usage

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.

REST API Examples

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!

Send Usage For a Specific Line Item

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.

Send Usage For a Specific Line Item

API Request

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

API Response

HTTP/1.1 201 Created
Location: https://example.chargeover.com/api/v3/usage/52
Content-Type: application/json
 
{
    "code": 201,
    "status": "OK",
    "message": "",
    "response": {
        "id": 52
    }
}

Send Usage for a Specific Subscription

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.

Send Usage for a Specific Subscription

API Request

POST /api/v3/usage
 
{
    "package_id": 645,
    "usage_value": 1376,
    "from": "2013-11-02",
    "to": "2013-12-02"
}

API Response

{
    "code": 201,
    "status": "OK",
    "message": "",
    "details": {},
    "response": {
        "id": 4
    }
}

Send Usage Using External Keys

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.

Send Usage Using External Keys

API Request

POST /api/v3/usage
 
{
    "customer.external_key": "customer_key",
    "line_item.item_external_key": "item_key",
    "usage_value": 2165,
    "from": "2018-10-2",
    "to": "2018-11-2"
}

API Response

{
    "code": 201,
    "status": "OK",
    "message": "",
    "details": {},
    "response": {
        "id": 5
    }
}

Usage Formulas

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

  • Maximum value - You send usage data to ChargeOver routinely, and the customer should be charged for the maximum value within that data.
  • Cumulative/Sum - 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.
  • Latest - Have ChargeOver use the latest value you send.

Maximum

Use the maximum value

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

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

Use the maximum value

API Request

POST /api/v3/usage
 
{
    "line_item_id": 590,
    "usage_value": 265.2,
    "type": "max"
}

Cumulative/Sum

Use the sum

The cumulative/sum 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.).

Use the sum

API Request

POST /api/v3/usage
 
{
    "line_item_id": 590,
    "usage_value": 265.2,
    "_comment": "This last attribute is optional; ChargeOver's default is to add up the usage values",
    "type": "add"
}

Latest

Use the latest value

The latest value mode is used when you want to send data to ChargeOver routinely, where the latest value is always the metric to bill for. For example:

  • The customer uses gigabytes of memory, and you want to bill the customer for the latest amount of memory used.
  • The customer is charged based on the latest number of photos stored.

You can tell ChargeOver to calculate usage based on the latest (newest) value you sent to ChargeOver. For this scenario, you'd most commonly send ChargeOver usage on a routine basis (e.g. every day, every hour, etc.).

The additional "type": "lat" tells ChargeOver to calculate based on the latest value.

Use the latest value

API Request

POST /api/v3/usage
 
{
    "line_item_id": 590,
    "usage_value": 265.2,
    "type": "lat"
}

Usage Options

The options attribute allows you to tell ChargeOver treat metered data in specific ways (for example, round the metered data up or down to present friendly integers to end-users, instead of floats).

Ceil

Ceiling (Round fractions up)

The ceil option rounds fractions/floats up to the next integer.

For example, if the uploaded usage would be have been 265.2, the usage would be rounded up to the next integer 266.

For cumulative usage, ceil is applied after the usage is summed up. So if you uploaded multiple data points then the usage is summed first, and then rounded up.

For example, if you uploaded 1.2 on day 1, 2.3 on day 2, and 3.4 on day 3, then these are summed up ( sum is 6.9 ), and then rounded up to 7.

Ceiling (Round fractions up)

API Request

POST /api/v3/usage
 
{
    "line_item_id": 590,
    "usage_value": 265.2,
    "option": [
        "ceil"
    ]
}

Round

Round floats/fractions

The round option rounds fractions/floats up or down to the nearest integer. Halves are rounded up.

  • 1.4 rounds down to 1
  • 1.5 rounds up to 2
  • 1.6 rounds up to 2

For cumulative usage, round is applied after the usage is summed up. So if you uploaded multiple data points then the usage is summed first, and then rounded.

For example, if you uploaded 1.2 on day 1, 2.3 on day 2, and 3.4 on day 3, then these are summed up ( sum is 6.9 ), and then rounded to 7.

Round floats/fractions

API Request

POST /api/v3/usage
 
{
    "line_item_id": 590,
    "usage_value": 265.2,
    "option": [
        "round"
    ]
}
0.077 (gen) on Thu, 28 Mar 2024 05:40:32 -0500