Product Groups

Product groups let you manage a set of related products as one catalog unit. You can use them to control contract windows, activation state, publishing windows, and booking expiry settings across multiple products.

In practice, a product group helps you organise products that should follow the same commercial rules. This is useful when you want consistent configuration for a cohort of products instead of updating each product one by one.

Key Concepts

Contract windows

Each product group has contract date boundaries:

• contractEarliestStartDate

• contractLatestStartDate

• contractEarliestEndDate

• contractLatestEndDate

These dates define the range of contract dates that products in the group can use.

State and publishing

A product group has two related controls:

• Activation state (ACTIVE, INACTIVE)

• Publishing window (startDate, endDate) with a publishing state

You can update activation state for one or more product groups in a single mutation.

Product membership

A product group contains a connection of products. This lets you inspect the products that belong to the group and paginate through them.

GraphQL API

Type

ProductGroup

Field	Type	Description
id	ID!	Product group identifier
internalReference	String!	Internal reference string for the group
workspaceId	Integer!	Workspace identifier
contractEarliestStartDate	String!	Earliest contract start date
contractLatestStartDate	String!	Latest contract start date
contractEarliestEndDate	String!	Earliest contract end date
contractLatestEndDate	String!	Latest contract end date
defaultExpiryDurationInSeconds	Integer	Default booking expiry duration
allowBookingExpiryTimer	Boolean	Whether booking expiry timer is enabled
academicYear	String	Academic year in YYYY/YYYY format
state	CatalogProductGroupStateEnum!	Activation state
publishing	Publishing!	Publishing window and lifecycle state
contractTemplateExternalId	String	External contract template identifier
createdAt	ISO8601DateTime!	Creation timestamp
updatedAt	ISO8601DateTime!	Last update timestamp

CatalogProductGroupStateEnum

Value	Description
ACTIVE	Product group is active
INACTIVE	Product group is inactive

CatalogPublishStateEnum

Value	Description
SCHEDULED	Publishing has not started yet
ONGOING	Publishing is currently active
FINISHED	Publishing window has ended

Queries

Get a product group

query ProductGroup($id: ID!) {
  catalog {
    productGroup(id: $id) {
      id
      internalReference
      state
      publishing {
        startDate
        endDate
        state
      }
      products {
        totalCount
      }
    }
  }
}

{
  "id": "product-group-id"
}

List product groups

query ProductGroups(
  $filters: ProductGroupsFiltersInput
  $first: Int
  $after: String
) {
  catalog {
    productGroups(filters: $filters, first: $first, after: $after) {
      nodes {
        id
        internalReference
        state
      }
      totalCount
      pageInfo {
        hasNextPage
        endCursor
      }
    }
  }
}

{
  "filters": {
    "state": "ACTIVE",
    "published": true
  },
  "first": 20
}

Tip: productGroups follows the standard connection pattern. Use cursors for pagination when iterating through large catalogs.

Mutations

Create a product group

mutation CreateProductGroup($input: CreateProductGroupMutationInput!) {
  catalog {
    productGroup {
      create(input: $input) {
        id
      }
    }
  }
}

{
  "input": {
    "productGroup": {
      "internalReference": "PG-2026-01",
      "contractEarliestStartDate": "2026-01-01",
      "contractLatestStartDate": "2026-09-30",
      "contractEarliestEndDate": "2026-01-15",
      "contractLatestEndDate": "2027-08-31",
      "workspaceId": "workspace-id",
      "academicYear": "2026/2027",
      "allowBookingExpiryTimer": true,
      "defaultExpiryDurationInSeconds": 1800,
      "publishing": {
        "startDate": "2026-02-01",
        "endDate": "2027-06-30"
      }
    }
  }
}

Required fields for productGroup in create:

Field	Type
internalReference	String!
contractEarliestStartDate	ISO8601Date!
contractLatestStartDate	ISO8601Date!
contractEarliestEndDate	ISO8601Date!
contractLatestEndDate	ISO8601Date!
workspaceId	ID!
academicYear	String!

Update a product group

mutation UpdateProductGroup($input: UpdateProductGroupMutationInput!) {
  catalog {
    productGroup {
      update(input: $input) {
        id
      }
    }
  }
}

{
  "input": {
    "productGroupId": "product-group-id",
    "productGroup": {
      "internalReference": "PG-2026-01-REV1",
      "publishing": {
        "startDate": "2026-03-01",
        "endDate": "2027-07-31"
      }
    }
  }
}

Required fields for update input:

Field	Type
productGroupId	ID!
productGroup	ProductGroupUpdateInput!

Update product group state in bulk

mutation UpdateProductGroupState($input: UpdateProductGroupsStateMutationInput!) {
  catalog {
    productGroup {
      updateState(input: $input) {
        updatedCount
        productGroupIds
      }
    }
  }
}

{
  "input": {
    "productGroupIds": [
      "product-group-id-1",
      "product-group-id-2"
    ],
    "state": "ACTIVE"
  }
}

MCP Tools

If you use MCP, these tools are relevant:

• get_product_group

• update_product_groups

• get_product

See Tools for setup and full coverage.

Relationships

• A product group belongs to a Workspaces

• A product group has many Product

• Product groups work alongside Pricing to control what can be sold and when