Skip to content

Product Collection Intents

Purpose

This document defines intent for product collections managed through the marketing BFF and consumed by site/page intents.

Product collections are reusable named selections of products. They are not site-owned objects, even when a given site happens to use them.

Role of Product Collections

Product collections support:

  • cross-portfolio grouping
  • site/page product selection
  • curated showcases
  • stable retrieval targets for apps and assistants

Use intent for a collection belongs in docs/sites/. The collection definition itself belongs in the product domain.

Retrieval Intent

The current BFF retrieval endpoints for product collections are:

  • getProductCollection(collectionKey)
  • getProductCollections(first, collectionKey)
  • getProductCollectionHeaders(first, query)
  • getProductCollectionsByKeys(collectionKeys)

Recommended retrieval pattern:

  1. use header/list queries to discover candidate collections
  2. use exact collection retrieval to inspect members
  3. use site/page intents to determine where a collection is consumed

Mutation Intent

The current verified collection mutations are:

  • createProductCollection(input)
  • deleteProductCollection(collectionKey)
  • setProductCollections(productKey, collectionKeys)

The schema also exposes:

  • updateProductCollection(collectionKey, input)

but live execution was previously observed failing, so it should be treated as unstable until re-verified.

Human Input Pattern

Collection intent should support requests such as:

  • show me collections for C&I systems
  • create a product collection for solar racking packages
  • add Racking System Package A to C&I System 30/60

The assistant should interpret these as collection-level operations, not as site-bound edits.

Collection Shape Direction

A product collection should be treated as a first-class object with:

  • collectionKey
  • name
  • description
  • optional scope metadata when useful
  • product membership
  • optional collection-level media and presentation metadata

Site Consumption Rule

Collections should be referenced by site/page intent under docs/sites/.

That means:

  • the product domain defines the collection
  • the site domain declares where it is used

This keeps product assets reusable across multiple sites, pages, and assistants.