Distru Purchases By Company API

openapi: 3.2.0
info:
  license:
    name: Proprietary
    url: https://www.distru.com/legal/terms-of-service
  title: Distru Purchases By Company API
  version: '1.0'
servers:
- url: https://app.distru.com
security:
- Bearer: []
tags:
- name: PurchasesByCompany
paths:
  /public/v1/reports/purchases-by-company:
    get:
      description: 'Returns the Purchases By Company report: one row per vendor (a company relationship where your company buys from a related company) summarizing purchasing activity over a date range. Each row carries the vendor''s most recent purchase date, the number of purchases counted, and the total amount spent.


        Which vendors appear:

        • Only vendors with at least one non-draft purchase matching the filters (the date range plus any `owner_ids` filter) are included; a vendor with no qualifying purchases in the range is omitted entirely.

        • Draft purchases are never counted, and purchases you lack permission to view (team visibility) are excluded from the counts and totals.


        Behaviors worth noting:

        • `last_purchase_date` is the vendor''s most recent non-draft purchase across all time — it is NOT restricted to the reported date range, so it can fall outside the range you filtered on.

        • `purchase_order_count` and `total_purchases` are computed only over the purchases inside the date range (and matching the `owner_ids` filter).

        • When no date filter is provided, the report defaults to the last 30 days. All date bounds are interpreted in your company''s timezone.


        Every value is returned as it appears in the report''s CSV export: numeric cells are returned as strings (currency and comma formatting stripped, matching the rest of the API) and date cells stay formatted strings. Any CompanyRelationship custom fields configured for your company are appended as extra columns on each row and listed in `meta.columns`. The resolved date range and the report''s column definitions are returned under `meta`.


        Each row also carries the IDs of the records it names — `vendor_id` and `vendor_owner_id`, each right after its name column — so a row can be followed to the company or user endpoints without a name lookup. The CSV export leaves these ID columns out.


        Required permission: `reports_permissions_purchases_by_company`.'
      operationId: DistruPublic.V1.Report.PurchasesByCompanyController.index
      parameters:
      - description: 'Restrict the counted purchases to those whose order date falls in this range. The value is two comma-separated ISO8601 timestamps, `after,before`, and the range is inclusive on both ends. Either side may be left empty for an open-ended range: `2026-01-01T00:00:00Z,` counts everything from that instant onward and `,2026-02-01T00:00:00Z` everything up to it (both sides empty is rejected). Bounds are evaluated in your company''s timezone. When omitted, the report covers the last 30 days. This only bounds the aggregated `purchase_order_count` and `total_purchases` — `last_purchase_date` always reflects the vendor''s most recent non-draft purchase regardless of this filter.

          '
        in: query
        name: order_datetime
        required: false
        example: ?order_datetime=2026-01-01T00:00:00Z,2026-02-01T00:00:00Z
        schema:
          type: string
      - description: 'Case-insensitive substring match on the vendor''s related company name or its legal business name; only vendors that contain the term in either are returned. Omit to list all vendors.

          '
        in: query
        name: search
        required: false
        example: ?search=green
        schema:
          type: string
      - description: 'Filter to vendors belonging to any of these vendor group ids (match-any / OR). Each id is a Distru vendor group id. Repeat the bracketed key once per value. Omit or send an empty list to apply no group filter.

          '
        in: query
        name: company_relationship_group_ids
        required: false
        style: form
        explode: false
        schema:
          type: array
          items:
            type: string
      - description: 'Filter the counted purchases to those owned by any of these purchase owners / sales reps (match-any / OR). Each id is a Distru user id. Because this filters the purchases themselves, it also narrows which vendors appear: a vendor is listed only if it has non-draft purchases in the range owned by one of these reps, and its `purchase_order_count` and `total_purchases` reflect only those purchases. Repeat the bracketed key once per value. Omit or send an empty list to include all owners.

          '
        in: query
        name: owner_ids
        required: false
        style: form
        explode: false
        schema:
          type: array
          items:
            type: string
      responses:
        '200':
          description: The Purchases By Company report
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/PurchasesByCompanyReport'
        '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 Purchases By Company report
      tags:
      - PurchasesByCompany
components:
  schemas:
    PurchasesByCompanyReportMeta:
      description: Report-level metadata
      properties:
        columns:
          description: 'Ordered column definitions for the rows in `data`, including any appended CompanyRelationship custom-field columns. Always present.

            '
          items:
            $ref: '#/components/schemas/PurchasesByCompanyReportColumn'
          type: array
        date_range:
          description: 'Human-readable label of the date range the report covers, derived from the `order_datetime` filter, or the default last-30-days window when that filter is omitted. Always present.

            '
          type: string
        report:
          description: The report identifier, always `purchases_by_company`.
          type: string
      required:
      - columns
      - date_range
      - report
      title: PurchasesByCompanyReportMeta
      type: object
    PurchasesByCompanyReport:
      description: The Purchases By Company report
      properties:
        data:
          description: The report rows
          items:
            $ref: '#/components/schemas/PurchasesByCompanyReportRow'
          type: array
        meta:
          $ref: '#/components/schemas/PurchasesByCompanyReportMeta'
      required:
      - meta
      - data
      title: PurchasesByCompanyReport
      type: object
    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
    PurchasesByCompanyReportRow:
      description: 'A single row of the Purchases By Company report. If your company has CompanyRelationship custom fields configured, each is appended as an additional key on every row (keyed by the slugified field label, listed in `meta.columns`).

        '
      properties:
        category:
          description: The related company's category, or null when the company has no category set.
          type: string
        last_purchase_date:
          description: 'Date of the vendor''s most recent non-draft purchase, formatted `M/D/YYYY` in your company''s timezone (month and day are not zero-padded, e.g. `8/5/2026`). This is the latest purchase across all time, not limited to the reported date range. An empty string `""` when that purchase has no order date recorded.

            '
          type: string
        name:
          description: The vendor's related company name. Always present.
          type: string
        product_owner:
          description: Full name of the sales rep assigned to this vendor, or null when no owner is assigned.
          type: string
        purchase_order_count:
          description: 'Number of non-draft purchases counted for this vendor within the reported date range (and matching the `owner_ids` filter). Always at least 1, since vendors with no qualifying purchases are omitted.

            '
          type: string
        relationship_type:
          description: The vendor's relationship type name, or null when none is assigned.
          type: string
        total_purchases:
          description: 'Total amount spent across the counted purchases, in your company''s currency, summed over the reported date range (and `owner_ids` filter). Never null; a vendor whose purchases all total zero reports 0.

            '
          type: string
        vendor_id:
          description: The vendor's company ID — the `id` [GET /public/v1/companies](#get-companies) returns.
          type: string
        vendor_owner_id:
          description: The ID of the sales rep assigned to this vendor — the `id` [GET /public/v1/users](#get-users) returns — or null when no owner is assigned.
          type: string
      required:
      - total_purchases
      - purchase_order_count
      - vendor_id
      - name
      title: PurchasesByCompanyReportRow
      type: object
    PurchasesByCompanyReportColumn:
      properties:
        key:
          description: The key this column appears under on every data row (the slugified label).
          type: string
        label:
          description: The human-readable label of the column.
          type: string
      required:
      - label
      - key
      title: PurchasesByCompanyReportColumn
      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
  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`.'