Create Usage
Records an instance of metered or prepaid usage for a subscription.
You can report metered or prepaid usage to Advanced Billing as often as you wish. You can report usage as it happens or periodically, such as each night or once per billing period.
Full documentation on how to create Components in the Advanced Billing UI can be located here. Additionally, for information on how to record component usage against a subscription, see the following resources:
It is not possible to record metered usage for more than one component at a time. Usage should be reported as one API call per component on a single subscription. For example, to record that a subscriber has sent both an SMS Message and an Email, send an API call for each.
See the following product documentation articles for more information:
The quantity from usage for each component is accumulated to the unit_balance on the Component Line Item for the subscription.
Price Point ID usage
If you are using price points, for metered and prepaid usage components Advanced Billing gives you the option to specify a price point in your request.
You do not need to specify a price point ID. If a price point is not included, the default price point for the component will be used when the usage is recorded.
Deducting Usage
If you need to reverse a previous usage report or otherwise deduct from the current usage balance, you can provide a negative quantity.
Example:
Previously recorded quantity was 5000:
{ "usage": { "quantity": 5000, "memo": "Recording 5000 units" }}To reduce the quantity to 0, POST the following payload:
{ "usage": { "quantity": -5000, "memo": "Deducting 5000 units" }}The unit_balance has a floor of 0; negative unit balances are never allowed. For example, if the usage balance is 100 and you deduct 200 units, the unit balance would then be 0, not -100.
Authorization
BasicAuth The username is a Maxio Chargify API key. The password is x.
In: header
Path Parameters
Either the Advanced Billing subscription ID (integer) or the subscription reference (string). Important: In cases where a numeric string value matches both an existing subscription ID and an existing subscription reference, the system will prioritize the subscription ID lookup. For example, if both subscription ID 123 and subscription reference "123" exist, passing "123" will return the subscription with ID 123.
Either the Advanced Billing id for the component or the component's handle prefixed by handle:
Request Body
application/json
Response Body
application/json
application/json
curl -X POST "https://example.com/subscriptions/0/components/0/usages.json" \ -H "Content-Type: application/json" \ -d '{ "usage": { "quantity": 1000, "price_point_id": "149416", "memo": "My memo" } }'{ "usage": { "id": 138522957, "memo": "My memo", "created_at": "2017-11-13T10:05:32-06:00", "price_point_id": 149416, "quantity": 1000, "component_id": 500093, "component_handle": "handle", "subscription_id": 22824464 }}List Usages GET
Lists usages associated with a subscription for a particular metered component. This will display the previously recorded components for a subscription. This endpoint is not compatible with quantity-based components. ## Since Date and Until Date Usage Note: The `since_date` and `until_date` attributes each default to midnight on the date specified. For example, in order to list usages for January 20th, you would need to append the following to the URL. ``` ?since_date=2016-01-20&until_date=2016-01-21 ``` ## Read Usage by Handle Use this endpoint to read the previously recorded components for a subscription. You can now specify either the component id (integer) or the component handle prefixed by "handle:" to specify the unique identifier for the component you are working with.
Activate Event-Based Component POST
Activates an event-based component for a single subscription. To bill your subscribers on your Events data under the Events-Based Billing feature, the components must be activated for the subscriber. For more information, see [Design Your Catalog](https://docs.maxio.com/hc/en-us/articles/24181036583053-Design-Your-Catalog?method=componenttypes). Use this endpoint to activate an event-based component for a single subscription. Activating an event-based component causes billing for events when the subscription is renewed. Note: it is possible to stream events for a subscription at any time, regardless of component activation status. The activation status only determines if the subscription should be billed for event-based component usage at renewal.