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.

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

HTTP/1.1 200 OK
Content-Type: application/json

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

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.

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

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.

POST /api/v3/usage

{
    "package_id": 645,
    "usage_value": 1376,
    "from": "2013-11-02",
    "to": "2013-12-02"
}

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

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

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

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.

POST /api/v3/usage

{
    "line_item_id": 590,
    "usage_value": 265.2,
    "type": "max"
}

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

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

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.

POST /api/v3/usage

{
    "line_item_id": 590,
    "usage_value": 265.2,
    "type": "lat"
}

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.

POST /api/v3/usage

{
    "line_item_id": 590,
    "usage_value": 265.2,
    "option": [
        "ceil"
    ]
}

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.

POST /api/v3/usage

{
    "line_item_id": 590,
    "usage_value": 265.2,
    "option": [
        "round"
    ]
}