---
title: "Get invoices"
method: GET
path: "/matters/{matterId}/invoices"
tags: ["Invoices"]
---

# Get invoices

`GET /matters/{matterId}/invoices`

## Request

- Base URL: `https://api.smokeball.com`
- URL: `https://api.smokeball.com/matters/{matterId}/invoices`
- Auth: API key in header `x-api-key` and API key in header `Authorization`

Returns a list of invoices for the specified matter.

## Path parameters

- `matterId` string, required

## Query parameters

- `LastUpdated` string, date-time
- `UpdatedSince` integer
- `Offset` integer
- `Limit` integer

## Response `200`

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

- InvoicePagedCollection
  - `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` Invoice[], 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: The unique identifier of the invoice.
    - `versionId` string, nullable: The unique identifier representing the current version of the invoice.
    - `matter` Link
      - `id` string, nullable
      - `href` string, nullable
      - `relation` string, nullable
      - `method` string, nullable
    - `matterId` string, nullable: The unique identifier of the matter this invoice belongs to.
    - `lastUpdatedByUserId` string, nullable: The unique identifier of the user who last updated the invoice.
    - `description` string, nullable: A short description of the invoice contents or purpose.
    - `status` 0 | 1 | 2 | 3 | 4: The status of the invoice. Possible values: Draft = 0, Final = 1, Paid = 2, Deleted = 3 or Void = 4.
    - `invoiceNumber` integer, nullable: The sequential number assigned to the invoice.
    - `invoiceTitle` string, nullable: The main title of the invoice.
    - `invoiceTitleLine2` string, nullable: The optional second line of the invoice title.
    - `issuedDate` string, date-time: The date the invoice was issued.
    - `dueDate` string, date-time: The date by which payment for the invoice is due.
    - `paidDate` string, date-time: The date the invoice was fully paid. Only populated if the invoice has been paid in full.
    - `discount` Discount
      - `type` 0 | 1
      - `fixedDiscount` number, double: The fixed discount amount to be subtracted from the invoice total. Only applicable when Type is Fixed.
      - `percentage` number, double: The percentage discount to be applied to the invoice total. Only applicable when Type is Percentage. Expressed as a number between 0 and 100.
      - `description` string, nullable: A description of the discount, such as the reason or category.
    - `surcharge` Surcharge
      - `type` 0 | 1 | 2
      - `fixedSurcharge` number, double, nullable: The fixed surcharge amount applied to the invoice total. Only applicable when Type is Fixed.
      - `percentage` number, double, nullable
      - `description` string, nullable: A description of the surcharge, such as the reason or category.
      - `applyTo` 0 | 1 | 2 | 3
    - `debtors` Debtor[], nullable: The list of debtors associated with this invoice.
      - `contact` Link
        - `id` string, nullable
        - `href` string, nullable
        - `relation` string, nullable
        - `method` string, nullable
    - `entries` InvoicedMatterEntryItem[], nullable: The individual entries (fees or expenses) included in the invoice.
      - `id` string, nullable
      - `versionId` string, nullable
      - `type` 0 | 1 | 2 | 3: Type of the activity. Possible values: Fixed = '0', Time = '1', Expense = '2', Surcharge = '3'
    - `adjustments` InvoiceAdjustment[], nullable: The finalized adjustments applied to the invoice.
      - `issuedDate` string, date-time: The date the adjustment was issued.
      - `amount` number, double: The credit amount of the adjustment, excluding tax.
      - `tax` number, double: The tax component of the adjustment credit.
      - `total` number, double: The total credit amount of the adjustment, including tax.
    - `waived` boolean: Indicates whether the invoice has been waived.
    - `invoiceTotals` InvoiceTotals
      - `paid` number, double: The total amount that has been paid towards the invoice.
      - `billed` number, double: The total amount billed on the invoice, excluding tax and interest. This includes all fees and expenses before discounts or write-offs.
      - `unpaid` number, double: The remaining amount due on the invoice, including any unpaid tax or interest.
      - `unpaidExcInterest` number, double: The total unpaid amount excluding interest. If this value is zero on an interest-bearing invoice, it indicates the principal has been fully paid, although interest may still be outstanding.
      - `writtenOff` number, double: The total amount that has been written off from the invoice and is no longer expected to be paid.
      - `waived` number, double: The total amount that has been waived on the invoice. Waived amounts are not charged but are also not written off.
      - `discount` number, double: The total amount discounted on the invoice. This includes all applied discounts reducing the billed amount.
      - `total` number, double: The grand total for the invoice, including tax and interest, before any payments, discounts, or write-offs.
      - `tax` number, double: The total tax amount applied to the invoice.
      - `interest` number, double: The total interest charged on the invoice, regardless of what has been paid so far.
      - `feeTotal` number, double: The total amount of all fees on the invoice, including both written off and non-written off fees.
      - `writtenOffFeeTotal` number, double: The total amount of fees that have been written off.
      - `expenseTotal` number, double: The total amount of all expenses on the invoice, including both written off and non-written off expenses.
      - `writtenOffExpenseTotal` number, double: The total amount of expenses that have been written off.
      - `adjustmentTotal` number, double: The total credit amount, including tax, of all finalized adjustments applied to the invoice.
  - `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

- `400`: When an unsupported request is made.

## Changes

- **2026-11-03** `6e350cf667d4`: 2 info
  - added the optional property `value/items/adjustments` to the response with the `200` status
  - added the optional property `value/items/invoiceTotals/allOf[#/components/schemas/InvoiceTotals]/adjustmentTotal` to the response with the `200` status
- **2026-07-26** `197984da9b42`: 1 warning
  - added the new `3.00` enum value to the `value/items/entries/items/type/allOf[#/components/schemas/EntryType]/` response property for the response status `200`

[Operation history](https://skmtc.dev/smokeball/apis/smokeball-api/changes/matters/:matterId/invoices/get.md)

---

[API](https://skmtc.dev/smokeball/apis/smokeball-api.md) - [All operations](https://skmtc.dev/smokeball/apis/smokeball-api/llms.txt) - [OpenAPI document](https://skmtc.dev/smokeball/apis/smokeball-api/revisions/6e350cf667d4?raw)