Distru Inventory Valuation API

openapi: 3.2.0
info:
  license:
    name: Proprietary
    url: https://www.distru.com/legal/terms-of-service
  title: Distru Inventory Valuation API
  version: '1.0'
servers:
- url: https://app.distru.com
security:
- Bearer: []
tags:
- name: InventoryValuation
paths:
  /public/v1/reports/inventory-valuation:
    get:
      description: 'Returns one row per product with its current on-hand position — active, assembling, reserved, available, incoming, and pending-output quantities — alongside the product''s descriptive attributes (SKU, vendor, brand, unit type, category, subcategory, group, owner), its unit cost and price, its inventory alert thresholds, and its active inventory value. This is a read-only snapshot computed at request time; it never changes inventory, and does not touch compliance systems (Metrc/BioTrack). Use it to reconcile stock and value a company''s holdings, not to drive stock movements.


        Quantities are derived, not stored verbatim:

        • `available_quantity` is `active_quantity` minus `reserved_quantity`, and can be negative when reservations exceed on-hand stock.

        • `incoming_quantity` sums quantities on open (not-yet-received) purchases; `pending_output_quantity` sums the output still owed by open assemblies.

        • Active and assembling quantities count only inventory that is itself active. When `location_ids` and/or `user_ids` are supplied, the counted stock is narrowed to those locations and users (see those params).


        The active value is `active_quantity` × unit price by default. Pass `calculation_method=cost` to value it by unit cost instead; this also renames the value column (`active_value_price` becomes `active_value_cost`). A product with no unit cost set is valued at 0 under `cost` (unit price is always set, so `price` never hits this case).


        Every value is returned as it appears in the report''s CSV export, with numeric cells returned as strings (currency and comma formatting stripped, matching the rest of the API); a few identifier-like values with significant leading zeros keep their display string. Any Product custom fields configured for the company are appended as extra keys on each row (one per custom field), so the row shape varies by company. Report-level information (the resolved report date and column definitions) is returned under `meta`. All matching products are returned; there is no pagination. Rows come back ordered by `available_quantity`, highest first.


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


        Required permission: `reports_permissions_inventory_valuation`.'
      operationId: DistruPublic.V1.Report.InventoryValuationController.index
      parameters:
      - description: 'Keeps only products that match the term. Matching is case-insensitive: a product is kept when the term appears anywhere in its name or SKU, or when the term is a close fuzzy match on the name (so minor misspellings of the name still match). Omit (or pass empty) to return every product.'
        in: query
        name: search
        required: false
        example: ?search=Blue%20Dream
        schema:
          type: string
      - description: How to value active inventory. `price` (the default when omitted) values each product at `active_quantity` × unit price; `cost` values it at `active_quantity` × unit cost and renames the value column from `active_value_price` to `active_value_cost`. A product with no unit cost set is valued at 0 under `cost`.
        in: query
        name: calculation_method
        required: false
        schema:
          type: string
          enum:
          - cost
          - price
      - description: Narrows the active/assembling/reserved/incoming/pending-output stock counted to these locations. Values are Distru location IDs. Combined with `user_ids` as a union — stock counts if it sits at any listed location OR belongs to any listed user. Omit (or pass empty) to count stock across all locations.
        in: query
        name: location_ids
        required: false
        style: form
        explode: false
        schema:
          type: array
          items:
            type: string
      - description: Narrows the counted stock to inventory belonging to these users. Values are Distru user IDs. Combined with `location_ids` as a union (see that param). Omit (or pass empty) to count stock across all users.
        in: query
        name: user_ids
        required: false
        style: form
        explode: false
        schema:
          type: array
          items:
            type: string
      - description: Keeps only products supplied by these vendors. Values are Distru vendor IDs (the vendor company relationship). Omit (or pass empty) to include every vendor.
        in: query
        name: vendor_ids
        required: false
        style: form
        explode: false
        schema:
          type: array
          items:
            type: string
      - description: Keeps only products under these brands. Values are Distru brand IDs (the brand company relationship). Omit (or pass empty) to include every brand.
        in: query
        name: brand_ids
        required: false
        style: form
        explode: false
        schema:
          type: array
          items:
            type: string
      responses:
        '200':
          description: The Inventory Valuation report
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/InventoryValuationReport'
        '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 Inventory Valuation report
      tags:
      - InventoryValuation
