Distru Sales Order Tax API

openapi: 3.2.0
info:
  license:
    name: Proprietary
    url: https://www.distru.com/legal/terms-of-service
  title: Distru Sales Order Tax API
  version: '1.0'
servers:
- url: https://app.distru.com
security:
- Bearer: []
tags:
- name: SalesOrderTax
paths:
  /public/v1/reports/sales-order-tax:
    get:
      description: 'Returns the total tax collected across sales orders, aggregated by tax. Each row in `data` is one unique combination of tax name and tax rate, with `total_tax` summing every matching order''s charge of that tax. This is a read-only reporting endpoint — it does not create, modify, or sync anything, and has no effect on inventory, compliance, or the orders themselves.


        Which orders are counted is controlled entirely by the query filters below. Only charges flagged as taxes are summed; non-tax charges (fees, discounts) are excluded. Passing `tax_ids` narrows the sum to those specific taxes.


        • The `order_datetime` filter scopes the report by order date and is the only filter with a default: when omitted, the report covers the last 30 days, computed in the authenticated user''s timezone. Every other filter is additive and applies no default — omit it to leave that dimension unconstrained.

        • Rows are grouped independently by tax name and by tax rate, so the same tax name can appear on multiple rows if it was charged at different rates within the range.


        Numeric cells are returned as strings (currency and percent formatting stripped) so they match the rest of the API: `tax_rate` is a percentage value (e.g. `"27"` means 27%) and `total_tax` is a currency amount in the company''s currency. `meta` carries the resolved, human-readable date range and the report''s column definitions.


        Required permission: `reports_permissions_sales_order_tax`. Company admins are always authorized regardless of this permission.'
      operationId: DistruPublic.V1.Report.SalesOrderTaxController.index
      parameters:
      - description: Restrict the report to orders in any of the given statuses (SCREAMING_CASE). Repeat the key to pass several; an order matches if its status is any one of them. Omit to include every status.
        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: Restrict the report to orders with any of the given payment statuses (SCREAMING_CASE). Matches on any value listed. Omit to include all payment statuses.
        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: 'Restrict the report to orders created through any of the given sources (SCREAMING_CASE): LEAFLINK, EXTERNAL_BUYER, INTERNAL_USER, or API. Matches on any value listed. Omit to include all sources.'
        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: 'Restrict the report to orders whose order date falls in this range. Format is two comma-separated ISO8601 UTC datetimes, `after,before`. Either side may be left empty for an open-ended range (`2026-01-01T00:00:00Z,` = on or after that instant; `,2026-02-01T00:00:00Z` = up to that instant). This is the only filter with a default: when the whole param is omitted, the report covers the last 30 days in the authenticated user''s timezone.'
        in: query
        name: order_datetime
        required: false
        example: ?order_datetime=2026-01-01T00:00:00Z,2026-02-01T00:00:00Z
        schema:
          type: string
      - description: Restrict the report to orders whose delivery date falls in this range. Same `after,before` comma-separated ISO8601 UTC format as `order_datetime`; either side may be empty. No default — omit to leave delivery date unconstrained.
        in: query
        name: delivery_datetime
        required: false
        example: ?delivery_datetime=2026-01-01T00:00:00Z,2026-02-01T00:00:00Z
        schema:
          type: string
      - description: Restrict the report to orders whose due date falls in this range. Same `after,before` comma-separated ISO8601 UTC format as `order_datetime`; either side may be empty. No default.
        in: query
        name: due_datetime
        required: false
        example: ?due_datetime=2026-01-01T00:00:00Z,2026-02-01T00:00:00Z
        schema:
          type: string
      - description: Restrict the report to orders created (in Distru) within this range. Same `after,before` comma-separated ISO8601 UTC format as `order_datetime`; either side may be empty. No default. This is when the order record was created, independent of its order date.
        in: query
        name: created_datetime
        required: false
        example: ?created_datetime=2026-01-01T00:00:00Z,2026-02-01T00:00:00Z
        schema:
          type: string
      - description: Restrict the report to orders last modified within this range. Same `after,before` comma-separated ISO8601 UTC format as `order_datetime`; either side may be empty. No default.
        in: query
        name: updated_datetime
        required: false
        example: ?updated_datetime=2026-01-01T00:00:00Z,2026-02-01T00:00:00Z
        schema:
          type: string
      - description: Restrict the report to orders whose grand total falls within a range, given as two comma-separated decimal amounts `min,max` in the company's currency. Compared inclusively.
        in: query
        name: total
        required: false
        example: ?total=100,500
        schema:
          type: string
      - description: Restrict to orders by whether they are linked to a compliance (Metrc/BioTrack) transfer. `true` keeps only matched orders, `false` only unmatched. Omit to include both.
        in: query
        name: matched_with_compliance_transfer
        required: false
        schema:
          type: boolean
      - description: Free-text search restricting the report to orders whose order number, customer name, or LeafLink short ID contains the given text (case-insensitive substring). Omit for no text filter.
        in: query
        name: search
        required: false
        schema:
          type: string
      - description: Restrict the report to orders for any of the given customers, identified by their Distru company-relationship (customer) IDs. These are the IDs returned by the customers endpoint. Repeat the key to pass several; matches any. Omit to include all customers.
        in: query
        name: company_relationship_ids
        required: false
        style: form
        explode: false
        schema:
          type: array
          items:
            type: string
      - description: Restrict the report to orders whose customer belongs to any of the given customer-group IDs. Repeat the key to pass several; matches any. Omit for no group filter.
        in: query
        name: company_relationship_group_ids
        required: false
        style: form
        explode: false
        schema:
          type: array
          items:
            type: string
      - description: Restrict the report to orders shipped from any of the given license IDs. Repeat the key to pass several; matches any. Omit for no license filter.
        in: query
        name: shipped_from_license_ids
        required: false
        style: form
        explode: false
        schema:
          type: array
          items:
            type: string
      - description: Restrict the report to orders placed against any of the given menu IDs. Repeat the key to pass several; matches any. Omit for no menu filter.
        in: query
        name: menu_ids
        required: false
        style: form
        explode: false
        schema:
          type: array
          items:
            type: string
      - description: Restrict the report to orders containing a product of any of the given brand IDs. Repeat the key to pass several; matches any. Omit for no brand filter.
        in: query
        name: brand_ids
        required: false
        style: form
        explode: false
        schema:
          type: array
          items:
            type: string
      - description: Restrict the report to orders owned by any of the given user IDs. Repeat the key to pass several; matches any. Omit for no owner filter.
        in: query
        name: owner_ids
        required: false
        style: form
        explode: false
        schema:
          type: array
          items:
            type: string
      - description: Restrict the report to orders created by any of the given user IDs. Repeat the key to pass several; matches any. Omit for no creator filter.
        in: query
        name: creator_ids
        required: false
        style: form
        explode: false
        schema:
          type: array
          items:
            type: string
      - description: Restrict the report to orders containing any of the given batch IDs. Repeat the key to pass several; matches any. Omit for no batch filter.
        in: query
        name: batch_ids
        required: false
        style: form
        explode: false
        schema:
          type: array
          items:
            type: string
      - description: Restrict the report to orders containing any of the given product IDs. Repeat the key to pass several; matches any. Omit for no product filter.
        in: query
        name: product_ids
        required: false
        style: form
        explode: false
        schema:
          type: array
          items:
            type: string
      - description: Restrict the summed tax charges to the given tax IDs. Unlike the order filters, this narrows which taxes contribute to `total_tax` rather than which orders are counted. Repeat the key to pass several; matches any. Omit to sum every tax.
        in: query
        name: tax_ids
        required: false
        style: form
        explode: false
        schema:
          type: array
          items:
            type: string
      responses:
        '200':
          description: The Sales Order Tax report
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/SalesOrderTaxReport'
        '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 Tax report
      tags:
      - SalesOrderTax
