DIdistru
InvoiceHistory

Get the Invoice History report

Changed on

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.

get/public/v1/reports/invoice-history

Request

  • Base URL
    https://app.distru.com
  • Auth
    HTTP bearer

Query parameters

statusstring[]

Filter by invoice payment status. Repeat the key to pass several values; an invoice matches if its status is any of them (OR). Values are SCREAMING_CASE: NOT_PAID, PARTIALLY_PAID, FULLY_PAID, OVER_PAID (OVER_PAID only occurs on legacy invoices). Omit to include every status.

order_statusstring[]

Filter by the status of the sales order each invoice belongs to. Repeat the key to pass several values; matches any (OR). Values are SCREAMING_CASE: PENDING, PROCESSING, READY_TO_SHIP, DELIVERING, DELIVERED, COMPLETED, CANCELED. Omit to include orders in any status.

invoice_datetimestring

Filter by invoice date, as a comma-separated ISO8601 datetime range from,to. Either side may be left empty for an open-ended range (2026-01-01T00:00:00Z, = on or after that instant; ,2026-02-01T00:00:00Z = on or before it); both sides empty is rejected. When this filter is omitted entirely the report defaults to the last 30 days, and the resolved window is reflected in meta.date_range.

due_datetimestring

Filter by invoice due date, as a comma-separated ISO8601 datetime range from,to. Either side may be empty for an open-ended range. Unlike invoice_datetime this has no default — omit it to apply no due-date filter.

totalstring

Filter by the invoice grand total, as a comma-separated min,max numeric range. Bounds are inclusive; omit a side to leave it unbounded.

paidstring

Filter by the amount paid on the invoice, as a comma-separated min,max numeric range. Bounds are inclusive; omit a side to leave it unbounded.

searchstring

Case-insensitive substring match on the invoice number. Combines with the other filters (AND); does not change the result ordering, which is always invoice number descending. Omit to skip the invoice-number search.

company_relationship_idsstring[]

Filter by customer. Each value is the Distru id of the customer's company relationship (the same id returned as the customer reference elsewhere in the API). Repeat the key to pass several; matches any (OR).

shipped_from_license_idsstring[]

Filter by the license the order shipped from. Each value is a Distru license id. Repeat the key to pass several; matches any (OR).

batch_idsstring[]

Filter to invoices whose line items reference any of these batches. Each value is a Distru batch id. Repeat the key to pass several; matches any (OR).

product_idsstring[]

Filter to invoices whose line items reference any of these products. Each value is a Distru product id. Repeat the key to pass several; matches any (OR).

Response

The Invoice History report

Changes

  • e8639f7dafedRevision changes
    • info

      added the optional property // to the response with the status

    • info

      added the required property // to the response with the status

    • info

      added the required property // to the response with the status

    • info

      added the required property // to the response with the status