components:
  schemas:
    InventoryValuationReport:
      description: The Inventory Valuation report
      properties:
        data:
          description: The report rows
          items:
            $ref: '#/components/schemas/InventoryValuationReportRow'
          type: array
        meta:
          $ref: '#/components/schemas/InventoryValuationReportMeta'
      required:
      - meta
      - data
      title: InventoryValuationReport
      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
    InventoryValuationReportRow:
      description: 'A single row of the Inventory Valuation report (one product). Companies with Product custom fields will see additional keys. When `calculation_method=cost`, the `active_value_price` key is returned as `active_value_cost` instead.

        '
      properties:
        active_quantity:
          description: The active on-hand quantity, counting only active inventory in the requested locations/users. Defaults to 0 when the product has no active stock.
          type: string
        active_value_price:
          description: '`active_quantity` × unit price. Present only under the default `calculation_method=price`; when `calculation_method=cost`, this key is replaced by `active_value_cost` (`active_quantity` × unit cost, using 0 when unit cost is null).'
          type: string
        assembling_quantity:
          description: The quantity currently reserved inside in-progress assemblies. 0 when none.
          type: string
        available_quantity:
          description: '`active_quantity` minus `reserved_quantity`. Can be negative when reservations exceed on-hand stock.'
          type: string
        brand:
          description: The name of the product's brand, or null when it has none
          type: string
        brand_id:
          description: The brand's company ID — the `id` [GET /public/v1/companies](#get-companies) returns — or null when the product has no brand.
          type: string
        category:
          description: The product's category, or null when it has none
          type: string
        group:
          description: The product's group, or null when it has none
          type: string
        image_url:
          description: URL of the product's thumbnail image, or null when it has no image
          type: string
        incoming_quantity:
          description: The quantity on open (not-yet-received) purchases. 0 when none.
          type: string
        inventory_threshold_max:
          description: The product's inventory alert maximum, or null when no threshold is set
          type: string
        inventory_threshold_min:
          description: The product's inventory alert minimum, or null when no threshold is set
          type: string
        name:
          description: The product name. Inactive products are prefixed to mark them.
          type: string
        owner:
          description: The full name of the product's owner, or null when unassigned
          type: string
        pending_output_quantity:
          description: The output quantity still owed by open assemblies. 0 when none.
          type: string
        product_id:
          description: The product's ID — the `id` [GET /public/v1/products](#get-products) returns.
          type: string
        reserved_quantity:
          description: The quantity reserved against open sales orders. 0 when none.
          type: string
        sku:
          description: The product SKU
          type: string
        subcategory:
          description: The product's subcategory, or null when it has none
          type: string
        unit_cost:
          description: The product's unit cost, or null when no cost is set. Used for the value column when `calculation_method=cost`.
          type: string
        unit_price:
          description: The product's unit price. Used for the value column by default (`calculation_method=price`).
          type: string
        unit_type:
          description: The product's unit of measure (e.g. `Each`, `Gram`)
          type: string
        vendor:
          description: The name of the product's vendor
          type: string
        vendor_id:
          description: The vendor's company ID — the `id` [GET /public/v1/companies](#get-companies) returns.
          type: string
      required:
      - unit_price
      - pending_output_quantity
      - incoming_quantity
      - available_quantity
      - reserved_quantity
      - assembling_quantity
      - active_quantity
      - unit_type
      - vendor_id
      - vendor
      - sku
      - product_id
      - name
      title: InventoryValuationReportRow
      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
    InventoryValuationReportColumn:
      properties:
        key:
          description: The key used for this column in each data row
          type: string
        label:
          description: The human-readable label of the column
          type: string
      required:
      - label
      - key
      title: InventoryValuationReportColumn
      type: object
    InventoryValuationReportMeta:
      description: Report-level metadata
      properties:
        columns:
          description: The ordered column definitions for the rows in `data`, including one entry per Product custom field. The value column key reflects `calculation_method` (`active_value_price` or `active_value_cost`).
          items:
            $ref: '#/components/schemas/InventoryValuationReportColumn'
          type: array
        date_range:
          description: Human-readable date the report was generated, in the company's timezone. Despite               the name this is the generation timestamp, not a filtered date range — inventory               valuation is a point-in-time snapshot with no date-range filter.
          type: string
        report:
          description: The report identifier (always `inventory_valuation`)
          type: string
      required:
      - columns
      - date_range
      - report
      title: InventoryValuationReportMeta
      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`.'