Distru Order Fulfillment API

openapi: 3.2.0
info:
  license:
    name: Proprietary
    url: https://www.distru.com/legal/terms-of-service
  title: Distru Order Fulfillment API
  version: '1.0'
servers:
- url: https://app.distru.com
security:
- Bearer: []
tags:
- name: Order Fulfillment
paths:
  /public/v1/reports/order-fulfillment:
    get:
      description: 'Returns one row per product sold over the reported date range, pivoted across the matching sales orders: alongside the product''s group, category, and subcategory, each row carries one dynamic column per order (keyed by the slugified order number, e.g. `so_1042`) holding the net quantity of that product on that order, plus the product''s total units, unit price, and total value. This is a read-only reporting endpoint — it never changes orders, inventory, or compliance state.


        When no `order_datetime` filter is provided, the report defaults to the last 30 days: from the beginning of the day 30 days ago through the end of today, in the company''s timezone. Canceled and merged orders are always excluded from this report, so filtering `status` to CANCELED returns no rows.


        Every value is returned as it appears in the report''s CSV export, with numeric cells returned as strings (currency and comma formatting stripped) so they match the rest of the API. Because the per-order columns are dynamic, the exact set of keys on each row and in `meta.columns` depends on which orders match the filters; a product that was not on a given order leaves that order''s cell as an empty string (`""`). Report-level information (the resolved human-readable date range and the full column list) is returned under `meta`.


        Each row also carries its product''s ID, `product_id`, right after the product name, so a row can be followed to the product endpoints without a name lookup. The CSV export leaves this ID column out.


        Required permission: `reports_permissions_order_fulfillment`.'
      operationId: DistruPublic.V1.Report.OrderFulfillmentController.index
      parameters:
      - description: 'Restricts the report to orders whose order date falls in this range, given as two         ISO8601 timestamps separated by a comma: `after,before` (both bounds inclusive).         Either side may be left empty to leave that bound open-ended —         `2026-01-01T00:00:00Z,` keeps only the lower bound and leaves the upper bound         open, while `,2026-02-01T00:00:00Z` keeps only the upper bound and leaves the lower         bound open. Both sides empty (`order_datetime=,`) is rejected as invalid. Omit the         parameter entirely to get the default window: the last 30 days, from the start of         the day 30 days ago through the end of today, in the company''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: Restricts to orders in any of the given statuses (values are OR'd together).         SCREAMING_CASE. Canceled and merged orders are excluded from this report regardless         of this filter, so CANCELED yields no rows.
        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: Case-insensitive substring match on the order number, the customer's company         name, or the order's LeafLink short ID; an order is included when the text appears         in any of the three. Omit to apply no text filter.
        in: query
        name: search
        required: false
        schema:
          type: string
      - description: Restricts to orders for the given customers, identified by their company         relationship IDs (the ID of the buyer on the order). Multiple IDs are OR'd.
        in: query
        name: company_relationship_ids
        required: false
        style: form
        explode: false
        schema:
          type: array
          items:
            type: string
      - description: Restricts the report to these products, given as product IDs. Omit to include         every product sold in the range.
        in: query
        name: product_ids
        required: false
        style: form
        explode: false
        schema:
          type: array
          items:
            type: string
      - description: 'Restricts to order items fulfilled from these locations, identified by their         location IDs. Combined with `user_ids` using OR: an order item matches when its         location OR its user is in the respective list. Providing only `location_ids`         restricts to those locations; omitting both `location_ids` and `user_ids` applies no         location/user restriction.'
        in: query
        name: location_ids
        required: false
        style: form
        explode: false
        schema:
          type: array
          items:
            type: string
      - description: Restricts to order items assigned to these users, identified by their user         IDs. Combined with `location_ids` using OR (see `location_ids`). Providing only         `user_ids` restricts to those users; omitting both applies no location/user         restriction.
        in: query
        name: user_ids
        required: false
        style: form
        explode: false
        schema:
          type: array
          items:
            type: string
      - description: Restricts to orders owned by these sales reps, identified by their user IDs.         Multiple IDs are OR'd; omit to include orders from every owner.
        in: query
        name: owner_ids
        required: false
        style: form
        explode: false
        schema:
          type: array
          items:
            type: string
      responses:
        '200':
          description: The Order Fulfillment report
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/OrderFulfillmentReport'
        '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 Order Fulfillment report
      tags:
      - Order Fulfillment
components:
  schemas:
    OrderFulfillmentReportColumn:
      properties:
        key:
          description: The key under which this column's value appears in each data row. For a per-order column this is the slugified order number (e.g. `so_1042`).
          type: string
        label:
          description: The human-readable column label (e.g. the order number, or `Total Units`).
          type: string
      required:
      - label
      - key
      title: OrderFulfillmentReportColumn
      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
    OrderFulfillmentReport:
      description: The Order Fulfillment report
      properties:
        data:
          description: The report rows, one per product.
          items:
            $ref: '#/components/schemas/OrderFulfillmentReportRow'
          type: array
        meta:
          $ref: '#/components/schemas/OrderFulfillmentReportMeta'
      required:
      - meta
      - data
      title: OrderFulfillmentReport
      type: object
    OrderFulfillmentReportRow:
      description: 'A single row of the Order Fulfillment report (one product). In addition to the keys below, each row carries one dynamic key per matching order, named after the slugified order number (e.g. `so_1042`), whose value is the net quantity of this product on that order (order-item quantity minus returns), or an empty string (`""`) when this product was not on that order.

        '
      properties:
        category:
          description: The product's category name, or null when the product has no category.
          type: string
        group:
          description: The product's group name, or null when the product has no group.
          type: string
        product:
          description: The product name; inactive products carry a prefix marking them inactive. Always present — this is the pivot key each row is built around.
          type: string
        product_id:
          description: The product's ID — the `id` [GET /public/v1/products](#get-products) returns.
          type: string
        subcategory:
          description: The product's subcategory name, or null when the product has no subcategory.
          type: string
        total_units:
          description: Total units of this product sold across the matching orders, net of returns (summed order-item quantities minus return quantities).
          type: string
        total_value:
          description: Total value of this product across the matching orders, computed as the product's base `unit_price` × `total_units`. Because it uses the base unit price rather than the actual negotiated line prices, it may differ from the orders' real revenue when the orders applied custom pricing or discounts.
          type: string
        unit_price:
          description: The product's configured base unit price — taken from the product itself, not from any individual order line — so it is the same regardless of per-order pricing or discounts.
          type: string
      required:
      - total_value
      - unit_price
      - total_units
      - product_id
      - product
      title: OrderFulfillmentReportRow
      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
    OrderFulfillmentReportMeta:
      description: Report-level metadata
      properties:
        columns:
          description: 'The report''s column definitions in display order: the fixed product columns, one column per matching order, and the trailing Total Units / Unit Price / Total Value columns.'
          items:
            $ref: '#/components/schemas/OrderFulfillmentReportColumn'
          type: array
        date_range:
          description: The human-readable date range the report covers (the resolved default window, or the requested `order_datetime` range).
          type: string
        report:
          description: The report identifier; always `order_fulfillment` for this endpoint.
          type: string
      required:
      - columns
      - date_range
      - report
      title: OrderFulfillmentReportMeta
      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`.'