Distru Purchase Order History API

openapi: 3.2.0
info:
  license:
    name: Proprietary
    url: https://www.distru.com/legal/terms-of-service
  title: Distru Purchase Order History API
  version: '1.0'
servers:
- url: https://app.distru.com
security:
- Bearer: []
tags:
- name: PurchaseOrderHistory
paths:
  /public/v1/reports/purchase-order-history:
    get:
      description: 'Read-only report that returns one row per 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`.'
      operationId: DistruPublic.V1.Report.PurchaseOrderHistoryController.index
      parameters:
      - description: 'Keep only purchases whose status is one of the supplied values (OR within the list). Values are SCREAMING_CASE: PENDING, PROCESSING, DELIVERING, PARTIALLY_RECEIVED, COMPLETED. DRAFT is not accepted and never returned — draft purchases are excluded from this report regardless of filters. Omit to include every non-draft status.'
        in: query
        name: status
        required: false
        style: form
        explode: false
        schema:
          type: array
          items:
            enum:
            - COMPLETED
            - DELIVERING
            - PENDING
            - PARTIALLY_RECEIVED
            - PROCESSING
            type: string
      - description: 'Keep only purchases whose order (purchase) date falls in the given range. Format is a comma-separated ISO8601 datetime pair `after,before`; both bounds are inclusive. Leave either side empty for an open-ended bound (e.g. `2026-01-01T00:00:00Z,` for everything from that date onward), but a bare comma with both sides empty (`,`) is rejected — omit the param entirely to apply no bound. This is the one date filter with a default: when omitted, the report covers the most recent 30-day range of order dates.'
        in: query
        name: order_datetime
        required: false
        example: ?order_datetime=2026-01-01T00:00:00Z,2026-02-01T00:00:00Z
        schema:
          type: string
      - description: Keep only purchases whose due date falls in the given range. Comma-separated ISO8601 datetime pair `after,before`; both bounds inclusive, either side may be empty for an open-ended bound (a bare `,` is rejected). No default — omit to skip this filter.
        in: query
        name: due_datetime
        required: false
        example: ?due_datetime=2026-01-01T00:00:00Z,2026-02-01T00:00:00Z
        schema:
          type: string
      - description: Keep only purchases created in the given range, by the record's creation timestamp. Comma-separated ISO8601 datetime pair `after,before`; both bounds inclusive, either side may be empty (a bare `,` is rejected). No default — omit to skip this filter.
        in: query
        name: created_datetime
        required: false
        example: ?created_datetime=2026-01-01T00:00:00Z,2026-02-01T00:00:00Z
        schema:
          type: string
      - description: Keep only purchases last modified in the given range, by the record's last-updated timestamp. Comma-separated ISO8601 datetime pair `after,before`; both bounds inclusive, either side may be empty (a bare `,` is rejected). No default — omit to skip this filter.
        in: query
        name: updated_datetime
        required: false
        example: ?updated_datetime=2026-01-01T00:00:00Z,2026-02-01T00:00:00Z
        schema:
          type: string
      - description: Keep only purchases whose total is within the given range. Comma-separated `min,max` numeric pair; both bounds inclusive. Leave either side empty for an open-ended bound (e.g. `100,` for 100 and up). Compares against the same purchase total returned in each row's `amount`.
        in: query
        name: total
        required: false
        example: ?total=100,500
        schema:
          type: string
      - description: Keep only purchases whose paid amount is within the given range. Comma-separated `min,max` numeric pair; both bounds inclusive, either side may be empty for an open-ended bound. Matches on the sum of the purchase's non-voided payments — the same value returned in each row's `paid` — so a purchase with no payments counts as 0.
        in: query
        name: paid
        required: false
        example: ?paid=0,250
        schema:
          type: string
      - description: Keep only purchases whose purchase number contains the search term. Case-insensitive partial (substring) match on the purchase number, with matches ordered by closeness to the term. Omit to skip.
        in: query
        name: search
        required: false
        example: ?search=PO-1024
        schema:
          type: string
      - description: Keep only purchases from the given vendors, identified by Distru company-relationship ID (OR within the list). Omit to include every vendor.
        in: query
        name: company_relationship_ids
        required: false
        style: form
        explode: false
        schema:
          type: array
          items:
            type: string
      - description: Keep only purchases received into the given warehouse locations, by Distru location ID (OR within the list). Omit to include every location.
        in: query
        name: location_ids
        required: false
        style: form
        explode: false
        schema:
          type: array
          items:
            type: string
      - description: Keep only purchases owned by the given users, by Distru user ID (OR within the list). Omit to include every owner.
        in: query
        name: owner_ids
        required: false
        style: form
        explode: false
        schema:
          type: array
          items:
            type: string
      - description: Keep only purchases created by the given users, by Distru user ID (OR within the list). Omit to include every creator.
        in: query
        name: creator_ids
        required: false
        style: form
        explode: false
        schema:
          type: array
          items:
            type: string
      - description: Keep only purchases that include one of the given batches, by Distru batch ID (OR within the list).
        in: query
        name: batch_ids
        required: false
        style: form
        explode: false
        schema:
          type: array
          items:
            type: string
      - description: Keep only purchases that include one of the given products, by Distru product ID (OR within the list).
        in: query
        name: product_ids
        required: false
        style: form
        explode: false
        schema:
          type: array
          items:
            type: string
      responses:
        '200':
          description: The Purchase Order History report
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/PurchaseOrderHistoryReport'
        '400':
          description: Invalid parameters
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid API token
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: The API token lacks the required permission
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      summary: Get the Purchase Order History report
      tags:
      - PurchaseOrderHistory
