---
title: "Get the Invoice History report"
method: GET
path: "/public/v1/reports/invoice-history"
tags: ["InvoiceHistory"]
---

# Get the Invoice History report

`GET /public/v1/reports/invoice-history`

## Request

- Base URL: `https://app.distru.com`
- URL: `https://app.distru.com/public/v1/reports/invoice-history`
- Auth: HTTP bearer

Read-only report: returns one row per invoice with its dates, sales order, customer, payment status, and monetary totals (paid, outstanding, line item subtotal, taxes, charges, discounts, and grand total) along with the per-tax, per-charge, and per-discount summary strings. This endpoint only reads — it never mutates invoices, inventory, payments, or compliance state.

Scope and date defaulting:

• Results are scoped to the company that owns the API key, and further to the invoices the key's user is allowed to view.
• Filtering on `invoice_datetime` is optional; when you omit it the report covers the last 30 days (from the start of the day 30 days ago through the end of today, resolved in the API key user's timezone). No other filter has a default. `due_datetime` has no implicit range.
• The resolved invoice-date window (whether you passed it or it defaulted) is echoed back as a human-readable string in `meta.date_range`.

Row shape and value formatting:

• Rows always come back ordered by invoice number, descending. This endpoint exposes no sort parameter — the order is fixed regardless of which filters (including `search`) you pass.
• Monetary cells (`paid`, `outstanding`, `line_item_subtotal`, `total_taxes`, `total_charges`, `total_discounts`, `total`) are returned as strings (currency and comma formatting stripped) so they match the rest of the API, already coalesced to `"0"` when the invoice has no matching payments/taxes/charges/discounts — they are never null.
• The summary cells (`tax_summary`, `charge_summary`, `discount_summary`) are human-readable breakdown strings and are null when the invoice has no taxes, no positive charges, or no negative charges (discounts) respectively.
• `status` is a SCREAMING_CASE payment-status token (see the values below).
• Each row also carries the IDs of the records it names — `invoice_id`, `sales_order_id`, `customer_id` and `invoice_owner_id`, each right after its name column — so a row can be followed to the invoice, order, company or user endpoints without a name lookup. The CSV export leaves these ID columns out.

Extra columns:

• Companies on a compliance integration get two additional columns — the transfer manifest number and the shipped-from license number. They are labelled by system (Metrc vs BioTrack) but carry the same data.
• Any Invoice custom fields configured for the company are appended as additional columns, keyed by a slug of the field label.

Because the set of columns varies by company (compliance integration and custom fields), read `meta.columns` to discover the exact keys present in each `data` row rather than hard-coding them.

Required permission: view the invoice history report.

## Query parameters

- `status` string[]
- `order_status` string[]
- `invoice_datetime` string
- `due_datetime` string
- `total` string
- `paid` string
- `search` string
- `company_relationship_ids` string[]
- `shipped_from_license_ids` string[]
- `batch_ids` string[]
- `product_ids` string[]

## Response `200`

The Invoice History report

- InvoiceHistoryReport: The Invoice History report
  - `data` InvoiceHistoryReportRow[], required: The report rows
    - `charge_summary` string: Human-readable per-charge breakdown of the positive charges. Null when the invoice has none.
    - `customer` string, required: The customer's company name
    - `customer_id` string, required: The customer's company ID — the `id` [GET /public/v1/companies](#get-companies) returns and the value `company_relationship_ids` filters on.
    - `discount_summary` string: Human-readable per-discount breakdown. Null when the invoice has no discounts.
    - `due_date` string: The invoice due date as `YYYY-MM-DD` in the API key user's timezone. Null when the invoice has no due date set.
    - `invoice_date` string: The invoice date as `YYYY-MM-DD` in the API key user's timezone. Null when the invoice has no invoice date set.
    - `invoice_id` string, required: The invoice's ID — the `id` [GET /public/v1/invoices](#get-invoices) returns.
    - `invoice_number` string: The invoice number. Null when the invoice has none.
    - `invoice_owner_id` string: The invoice owner's ID — the `id` [GET /public/v1/users](#get-users) returns — or `null` when the invoice has no owner.
    - `line_item_subtotal` string, required: Sum of the invoice's line items (quantity times unit price); `0` when there are none.
    - `outstanding` string, required: The unpaid balance: invoice total minus amount paid. Negative when overpaid.
    - `owner` string: Full name of the invoice's owner (the assigned user). Null when the invoice has no owner.
    - `paid` string, required: The total amount paid on the invoice across its non-voided payments; `0` when nothing has been paid.
    - `sales_order` string, required: The order number of the sales order this invoice belongs to
    - `sales_order_id` string, required: The ID of the sales order this invoice belongs to — the `id` [GET /public/v1/orders](#get-orders) returns.
    - `status` 'NOT_PAID' | 'PARTIALLY_PAID' | 'FULLY_PAID' | 'OVER_PAID': The invoice payment status, SCREAMING_CASE: NOT_PAID, PARTIALLY_PAID, FULLY_PAID, OVER_PAID (OVER_PAID only on legacy invoices). Null on the rare invoice with no payment status set.
    - `tax_summary` string: Human-readable per-tax breakdown, e.g. `Excise Tax - $12.50, City Tax - $4.00`. Null when the invoice has no taxes.
    - `total` string, required: The invoice grand total
    - `total_charges` string, required: Sum of the invoice's positive (non-discount, non-tax) charges; `0` when none.
    - `total_discounts` string, required: Sum of the invoice's discounts (negative charges), expressed as a negative number; `0` when none.
    - `total_taxes` string, required: Sum of the invoice's taxes; `0` when none.
  - `meta` InvoiceHistoryReportMeta, required: Report-level metadata
    - `columns` InvoiceHistoryReportColumn[], required: Ordered definitions of every column in each `data` row, including the compliance and custom-field columns that vary by company. Use this to discover the exact keys present.
      - `key` string, required: The key this column uses in each `data` row
      - `label` string, required: The human-readable label of the column
    - `date_range` string, required: Human-readable invoice-date window the report covers, reflecting either the `invoice_datetime` filter or the default last-30-days window when it was omitted.
    - `report` string, required: The report identifier, always `invoice_history`

## Other responses

- `400`: Invalid parameters
- `401`: Missing or invalid API token
- `403`: The API token lacks the required permission, or team restrictions hide the record

## Changes

- **2026-10-07** `e8639f7dafed`: 4 info
  - added the optional property `data/items/invoice_owner_id` to the response with the `200` status
  - added the required property `data/items/customer_id` to the response with the `200` status
  - added the required property `data/items/invoice_id` to the response with the `200` status
  - added the required property `data/items/sales_order_id` to the response with the `200` status

[Operation history](https://skmtc.dev/distru/apis/distru-api/changes/public/v1/reports/invoice-history/get.md)

---

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