---
title: "Get subscription usage charges"
method: GET
path: "/subscriptions/{subscriptionId}/charges"
tags: ["Subscriptions"]
---

# Get subscription usage charges

`GET /subscriptions/{subscriptionId}/charges`

Returns a paged list of usage charges across all usage products on the account's usage subscription,
sorted by created date descending.
            
Results can be filtered via query parameters:
* From/To (created date range)
* Status
* MatterId
* UserId
* ProductId

## Path parameters

- `subscriptionId` string, required

## Query parameters

- `From` string, date-time
- `To` string, date-time
- `Status` string
- `MatterId` string
- `UserId` string
- `ProductId` string
- `Offset` integer
- `Limit` integer

## Response `200`

When request is successful. Returns a paged collection of 'Charge' objects.

- ChargePagedCollection
  - `id` string, nullable
  - `href` string, nullable
  - `relation` string, nullable
  - `method` string, nullable
  - `self` Link
    - `id` string, nullable
    - `href` string, nullable
    - `relation` string, nullable
    - `method` string, nullable
  - `value` Charge[], nullable
    - `href` string, nullable
    - `relation` string, nullable
    - `method` string, nullable
    - `self` Link
      - `id` string, nullable
      - `href` string, nullable
      - `relation` string, nullable
      - `method` string, nullable
    - `id` string, nullable — Unique identifier of the usage charge.
    - `externalId` string, nullable — The external usage charge id.
    - `externalAdjustmentId` string, nullable — The external adjustment id created when the usage charge is canceled.
    - `expenseId` string, nullable — The Billing expense id created for the usage charge.
    - `subscriptionId` string, nullable — The subscription id.
    - `accountId` string, nullable — The Smokeball firm id.
    - `userId` string, nullable — The user id that created the usage charge.
    - `productId` string, nullable — The product id.
    - `priceId` string, nullable — The internal price id.
    - `metadata` object, nullable — Caller-supplied metadata associated with the charge.
    - `matterId` string, nullable — The matter id associated with the usage charge.
    - `description` string, nullable — The description associated with the usage charge.
    - `supplierTransactionId` string, nullable — The supplier transaction id associated with the usage charge.
    - `supplierTransactionAmount` number, double, nullable — The supplier transaction amount associated with the usage charge.
    - `amount` number, double, nullable — The total customer billing amount for the usage charge, in cents.
    - `quantity` integer — The usage quantity recorded for the charge.
    - `status` string — The usage charge status. * Pending * Succeeded * Failed * Canceled * Refunded
    - `failureReason` string, nullable — The reason the usage charge failed.
    - `createdDate` string, date-time — The created date of the usage charge.
    - `updatedDate` string, date-time — The updated date of the usage charge.
    - `occurredDate` string, date-time — The date the usage occurred.
  - `offset` integer, nullable
  - `limit` integer, nullable
  - `size` integer
  - `first` Link
    - `id` string, nullable
    - `href` string, nullable
    - `relation` string, nullable
    - `method` string, nullable
  - `previous` Link
    - `id` string, nullable
    - `href` string, nullable
    - `relation` string, nullable
    - `method` string, nullable
  - `next` Link
    - `id` string, nullable
    - `href` string, nullable
    - `relation` string, nullable
    - `method` string, nullable
  - `last` Link
    - `id` string, nullable
    - `href` string, nullable
    - `relation` string, nullable
    - `method` string, nullable

## Other responses

- `404` — When the usage subscription does not exist.

---

[API](https://skmtc.net/smokeball/apis/api.md) · [All operations](https://skmtc.net/smokeball/apis/api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/smokeball/api/versions/197984da9b42/schema)