components:
  schemas:
    SalesOrderTaxReportRow:
      description: 'A single aggregated row of the Sales Order Tax report: all matching orders'' charges for one unique tax name and rate, summed together.'
      properties:
        tax_rate:
          description: The tax rate as a percentage, e.g. `27` for 27%, rounded to at least 2 decimal places; ranges from -100 to 100. Null when the tax is a flat/fixed amount rather than a percentage.
          type: string
        tax_type:
          description: The name of the tax charge (e.g. "Cannabis Excise Tax"). May be null when the underlying tax charge has no name.
          type: string
        total_tax:
          description: Sum of this tax collected across every matching order, as a string in the company's currency. Always present and non-null; a row exists only when at least one matching tax charge was found, so this is the aggregated amount for that tax name and rate. When no orders match the filters at all, `data` is an empty array rather than a zero row.
          type: string
      required:
      - total_tax
      title: SalesOrderTaxReportRow
      type: object
    SalesOrderTaxReport:
      description: The Sales Order Tax report
      properties:
        data:
          description: The report rows
          items:
            $ref: '#/components/schemas/SalesOrderTaxReportRow'
          type: array
        meta:
          $ref: '#/components/schemas/SalesOrderTaxReportMeta'
      required:
      - meta
      - data
      title: SalesOrderTaxReport
      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
    SalesOrderTaxReportMeta:
      description: Report-level metadata
      properties:
        columns:
          description: The report's ordered column definitions, pairing each row key with its display label.
          items:
            $ref: '#/components/schemas/SalesOrderTaxReportColumn'
          type: array
        date_range:
          description: Human-readable label for the resolved order-date range the report covers (e.g. "Jul 21, 2026 to Aug 20, 2026"), rendered in the authenticated user's timezone. Reflects the default last-30-days window when `order_datetime` is omitted.
          type: string
        report:
          description: The report identifier; always `sales_order_tax` for this endpoint.
          type: string
      required:
      - columns
      - date_range
      - report
      title: SalesOrderTaxReportMeta
      type: object
    SalesOrderTaxReportColumn:
      properties:
        key:
          description: The key this column appears under in every `data` row (e.g. `total_tax`).
          type: string
        label:
          description: The human-readable column header (e.g. "Total Tax").
          type: string
      required:
      - label
      - key
      title: SalesOrderTaxReportColumn
      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`.'