# Subscription usage billing
## GET /subscriptions/{SubscriptionReference}/usages/
> Filter usages for a subscription
```json
{"openapi":"3.0.0","info":{"title":"API REST Documentation","version":"6.0-oas3"},"servers":[{"url":"https://api.2checkout.com/rest/6.0"}],"paths":{"/subscriptions/{SubscriptionReference}/usages/":{"get":{"tags":["Subscription usage billing"],"summary":"Filter usages for a subscription","parameters":[{"name":"SubscriptionReference","in":"path","description":"Unique code which represents a subscription","required":true,"style":"simple","explode":false,"schema":{"type":"string"}},{"name":"IntervalStart","in":"query","description":"The IntervalStart date in YYY-MM-DD HH:MM:SS format to filter by","required":true,"style":"form","explode":true,"schema":{"type":"string"}},{"name":"IntervalEnd","in":"query","description":"The IntervalEnd date in YYY-MM-DD HH:MM:SS format to filter by","required":true,"style":"form","explode":true,"schema":{"type":"string"}},{"name":"Page","in":"query","description":"The page to be returned","required":true,"style":"form","explode":true,"schema":{"type":"integer"}},{"name":"Limit","in":"query","description":"The number of results per page. [MAX 100]","required":true,"style":"form","explode":true,"schema":{"type":"integer"}},{"name":"OptionCode","in":"query","description":"The additional price option code to filter by.","required":false,"style":"form","explode":true,"schema":{"type":"string"}},{"name":"RenewalOrderReference","in":"query","description":"The renewal order unique identifier.","required":false,"style":"form","explode":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"The filtered usages","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FilteredUsagesResponse"}}}},"400":{"description":"There has been a client error. The \"message\" can be on of the following:- If the Page parameter is invalid:\"The Page parameter must be a positive integer higher than or equal to 1.\";
- If the Limit parameter is invalid:\"The Limit parameter must be a positive integer lower than 100\";
- If IntervalStart or IntervalEnd parameters are not proided together:\"Both 'IntervalStart' and 'IntervalEnd' parameters must be provided\";
- if the RenewalOrderReference parameter is invalid:\"If provided, 'RenewalOrderReference' must be a positive integer.\";
- If IntervalStart does not respect the required date format:\"'IntervalStart' must be provided in the following format:YYYY-MM-DD HH:MM:SS\";
- If Intervalend does not respect the required date format:\"'IntervalEnd' must be provided in the following format:YYYY-MM-DD HH:MM:SS\";
- If the provided usage start date is earlier than the subscription start date or the provided usage end date is higher than the subscription expiration date\"Usage interval out of bounds\".
","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsageFilterClientErrorResponse"}}}},"404":{"description":"Filter usages client error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsageNotFoundErrorResponse"}}}},"500":{"description":"Filter usage server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsageFilterServerErrorResponse"}}}}}}}},"components":{"schemas":{"FilteredUsagesResponse":{"type":"object","properties":{"Items":{"type":"array","items":{"$ref":"#/components/schemas/Usage"}},"Pagination":{"$ref":"#/components/schemas/FilteredUsagesResponse_Pagination"}}},"Usage":{"required":["OptionCode","SubscriptionReference","Units","UsageEnd","UsageStart"],"type":"object","properties":{"UsageReference":{"type":"integer","description":"The unique usage identifier"},"SubscriptionReference":{"type":"string","description":"The subscription code"},"OptionCode":{"type":"string","description":"The price option group code"},"UsageStart":{"type":"string","description":"The date the usage came in effect."},"UsageEnd":{"type":"string","description":"The date the usage was stopped being used."},"Units":{"type":"integer","format":"int32"},"Description":{"type":"string"}}},"FilteredUsagesResponse_Pagination":{"type":"object","properties":{"Page":{"type":"integer","description":"Current page"},"Limit":{"type":"integer","description":"Max number of results per page"},"Count":{"type":"integer","description":"The total number of results"}}},"UsageFilterClientErrorResponse":{"type":"object","properties":{"error_code":{"type":"string","description":"Error type"},"message":{"type":"string","description":"Error message"}}},"UsageNotFoundErrorResponse":{"type":"object","properties":{"error_code":{"type":"string","description":"Error type"},"message":{"type":"string","description":"Error message"}}},"UsageFilterServerErrorResponse":{"type":"object","properties":{"error_code":{"type":"string","description":"Error type"},"message":{"type":"string","description":"Error message"}}}}}}
```
## POST /subscriptions/{SubscriptionReference}/usages/
> Save usages for a subscription
```json
{"openapi":"3.0.0","info":{"title":"API REST Documentation","version":"6.0-oas3"},"servers":[{"url":"https://api.2checkout.com/rest/6.0"}],"paths":{"/subscriptions/{SubscriptionReference}/usages/":{"post":{"tags":["Subscription usage billing"],"summary":"Save usages for a subscription","parameters":[{"name":"SubscriptionReference","in":"path","description":"Unique code which represents a subscription","required":true,"style":"simple","explode":false,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsageSaveRequest"}}},"required":true},"responses":{"200":{"description":"The saved usages","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsageSaveResponse"}}}},"400":{"description":"There has been a client error. The \"message\" in the sample below can be on of the following:- If mandatory parameters are missing:\"Usage was not added as one or more of the mandatory parameters are missing\";
- If parameters do not math the required format:\"Usage was not added as one or more of the parameters do not match the required format\";
- If the subscription does not belong to this account:\"Usage was not added as the license code provided is invalid\";
- If the provided option code does not belong to the subscription products:\"Usage was not added as the option code provided is invalid\";
- If the usage intervals for the provided usages overlap between themselves or existing usages:\"Usage was not added as the usage interval provided overlaps with an existing usage interval for the same LICENCECODE and OPTIONCODE combination\";
- If the provided usage start date is earlier than the subscription start date or the provided usage end date is higher than the subscription expiration date\"Usage interval out of bounds\".
","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsageSaveClientErrorResponse"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsageNotFoundErrorResponse"}}}},"500":{"description":"There has been an unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsageSaveServerErrorResponse"}}}}}}}},"components":{"schemas":{"UsageSaveRequest":{"type":"array","items":{"$ref":"#/components/schemas/UsageSaveObject"}},"UsageSaveObject":{"required":["OptionCode","Units","UsageEnd","UsageStart"],"type":"object","properties":{"OptionCode":{"type":"string","description":"The price option group code"},"UsageStart":{"type":"string","description":"The date the usage came in effect."},"UsageEnd":{"type":"string","description":"The date the usage was stopped being used."},"Units":{"type":"integer","format":"int32"},"Description":{"type":"string"}}},"UsageSaveResponse":{"type":"array","items":{"$ref":"#/components/schemas/Usage"}},"Usage":{"required":["OptionCode","SubscriptionReference","Units","UsageEnd","UsageStart"],"type":"object","properties":{"UsageReference":{"type":"integer","description":"The unique usage identifier"},"SubscriptionReference":{"type":"string","description":"The subscription code"},"OptionCode":{"type":"string","description":"The price option group code"},"UsageStart":{"type":"string","description":"The date the usage came in effect."},"UsageEnd":{"type":"string","description":"The date the usage was stopped being used."},"Units":{"type":"integer","format":"int32"},"Description":{"type":"string"}}},"UsageSaveClientErrorResponse":{"type":"object","properties":{"error_code":{"type":"string","description":"Error type"},"message":{"type":"string","description":"Error message"}}},"UsageNotFoundErrorResponse":{"type":"object","properties":{"error_code":{"type":"string","description":"Error type"},"message":{"type":"string","description":"Error message"}}},"UsageSaveServerErrorResponse":{"type":"object","properties":{"error_code":{"type":"string","description":"Error type"},"message":{"type":"string","description":"Error message"}}}}}}
```
## DELETE /subscriptions/{SubscriptionReference}/usages/
> Deletes one or more usage entries based on the provided criteria
```json
{"openapi":"3.0.0","info":{"title":"API REST Documentation","version":"6.0-oas3"},"servers":[{"url":"https://api.2checkout.com/rest/6.0"}],"paths":{"/subscriptions/{SubscriptionReference}/usages/":{"delete":{"tags":["Subscription usage billing"],"summary":"Deletes one or more usage entries based on the provided criteria","parameters":[{"name":"SubscriptionReference","in":"path","description":"Unique code which represents a subscription","required":true,"style":"simple","explode":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"No content"},"400":{"description":"There has been a client error. The \"message\" can be on of the following:- If the SubscriptionReference parameter is missing or does not match required type:\"One or more parameters lack the required format:SubscriptionReference must be a string.\";
- If mandatory parameters are missing:\"Please provide at least one of the following parameters:UsageReference, OptionCode, IntervalStart, IntervalEnd\";
- If one or more parameters lack the required format:\"One or more parameters lack the required format:\";
- Usage line already billed:\"Usage was not deleted as this usage was already billed.\";
- Renewal in progress:\"There is a renewal in progress for the provided usage line.\";
","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsageDeleteClientErrorResponse"}}}},"404":{"description":"The \"message\" can be on of the following:- When the subscription does not exist or does not belong to this account:\"Subscription not found.\";
- The usage line does not exist:\"Usage line described does not exist\";
","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsageNotFoundErrorResponse"}}}},"500":{"description":"Delete usages server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsageDeleteServerErrorResponse"}}}}}}}},"components":{"schemas":{"UsageDeleteClientErrorResponse":{"type":"object","properties":{"error_code":{"type":"string","description":"Error type"},"message":{"type":"string","description":"Error message"}}},"UsageNotFoundErrorResponse":{"type":"object","properties":{"error_code":{"type":"string","description":"Error type"},"message":{"type":"string","description":"Error message"}}},"UsageDeleteServerErrorResponse":{"type":"object","properties":{"error_code":{"type":"string","description":"Error type"},"message":{"type":"string","description":"Error message"}}}}}}
```
## PUT /subscriptions/{SubscriptionReference}/usages/{UsageReference}
> Update a specific usage entry
```json
{"openapi":"3.0.0","info":{"title":"API REST Documentation","version":"6.0-oas3"},"servers":[{"url":"https://api.2checkout.com/rest/6.0"}],"paths":{"/subscriptions/{SubscriptionReference}/usages/{UsageReference}":{"put":{"tags":["Subscription usage billing"],"summary":"Update a specific usage entry","parameters":[{"name":"SubscriptionReference","in":"path","description":"Unique code which represents a subscription","required":true,"style":"simple","explode":false,"schema":{"type":"string"}},{"name":"UsageReference","in":"path","description":"Unique integer which represents a subscription usage","required":true,"style":"simple","explode":false,"schema":{"type":"integer"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsageUpdateRequest"}}},"required":true},"responses":{"200":{"description":"The updated usage","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Usage"}}}},"400":{"description":"There has been a client error. The \"message\" can be on of the following:- If the SubscriptionReference parameter is missing or does not match required type:\"One or more parameters lack the required format:SubscriptionReference must be a string.\";
- If mandatory parameters are missing:\"Please provide at least one of the following parameters:UsageReference, OptionCode, IntervalStart, IntervalEnd\";
- If one or more parameters lack the required format:\"One or more parameters lack the required format:\";
- Usage line already billed:\"Usage was not updated as this usage was already billed.\";
- Renewal in progress:\"There is a renewal in progress for the provided usage line.\";
","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsageUpdateClientErrorResponse"}}}},"404":{"description":"The \"message\" can be on of the following:- When the subscription does not exist or does not belong to this account:\"Subscription not found.\";
- The usage line does not exist:\"Usage line described does not exist\";
","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsageNotFoundErrorResponse"}}}},"500":{"description":"Update usage server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsageUpdateServerErrorResponse"}}}}}}}},"components":{"schemas":{"UsageUpdateRequest":{"type":"object","properties":{"Units":{"type":"integer","description":"The new units to be updated on the subscription usage."},"Description":{"type":"string","description":"The new description to be updated on the subscription usage."}}},"Usage":{"required":["OptionCode","SubscriptionReference","Units","UsageEnd","UsageStart"],"type":"object","properties":{"UsageReference":{"type":"integer","description":"The unique usage identifier"},"SubscriptionReference":{"type":"string","description":"The subscription code"},"OptionCode":{"type":"string","description":"The price option group code"},"UsageStart":{"type":"string","description":"The date the usage came in effect."},"UsageEnd":{"type":"string","description":"The date the usage was stopped being used."},"Units":{"type":"integer","format":"int32"},"Description":{"type":"string"}}},"UsageUpdateClientErrorResponse":{"type":"object","properties":{"error_code":{"type":"string","description":"Error type"},"message":{"type":"string","description":"Error message"}}},"UsageNotFoundErrorResponse":{"type":"object","properties":{"error_code":{"type":"string","description":"Error type"},"message":{"type":"string","description":"Error message"}}},"UsageUpdateServerErrorResponse":{"type":"object","properties":{"error_code":{"type":"string","description":"Error type"},"message":{"type":"string","description":"Error message"}}}}}}
```
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.2checkout.com/api-reference/reference/subscription-usage-billing.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.