Distru Product Group API

openapi: 3.2.0
info:
  license:
    name: Proprietary
    url: https://www.distru.com/legal/terms-of-service
  title: Distru Product Group API
  version: '1.0'
servers:
- url: https://app.distru.com
security:
- Bearer: []
tags:
- name: Product Group
paths:
  /public/v1/product-groups:
    get:
      description: 'Lists the authenticated company''s product groups, oldest first (ordered by creation time

        ascending). Product groups are the categories a product can belong to: each product references

        at most one group, and groups are also used as targeting or exclusion filters on price tiers.


        Results are paginated. When more rows exist the response includes a

        `next_page` URL to fetch the following page; `next_page` is null on the last page. Page size is

        fixed by the server and is not client-controllable. Filter the list

        by the `inserted_datetime` and `updated_datetime` ranges.


        Required permission: `settings_permissions_product_groups`.'
      operationId: DistruPublic.V1.ProductGroupController.index
      parameters:
      - description: Restrict the result to specific product groups by ID (the same ID returned as each group's `id`). Repeat the bracketed key once per ID. Unknown IDs simply match nothing; an empty list is treated as no filter. At most 200 IDs may be given.
        in: query
        name: ids
        required: false
        style: form
        explode: false
        schema:
          type: array
          items:
            type: string
      - description: 'Filter to product groups by their creation datetime, given as a comma-separated `start,end` pair of ISO8601 datetimes (inclusive). Either bound may be omitted for an open-ended range: `2022-07-10T00:00:00Z,` matches on or after that instant, `,2022-07-10T00:00:00Z` matches on or before it.'
        in: query
        name: inserted_datetime
        required: false
        example: ?inserted_datetime=2022-07-10T00:00:00Z,2022-07-31T00:00:00Z
        schema:
          type: string
      - description: Filter to product groups by their last-updated datetime, given as a comma-separated `start,end` pair of ISO8601 datetimes (inclusive). Either bound may be omitted for an open-ended range.
        in: query
        name: updated_datetime
        required: false
        example: ?updated_datetime=2022-07-10T00:00:00Z,2022-07-31T00:00:00Z
        schema:
          type: string
      - description: Page selector. Page size is fixed by the server; paginate by following the `next_page` URL in each response rather than building page selectors yourself — it is null on the last page. `next_page` uses `page[after]=<cursor>`, an opaque token marking where the next page resumes; pass it back exactly as given, and only to the endpoint that issued it. This is seek-based, so every page stays fast no matter how deep you page.
        in: query
        name: page
        required: false
        example: ?page[after]=cursor
        schema:
          type: string
      responses:
        '200':
          description: A list of product groups
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProductGroups'
        '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'
        '429':
          description: Too Many Requests — the account's list rate limit (3000 calls, refilling at 5 per minute, one per page) was exceeded. Retry after the period in the Retry-After header. Calls with an `updated_datetime` lower bound within the last 30 days are free and never refused; see [Incremental Sync](#incremental-sync).
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      summary: Get product groups
      tags:
      - Product Group
    post:
      description: 'Creates or updates a single product group. Pass `id` to update the matching group; omit `id`

        to create a new one. A create returns 201, an update returns 200.


        `name` is the only editable field and is required on both create and update; the update

        replaces the group''s name. A group''s name must be unique within the company, compared

        case-insensitively (`Flower` and `flower` collide) — a duplicate is rejected with a 400. The

        name may contain only letters, digits, spaces, underscores, and the characters

        `~ # - $ / | % & '' ( ) .`; any other special character, and two colons in a row (`::`), are

        rejected with a 400.


        Assigning products to a group is not done here: a product''s group is set on the product itself,

        not on this endpoint. This endpoint only defines the group''s identity.


        Required permission: `settings_permissions_product_groups`.'
      operationId: DistruPublic.V1.ProductGroupController.upsert
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                id:
                  type: string
                  description: The Distru ID of the product group to update, as returned in a product group response. Present updates that group; absent creates a new one.
                name:
                  type: string
                  description: 'The group''s display name. Required on both create and update. Must be unique within the company, compared case-insensitively (`Flower` and `flower` collide). May contain only letters, digits, spaces, underscores, and the characters `~ # - $ / | % & '' ( ) .`; any other special character, and two colons in a row (`::`), are rejected with a 400.'
              required:
              - name
        required: true
      responses:
        '200':
          description: The updated product group
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProductGroupResponse'
        '201':
          description: The created product group
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProductGroupResponse'
        '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'
        '404':
          description: Not Found
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      summary: Upsert a product group
      tags:
      - Product Group
  /public/v1/product-groups/{id}:
    delete:
      description: 'Permanently deletes the product group. This is a hard delete: the record is removed and cannot

        be recovered. Returns 404 if no group with that ID belongs to the company.


        Deleting a group ripples to everything that referenced it:

        • Products in this group are un-grouped — their group becomes empty. The products themselves are

        not deleted.

        • The group is dropped from any menus that featured it as a collection.

        • Any price tier that targeted or excluded this group has that condition removed, which changes

        which products those price tiers apply to.


        Required permission: `settings_permissions_product_groups`.'
      operationId: DistruPublic.V1.ProductGroupController.delete
      parameters:
      - description: The product group's Distru ID, as returned in the `id` field of any product group response.
        in: path
        name: id
        required: true
        schema:
          type: string
      responses:
        '204':
          description: No Content
        '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'
        '404':
          description: Not Found
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      summary: Delete a product group
      tags:
      - Product Group
    get:
      description: 'Fetches a single product group by its ID, scoped to the authenticated company. Returns 404 if

        no group with that ID belongs to the company.


        Required permission: `settings_permissions_product_groups`.'
      operationId: DistruPublic.V1.ProductGroupController.show
      parameters:
      - description: The product group's Distru ID, as returned in the `id` field of any product group response.
        in: path
        name: id
        required: true
        schema:
          type: string
      responses:
        '200':
          description: A single product group
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProductGroupResponse'
        '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'
        '404':
          description: Not Found
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      summary: Get a product group
      tags:
      - Product Group
components:
  schemas:
    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
    ProductGroup:
      description: A product group
      properties:
        id:
          description: The product group's Distru ID. Stable for the life of the group; use it to fetch, update, or delete the group.
          type: string
        inserted_datetime:
          description: When the product group was created, as a UTC ISO-8601 timestamp (e.g. `2026-08-20T14:03:00Z`).
          type: string
        name:
          description: The group's display name. Unique within the company (case-insensitive).
          type: string
        updated_datetime:
          description: When the product group was last updated, as a UTC ISO-8601 timestamp. Equals `inserted_datetime` until the group is first edited.
          type: string
      required:
      - updated_datetime
      - inserted_datetime
      - name
      - id
      title: ProductGroup
      type: object
    ProductGroups:
      description: A collection of product groups
      properties:
        data:
          description: Product Groups
          items:
            $ref: '#/components/schemas/ProductGroup'
          type: array
        next_page:
          description: URL for the next page of results; null when there is no next page
          type: string
      title: Product Groups
      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
    ProductGroupResponse:
      description: A single product group
      properties:
        data:
          $ref: '#/components/schemas/ProductGroup'
      title: Product Group Response
      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`.'