--- title: "Get the Purchase Order History report" method: GET path: "/public/v1/reports/purchase-order-history" tags: ["PurchaseOrderHistory"] --- # Get the Purchase Order History report `GET /public/v1/reports/purchase-order-history` ## Request - Base URL: `https://app.distru.com` - URL: `https://app.distru.com/public/v1/reports/purchase-order-history` - Auth: HTTP bearer Read-only report that returns one row per [purchase](#model-purchase), each carrying the purchase's order and due dates, vendor, status, owner, and monetary totals (amount paid and purchase total). This is a reporting endpoint: it never changes inventory, compliance state, or any purchase — calling it has no side effects. Scope and filtering: • Only purchases visible to the API key's company are included; there are no cross-company rows. • DRAFT purchases are always excluded — a purchase appears here only once it has left draft, so the `status` of every row is one of PENDING, PROCESSING, DELIVERING, PARTIALLY_RECEIVED, or COMPLETED. • When `order_datetime` is omitted the report defaults to the most recent 30-day range of purchase (order) dates (from the start of the day 30 days ago through the end of today, in the company's timezone). Because of this default the report always carries an order-date bound — there is no way to fetch every purchase regardless of order date. The other date filters (`due_datetime`, `created_datetime`, `updated_datetime`) have no default — omit one and it simply is not applied. • Different filters combine with AND (a row must satisfy every filter you supply), while multiple values inside a single list filter combine with OR. All date-range bounds are inclusive. Row shape: • Every value is returned as it appears in the report's CSV export. Monetary cells (`paid`, `amount`) are returned as strings (currency and comma formatting stripped) so they match the rest of the API; dates as ISO8601 timestamps in the company's timezone; everything else as strings. • The column set is dynamic. Companies on a compliance integration get an extra manifest-number column (`metrc_manifest_number` for Metrc, `biotrack_manifest_number` for BioTrack), and every Purchase custom field configured for the company is appended as an extra column keyed by its slugified label. Because of this, read `meta.columns` to discover the exact keys present rather than hardcoding them. • `meta` also returns the resolved human-readable date range the report covers (after the 30-day default is applied). • Each row also carries the IDs of the records it names — `purchase_order_id`, `vendor_id` and `purchase_order_owner_id`, each right after its name column — so a row can be followed to the purchase, company or user endpoints without a name lookup. The CSV export leaves these ID columns out. Required permission: `reports_permissions_purchase_order_history`. ## Query parameters - `status` string[] - `order_datetime` string - `due_datetime` string - `created_datetime` string - `updated_datetime` string - `total` string - `paid` string - `search` string - `company_relationship_ids` string[] - `location_ids` string[] - `owner_ids` string[] - `creator_ids` string[] - `batch_ids` string[] - `product_ids` string[] ## Response `200` The Purchase Order History report - PurchaseOrderHistoryReport: The Purchase Order History report - `data` PurchaseOrderHistoryReportRow[], required: The report rows - `amount` string, required: The purchase total; 0 when the purchase has no line items. - `due_date` string: The due date as an ISO8601 timestamp in the company's timezone; null when the purchase has no due date. - `owner` string: The purchase owner's full name; null when no owner is assigned. - `paid` string, required: Total amount paid on the purchase across its non-voided payments; 0 when nothing has been paid. - `purchase_date` string: The purchase (order) date as an ISO8601 timestamp in the company's timezone; null when the purchase has no order date. - `purchase_number` string, required: The purchase number. - `purchase_order_id` string, required: The purchase's ID — the `id` [GET /public/v1/purchases](#get-purchases) returns. - `purchase_order_owner_id` string: The purchase owner's ID — the `id` [GET /public/v1/users](#get-users) returns — or `null` when no owner is assigned. - `status` 'COMPLETED' | 'DELIVERING' | 'PENDING' | 'PARTIALLY_RECEIVED' | 'PROCESSING', required: The purchase status. One of PENDING, PROCESSING, DELIVERING, PARTIALLY_RECEIVED, COMPLETED — DRAFT never appears here. - `vendor` string, required: The vendor (supplier) company name. - `vendor_id` string, required: The vendor's company ID — the `id` [GET /public/v1/companies](#get-companies) returns and the value `company_relationship_ids` filters on. - `meta` PurchaseOrderHistoryReportMeta, required: Report-level metadata - `columns` PurchaseOrderHistoryReportColumn[], required: Ordered definitions of every column present in the data rows, including the compliance manifest column and any custom-field columns. Use this to map row keys to labels. - `key` string, required: The key this column is stored under in every data row (a slugified version of the label, e.g. `purchase_number`). - `label` string, required: The human-readable column header, e.g. `Purchase Number`. - `date_range` string, required: The human-readable date range the report covers, after the default 30-day range is applied when `order_datetime` is omitted. - `report` string, required: The report identifier; always `purchase_order_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`: 3 info - added the optional property `data/items/purchase_order_owner_id` to the response with the `200` status - added the required property `data/items/purchase_order_id` to the response with the `200` status - added the required property `data/items/vendor_id` to the response with the `200` status [Operation history](https://skmtc.dev/distru/apis/distru-api/changes/public/v1/reports/purchase-order-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)