Distru Sales Order History API

openapi: 3.2.0
info:
  license:
    name: Proprietary
    url: https://www.distru.com/legal/terms-of-service
  title: Distru Sales Order History API
  version: '1.0'
servers:
- url: https://app.distru.com
security:
- Bearer: []
tags:
- name: SalesOrderHistory
paths:
  /public/v1/reports/sales-order-history:
    get:
      description: 'Returns one row per sales order — its dates, customer, status, owner, and monetary totals (paid, outstanding, subtotal, taxes, discounts, charges, returns, and grand total). This is a read-only report: it never creates, changes, or deletes orders, inventory, payments, or compliance records, and has no effect on Metrc or BioTrack. Use it to reconcile order value and payment state across a date window; do not use it to fetch a single order''s line items (use the Orders endpoints for that).


        When no `order_datetime` filter is supplied the report defaults to orders whose order date falls in the last 30 days. All other date filters (`delivery_datetime`, `due_datetime`, `created_datetime`, `updated_datetime`) have no default — omitting them applies no bound on that field. Multiple filters combine with AND; repeated values within one array filter combine with OR.


        This endpoint is not paginated: it returns every order matching the filters in a single response, and there is no `next_page` link. A wide date window can therefore produce a large payload, so narrow the date filters to bound the result set. Unlike the report''s own UI export, the response carries only order rows — there is no trailing "Total" summary row.


        Every cell is returned as it appears in the report''s CSV export. Values that look numeric (the monetary columns) are returned as strings (currency and comma formatting stripped) so they match the rest of the API; everything else stays a string too. A value whose numeric part has a leading zero (for example an order number like `"0042"`) keeps its full display string so the leading zeros are not lost. Date cells are display-formatted strings in the resolved format, not ISO8601, and each date is returned twice — once in the company''s timezone and once in UTC.


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


        Companies on a compliance integration receive two extra columns — a manifest number (labeled per the active system, Metrc or BioTrack) and the shipped-from license — appended after the standard columns. Any Order custom fields configured for the company are appended after those, keyed by the slugified custom field label. The `meta` object echoes the resolved human-readable date range and the full ordered list of column definitions (each with its response `key` and display `label`), so an integrator can map dynamic keys without hardcoding them.


        Requires the "view the sales order history report" permission on the API key.'
      operationId: DistruPublic.V1.Report.SalesOrderHistoryController.index
      parameters:
      - description: Filter to orders whose status is any of the given values (OR). Omit for no status filter. SCREAMING_CASE; one of PENDING, PROCESSING, READY_TO_SHIP, DELIVERING, DELIVERED, COMPLETED, CANCELED.
        in: query
        name: status
        required: false
        style: form
        explode: false
        schema:
          type: array
          items:
            enum:
            - PENDING
            - PROCESSING
            - READY_TO_SHIP
            - DELIVERING
            - DELIVERED
            - COMPLETED
            - CANCELED
            type: string
      - description: Filter to orders whose payment status is any of the given values (OR). Omit for no payment filter. SCREAMING_CASE; one of NOT_PAID, PARTIALLY_PAID, FULLY_PAID, OVER_PAID.
        in: query
        name: payment_status
        required: false
        style: form
        explode: false
        schema:
          type: array
          items:
            enum:
            - NOT_PAID
            - PARTIALLY_PAID
            - FULLY_PAID
            - OVER_PAID
            type: string
      - description: Filter to orders created through any of the given sources (OR). Omit for no source filter. SCREAMING_CASE; one of LEAFLINK, EXTERNAL_BUYER, INTERNAL_USER, API.
        in: query
        name: order_source
        required: false
        style: form
        explode: false
        schema:
          type: array
          items:
            enum:
            - LEAFLINK
            - EXTERNAL_BUYER
            - INTERNAL_USER
            - API
            type: string
      - description: 'Filter by order date, as a comma-separated `after,before` pair of ISO8601 UTC timestamps. Either side may be blank for an open-ended bound: `2026-01-01T00:00:00Z,` matches on/after Jan 1, `,2026-02-01T00:00:00Z` matches before Feb 1. When this param is omitted the report falls back to the last 30 days of order dates; supplying it overrides that default.'
        in: query
        name: order_datetime
        required: false
        example: 2026-01-01T00:00:00Z,2026-02-01T00:00:00Z
        schema:
          type: string
      - description: Filter by delivery date, as a comma-separated `after,before` pair of ISO8601 UTC timestamps; either side may be blank for an open-ended bound. No default when omitted.
        in: query
        name: delivery_datetime
        required: false
        example: 2026-01-01T00:00:00Z,2026-02-01T00:00:00Z
        schema:
          type: string
      - description: Filter by due date, as a comma-separated `after,before` pair of ISO8601 UTC timestamps; either side may be blank for an open-ended bound. No default when omitted.
        in: query
        name: due_datetime
        required: false
        example: 2026-01-01T00:00:00Z,2026-02-01T00:00:00Z
        schema:
          type: string
      - description: Filter by the order's creation timestamp, as a comma-separated `after,before` pair of ISO8601 UTC timestamps; either side may be blank for an open-ended bound. No default when omitted.
        in: query
        name: created_datetime
        required: false
        example: 2026-01-01T00:00:00Z,2026-02-01T00:00:00Z
        schema:
          type: string
      - description: Filter by the order's last-modified timestamp, as a comma-separated `after,before` pair of ISO8601 UTC timestamps; either side may be blank for an open-ended bound. No default when omitted.
        in: query
        name: updated_datetime
        required: false
        example: 2026-01-01T00:00:00Z,2026-02-01T00:00:00Z
        schema:
          type: string
      - description: Filter by the order grand total, as a comma-separated `min,max` numeric range (inclusive). Either side may be blank for an open-ended bound (e.g. `100,` for totals >= 100).
        in: query
        name: total
        required: false
        example: 100,500
        schema:
          type: string
      - description: Filter by whether the order is matched to a compliance (Metrc/BioTrack) transfer. `true` returns only matched orders, `false` only unmatched; omit to include both.
        in: query
        name: matched_with_compliance_transfer
        required: false
        example: true
        schema:
          type: boolean
      - description: Case-insensitive substring match against the order number, the customer name, and the LeafLink short ID (any one matching returns the order). Omit for no text search.
        in: query
        name: search
        required: false
        example: SO-1024
        schema:
          type: string
      - description: Filter to orders for any of these customers, identified by their company relationship IDs (OR).
        in: query
        name: company_relationship_ids
        required: false
        style: form
        explode: false
        schema:
          type: array
          items:
            type: string
      - description: Filter to orders whose customer belongs to any of these customer groups, by group ID (OR).
        in: query
        name: company_relationship_group_ids
        required: false
        style: form
        explode: false
        schema:
          type: array
          items:
            type: string
      - description: Filter to orders shipped from any of these licenses, by license ID (OR).
        in: query
        name: shipped_from_license_ids
        required: false
        style: form
        explode: false
        schema:
          type: array
          items:
            type: string
      - description: Filter to orders placed against any of these menus, by menu ID (OR).
        in: query
        name: menu_ids
        required: false
        style: form
        explode: false
        schema:
          type: array
          items:
            type: string
      - description: Filter to orders containing a product of any of these brands, by brand ID (OR).
        in: query
        name: brand_ids
        required: false
        style: form
        explode: false
        schema:
          type: array
          items:
            type: string
      - description: Filter to orders owned by any of these users, by user ID (OR).
        in: query
        name: owner_ids
        required: false
        style: form
        explode: false
        schema:
          type: array
          items:
            type: string
      - description: Filter to orders created by any of these users, by user ID (OR).
        in: query
        name: creator_ids
        required: false
        style: form
        explode: false
        schema:
          type: array
          items:
            type: string
      - description: Filter to orders containing any of these batches, by batch ID (OR).
        in: query
        name: batch_ids
        required: false
        style: form
        explode: false
        schema:
          type: array
          items:
            type: string
      - description: Filter to orders containing any of these products, by product ID (OR). Unlike the other ID filters, these are the same id returned as a product's `id` elsewhere in the API.
        in: query
        name: product_ids
        required: false
        style: form
        explode: false
        schema:
          type: array
          items:
            type: string
      responses:
        '200':
          description: The Sales Order History report
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/SalesOrderHistoryReport'
        '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 Sales Order History report
      tags:
      - SalesOrderHistory
