---
title: "Filter usages for a subscription"
method: GET
path: "/subscriptions/{SubscriptionReference}/usages/"
tags: ["Subscription usage billing"]
---

# Filter usages for a subscription

`GET /subscriptions/{SubscriptionReference}/usages/`

## Path parameters

- `SubscriptionReference` string, required

## Query parameters

- `IntervalStart` string, required
- `IntervalEnd` string, required
- `Page` integer, required
- `Limit` integer, required
- `OptionCode` string
- `RenewalOrderReference` integer

## Response `200`

The filtered usages

- FilteredUsagesResponse
  - `Items` Usage[]
    - `UsageReference` integer — The unique usage identifier
    - `SubscriptionReference` string, required — The subscription code
    - `OptionCode` string, required — The price option group code
    - `UsageStart` string, required — The date the usage came in effect.
    - `UsageEnd` string, required — The date the usage was stopped being used.
    - `Units` integer, required
    - `Description` string
  - `Pagination` FilteredUsagesResponsePagination
    - `Page` integer — Current page
    - `Limit` integer — Max number of results per page
    - `Count` integer — The total number of results

## Other responses

- `400` — There has been a client error. The <b>"message"</b> can be on of the following:</br><ul><li>If the <b>Page</b> parameter is invalid:<b>"The Page parameter must be a positive integer higher than or equal to 1."</b>;</li><li>If the <b>Limit</b> parameter is invalid:<b>"The Limit parameter must be a positive integer lower than 100"</b>;</li><li>If <b>IntervalStart</b> or <b>IntervalEnd</b> parameters are not proided together:<b>"Both 'IntervalStart' and 'IntervalEnd' parameters must be provided"</b>;</li><li>if the <b>RenewalOrderReference</b> parameter is invalid:<b>"If provided, 'RenewalOrderReference' must be a positive integer."</b>;</li><li>If <b>IntervalStart</b> does not respect the required date format:<b>"'IntervalStart' must be provided in the following format:YYYY-MM-DD HH:MM:SS"</b>;</li><li>If <b>Intervalend</b> does not respect the required date format:<b>"'IntervalEnd' must be provided in the following format:YYYY-MM-DD HH:MM:SS"</b>;</li><li>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<b>"Usage interval out of bounds"</b>.</li></ul>
- `404` — Filter usages client error
- `500` — Filter usage server error

---

[API](https://skmtc.dev/2checkout/apis/api-rest-documentation.md) · [All operations](https://skmtc.dev/2checkout/apis/api-rest-documentation/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/2checkout/api-rest-documentation/revisions/8a7ea610933e/schema)