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

# Get an invoice

`GET /matters/{matterId}/invoices/{invoiceId}`

## Request

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

Retrieves a specified invoice.

## Path parameters

- `matterId` string, required
- `invoiceId` string, required

## Response `200`

When request is successful. Returns a 'Invoice' object.

- Invoice
  - `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.

## Other responses

- `400`: When an unsupported request is made.
- `403`: When invoice with specified id is not associated with authenticated client or matter.
- `404`: Not Found

## Changes

- **2026-11-03** `6e350cf667d4`: 2 info
  - added the optional property `adjustments` to the response with the `200` status
  - added the optional property `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 `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/:invoiceId/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)