components:
  schemas:
    SalesOrderHistoryReportColumn:
      properties:
        key:
          description: The slugified key this column uses in every data row map (e.g. "order_date", "discounts_taxes_not_included"). Use it to read the corresponding value from each row.
          type: string
        label:
          description: The human-readable column label as shown in the CSV export (e.g. "Order Date", "Discounts (taxes not included)")
          type: string
      required:
      - label
      - key
      title: SalesOrderHistoryReportColumn
      type: object
    SalesOrderHistoryReportRow:
      description: 'A single sales order in the report. Monetary columns are returned as JSON numbers; date and text columns are strings. Companies on a compliance integration see two extra keys — `manifest_number` (the Metrc or BioTrack manifest number, whichever system is active) and `shipped_from_license` — and companies with Order custom fields see one extra key per field, named by the slugified custom field label. Use the `key` values under `meta.columns` to map these dynamic keys without hardcoding them.

        '
      properties:
        charges_taxes_not_included:
          description: Total non-tax charges on the order, excluding taxes; 0 when none
          type: string
        customer:
          description: The customer (company relationship) name, or `null` when the order has no linked customer.
          type: string
        customer_id:
          description: The customer's company ID — the `id` [GET /public/v1/companies](#get-companies) returns and the value `company_relationship_ids` filters on — or `null` when the order has no linked customer.
          type: string
        delivery_date:
          description: The delivery date as a display-formatted string in the company's timezone, or `null` when the order has no delivery date.
          type: string
        delivery_date_utc:
          description: The same delivery date in UTC, or `null` when the order has no delivery date.
          type: string
        discounts_taxes_not_included:
          description: Total discounts applied to the order, excluding taxes; 0 when none
          type: string
        due_date:
          description: The due date as a display-formatted string in the company's timezone. Always present — every order has a due date (enforced on write).
          type: string
        due_date_utc:
          description: The same due date in UTC. Always present.
          type: string
        menu:
          description: The name of the menu the order was placed through, or `null` when the order was not placed through a menu. Companies without DistruCommerce do not receive this column.
          type: string
        order_date:
          description: The order date as a display-formatted string in the company's timezone, e.g. "01/15/2026" (not ISO8601)
          type: string
        order_date_utc:
          description: The same order date as a display-formatted string in UTC
          type: string
        order_number:
          description: The order number, always returned as a string; even a purely numeric order number stays a string, and one with non-digit characters or a significant leading zero (e.g. "0042") keeps its full display string so the zero isn't lost.
          type: string
        order_source:
          description: How the order was created, as a SCREAMING_CASE token. Always present.
          enum:
          - LEAFLINK
          - EXTERNAL_BUYER
          - INTERNAL_USER
          - API
          type: string
        outstanding:
          description: 'Unpaid balance: total minus returns minus payments; 0 when fully settled'
          type: string
        owner:
          description: The order owner's name, or `null` when the order has no owner.
          type: string
        paid:
          description: Total payments applied to the order; 0 when none
          type: string
        returns:
          description: Total value of returns against the order; 0 when none
          type: string
        sales_order_id:
          description: The order's ID — the `id` [GET /public/v1/orders](#get-orders) returns.
          type: string
        sales_order_owner_id:
          description: The order owner's ID — the `id` [GET /public/v1/users](#get-users) returns — or `null` when the order has no owner.
          type: string
        status:
          description: The order status in SCREAMING_CASE. A rare internal status the public API does not expose (e.g. a merged order) is returned as its raw internal string. Always present.
          enum:
          - PENDING
          - PROCESSING
          - READY_TO_SHIP
          - DELIVERING
          - DELIVERED
          - COMPLETED
          - CANCELED
          type: string
        subtotal:
          description: Sum of the order's line-item quantity times price, before taxes, charges, and discounts; 0 when the order has no items
          type: string
        taxes:
          description: Total tax charges on the order; 0 when none
          type: string
        total:
          description: The order grand total (subtotal plus charges and taxes, minus discounts); 0 when the order is empty
          type: string
      required:
      - order_source
      - total
      - returns
      - charges_taxes_not_included
      - discounts_taxes_not_included
      - taxes
      - subtotal
      - outstanding
      - paid
      - status
      - sales_order_id
      - order_number
      - due_date_utc
      - due_date
      - order_date_utc
      - order_date
      title: SalesOrderHistoryReportRow
      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
    SalesOrderHistoryReport:
      description: The Sales Order History report
      properties:
        data:
          description: The report rows
          items:
            $ref: '#/components/schemas/SalesOrderHistoryReportRow'
          type: array
        meta:
          $ref: '#/components/schemas/SalesOrderHistoryReportMeta'
      required:
      - meta
      - data
      title: SalesOrderHistoryReport
      type: object
    SalesOrderHistoryReportMeta:
      description: Report-level metadata
      properties:
        columns:
          description: The ordered column definitions for this response, including any compliance and custom-field columns present for the company. Each entry pairs the row `key` with its display `label`.
          items:
            $ref: '#/components/schemas/SalesOrderHistoryReportColumn'
          type: array
        date_range:
          description: The human-readable date range the report covers, reflecting the resolved `order_datetime` filter (or the last-30-days default when none was given)
          type: string
        report:
          description: The report identifier; always "sales_order_history"
          type: string
      required:
      - columns
      - date_range
      - report
      title: SalesOrderHistoryReportMeta
      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`.'