components:
  schemas:
    ErrorResponse:
      description: The envelope returned by every failed request (400, 401, 403, 404, 429). `errors` always holds at least one entry.
      properties:
        errors:
          description: One or more errors describing why the request failed.
          items:
            $ref: '#/components/schemas/Error'
          type: array
      required:
      - errors
      title: ErrorResponse
      type: object
    PurchaseOrderHistoryReportRow:
      description: 'A single row of the Purchase Order History report. The keys below are always present; companies on a compliance integration see an additional manifest-number key (`metrc_manifest_number` or `biotrack_manifest_number`), and companies with Purchase custom fields see one extra key per field, slugified from its label. Read `meta.columns` for the exact key set of a given response.

        '
      properties:
        amount:
          description: The purchase total; 0 when the purchase has no line items.
          type: string
        due_date:
          description: The due date as an ISO8601 timestamp in the company's timezone; null when the purchase has no due date.
          type: string
        owner:
          description: The purchase owner's full name; null when no owner is assigned.
          type: string
        paid:
          description: Total amount paid on the purchase across its non-voided payments; 0 when nothing has been paid.
          type: string
        purchase_date:
          description: The purchase (order) date as an ISO8601 timestamp in the company's timezone; null when the purchase has no order date.
          type: string
        purchase_number:
          description: The purchase number.
          type: string
        purchase_order_id:
          description: The purchase's ID — the `id` [GET /public/v1/purchases](#get-purchases) returns.
          type: string
        purchase_order_owner_id:
          description: The purchase owner's ID — the `id` [GET /public/v1/users](#get-users) returns — or `null` when no owner is assigned.
          type: string
        status:
          description: The purchase status. One of PENDING, PROCESSING, DELIVERING, PARTIALLY_RECEIVED, COMPLETED — DRAFT never appears here.
          enum:
          - COMPLETED
          - DELIVERING
          - PENDING
          - PARTIALLY_RECEIVED
          - PROCESSING
          type: string
        vendor:
          description: The vendor (supplier) company name.
          type: string
        vendor_id:
          description: The vendor's company ID — the `id` [GET /public/v1/companies](#get-companies) returns and the value `company_relationship_ids` filters on.
          type: string
      required:
      - amount
      - paid
      - status
      - vendor_id
      - vendor
      - purchase_order_id
      - purchase_number
      title: PurchaseOrderHistoryReportRow
      type: object
    PurchaseOrderHistoryReport:
      description: The Purchase Order History report
      properties:
        data:
          description: The report rows
          items:
            $ref: '#/components/schemas/PurchaseOrderHistoryReportRow'
          type: array
        meta:
          $ref: '#/components/schemas/PurchaseOrderHistoryReportMeta'
      required:
      - meta
      - data
      title: PurchaseOrderHistoryReport
      type: object
    Error:
      description: A single error describing one problem with the request.
      properties:
        message:
          description: Human-readable, customer-facing description of what went wrong.
          type: string
        pointer:
          description: 'Path to the offending field in the request: field names and, for items in a list, their integer position — e.g. ["items", 0, "quantity"]. ["base"] means the error applies to the request as a whole rather than one field.'
          items: {}
          type: array
      required:
      - message
      - pointer
      title: Error
      type: object
    PurchaseOrderHistoryReportColumn:
      properties:
        key:
          description: The key this column is stored under in every data row (a slugified version of the label, e.g. `purchase_number`).
          type: string
        label:
          description: The human-readable column header, e.g. `Purchase Number`.
          type: string
      required:
      - label
      - key
      title: PurchaseOrderHistoryReportColumn
      type: object
    PurchaseOrderHistoryReportMeta:
      description: Report-level metadata
      properties:
        columns:
          description: 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.
          items:
            $ref: '#/components/schemas/PurchaseOrderHistoryReportColumn'
          type: array
        date_range:
          description: The human-readable date range the report covers, after the default 30-day range is applied when `order_datetime` is omitted.
          type: string
        report:
          description: The report identifier; always `purchase_order_history`.
          type: string
      required:
      - columns
      - date_range
      - report
      title: PurchaseOrderHistoryReportMeta
      type: object
  securitySchemes:
    Bearer:
      type: http
      scheme: bearer
      description: 'API token generated in Distru (Settings → Distru API). Send it on every request as `Authorization: Bearer YOUR_API_TOKEN`.'