List Usages
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-21Read 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.
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:
Query Parameters
Returns usages with an id greater than or equal to the one specified.
int64Returns usages with an id less than or equal to the one specified.
int64Returns usages with a created_at date greater than or equal to midnight (12:00 AM) on the date specified.
dateReturns usages with a created_at date less than or equal to midnight (12:00 AM) on the date specified.
dateResult records are organized in pages. By default, the first page of results is displayed. The page parameter specifies a page number of results to fetch. You can start navigating through the pages to consume the results. You do this by passing in a page parameter. Retrieve the next page by adding ?page=2 to the query string. If there are no results to return, then an empty result set will be returned.
Use in query page=1.
1 <= value1This parameter indicates how many records to fetch in each request. Default value is 20. The maximum allowed values is 200; any per_page value over 200 will be changed to 200.
Use in query per_page=200.
value <= 20020Response Body
application/json
curl -X GET "https://example.com/subscriptions/0/components/0/usages.json"[ { "usage": { "id": 178534642, "memo": "20", "created_at": "2018-08-03T11:58:42-05:00", "price_point_id": 242632, "quantity": "20.0", "component_id": 500093, "component_handle": "handle", "subscription_id": 22824464 } }, { "usage": { "id": 178534591, "memo": "10", "created_at": "2018-08-03T11:58:29-05:00", "price_point_id": 242632, "quantity": "10.0", "component_id": 500093, "component_handle": "handle", "subscription_id": 22824464 } }]Update Prepaid Usage Allocation Expiration Date PUT
Updates the expiration date for a prepaid usage allocation. This expiration date can be changed after the fact to allow for extending or shortening the allocation's active window. In order to change a prepaid usage allocation's expiration date, a PUT call must be made to the allocation's endpoint with a new expiration date. ## Limitations A few limitations exist when changing an allocation's expiration date: - An expiration date can only be changed for an allocation that belongs to a price point with expiration interval options explicitly set. - An expiration date can be changed towards the future with no limitations. - An expiration date can be changed towards the past (essentially expiring it) up to the subscription's current period beginning date.
Create Usage POST
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](https://maxio.zendesk.com/hc/en-us/articles/24261149711501-Create-Edit-and-Archive-Components). 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: - [Create and Manage Components](https://maxio.zendesk.com/hc/en-us/articles/24261149711501-Create-Edit-and-Archive-Components) - [Recording Metered Component Usage](https://maxio.zendesk.com/hc/en-us/articles/24251890500109-Reporting-Component-Allocations#reporting-metered-component-usage) - [Reporting Prepaid Component Status](https://maxio.zendesk.com/hc/en-us/articles/24251890500109-Reporting-Component-Allocations#reporting-prepaid-component-status) The `quantity` from usage for each component is accumulated to the `unit_balance` on the [Component Line Item](https://maxio-test-wp.pages.dev/api/openapi/subscription-components/readSubscriptionComponent) 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: ```json { "usage": { "quantity": 5000, "memo": "Recording 5000 units" } } ``` To reduce the quantity to `0`, POST the following payload: ```json { "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`.