diff --git a/DOCUMENTATION_OVERLAY_SUMMARY.md b/DOCUMENTATION_OVERLAY_SUMMARY.md deleted file mode 100644 index d9f9218c..00000000 --- a/DOCUMENTATION_OVERLAY_SUMMARY.md +++ /dev/null @@ -1,126 +0,0 @@ -# Documentation Overlay for categoryTree and navigation Queries - -## Overview - -This document summarizes the documentation overlay created for the new `categoryTree` and `navigation` queries in the Merchandising Services API. - -## Files Created/Modified - -### 1. Updated: `spectaql/metadata-merchandising.json` - -The main metadata file now contains comprehensive documentation for: - -- `categoryTree` query and its arguments -- `navigation` query and its arguments -- `CategoryTreeView` type and all its fields -- `CategoryNavigationView` type and all its fields - -### 2. Updated: `spectaql/config-merchandising.yml` - -SpectaQL configuration updated to use enhanced schema file instead of live introspection: - -- `introspectionFile: spectaql/enhanced-schema.json` -- Commented out live introspection URL and headers -- Enhanced metadata processing settings enabled - -### 3. Created: Enhanced Build Scripts - -- `scripts/fetch-and-enhance-schema.js` - Fetches live schema and injects descriptions -- `scripts/build-with-enhanced-schema.js` - Complete build process with description injection -- `scripts/inject-descriptions.js` - Core description injection logic (unused, kept for reference) - -## Usage - -### Enhanced Build Process - -To generate documentation with injected descriptions: - -```bash -node scripts/build-with-enhanced-schema.js -``` - -This process: - -1. Fetches the live GraphQL schema via introspection -2. Injects custom descriptions from `spectaql/metadata-merchandising.json` -3. Saves enhanced schema to `spectaql/enhanced-schema.json` -4. Runs SpectaQL using the enhanced schema file -5. Generates `static/graphql-api/merchandising-api/index.html` with descriptions - -### Standard Build Process - -For basic documentation without custom descriptions: - -```bash -yarn build:merchandising-api -``` - -## Documentation Added - -### categoryTree Query - -**Description:** Retrieve hierarchical category data in a tree structure. This query allows you to fetch category information with parent-child relationships, useful for building category navigation menus and breadcrumbs. - -**Arguments:** - -- `family` (String!): The catalog family identifier that determines which catalog's categories to retrieve. This is typically your store's catalog ID. -- `slugs` ([String!]): Optional array of specific category slugs to retrieve. If provided, only these categories and their hierarchical relationships will be returned. If omitted, all categories in the family are returned. -- `depth` (Int): Optional maximum depth level to retrieve in the category tree. Use this to limit how deep the hierarchy goes. If omitted, all levels are returned. - -### navigation Query - -**Description:** Retrieve category navigation data optimized for building storefront navigation menus. Returns a flattened structure of categories with their immediate children, ideal for creating responsive navigation components. - -**Arguments:** - -- `family` (String!): The catalog family identifier that determines which catalog's navigation structure to retrieve. This is typically your store's catalog ID. - -### CategoryTreeView Type - -**Description:** Represents a category in a hierarchical tree structure with parent-child relationships and level information. - -**Fields:** - -- `slug` (String!): The unique URL-friendly identifier for the category, used in routing and navigation. -- `name` (String!): The display name of the category as shown to customers in the storefront. -- `level` (Int): The hierarchical level of the category in the tree structure, where root categories have level 0. -- `parentSlug` (String): The slug of the parent category. Null for root-level categories. -- `childrenSlugs` ([String]): Array of slugs for all direct child categories. Empty array if the category has no children. - -### CategoryNavigationView Type - -**Description:** Represents a category optimized for navigation purposes with recursive child category structure. - -**Fields:** - -- `slug` (String!): The unique URL-friendly identifier for the category, used in routing and navigation. -- `name` (String!): The display name of the category as shown to customers in the storefront navigation. -- `children` ([CategoryNavigationView]): Array of direct child categories, each containing their own children in a recursive structure. Used to build multi-level navigation menus. - -## Usage - -The documentation overlay has been integrated into the existing SpectaQL configuration. When the API documentation is regenerated using the build scripts, the new queries and types will include comprehensive descriptions for all fields and arguments. - -To regenerate the documentation: - -```bash -yarn build:merchandising-api -``` - -## Benefits - -1. **Complete Documentation**: Both queries now have detailed descriptions explaining their purpose and use cases. -2. **Argument Documentation**: All query arguments include clear descriptions of their purpose and expected values. -3. **Field Documentation**: Every field in the return types has descriptive documentation. -4. **Developer-Friendly**: The documentation provides context about when and how to use each query. -5. **Maintainable**: The overlay approach allows for easy updates without modifying the core schema. - -## Verification - -The documentation has been successfully merged into the metadata file. You can verify this by checking: - -- The `categoryTree` and `navigation` queries in the metadata file -- The `CategoryTreeView` and `CategoryNavigationView` type definitions -- The field argument documentation for both queries - -The next time the API documentation is built (when proper API credentials are available), these descriptions will appear in the generated HTML documentation. diff --git a/README.md b/README.md index 28fd02ea..f11be8e9 100644 --- a/README.md +++ b/README.md @@ -60,272 +60,47 @@ If you have questions, open an issue and ask us. We look forward to hearing from ## GraphQL API reference generator -The GraphQL API reference is generated using [SpectaQL](https://github.com/anvilco/spectaql), an open source tool. The data required for the generator is located in the `spectaql` directory: +The Merchandising GraphQL API reference is generated using [SpectaQL](https://github.com/anvilco/spectaql). It uses live introspection against the GraphQL endpoint and a metadata overlay to filter the schema down to the documented queries and types. -- `config-admin.yml`: [configuration file to generate the Channels and Policies API Reference](spectaql/config-admin.yml). (Not used in the current implementation, but included for future use.) -- `config-merchandising.yml`: [configuration file to generate the Merchandising Services API Reference](spectaql/config-admin.yml). +### Quick start -These configuration files include the endpoint for each API service. +1. Create a `.env` file in the project root: -When you build the API reference, the build script uses live introspection to retrieve the GraphQL schemas and generate the API references. The configuration file also provides the introductory text for the Welcome topic, the API reference title, and other settings used when generating the references. - -The resulting GraphQL API references are output to the `static/graphql-api/` directory. - -- `static/graphql/admin-api/index.html` -- `static/graphql/merchandising-api/index.html` - -The references are embedded in the API Reference page using the `frameSrc` feature supported by the Adobe I/O theme. - -- [Channels and Policies API Reference](src/pages/optimizer/reference/graphql/merchandising-api/) `frameSrc: /graphql-api/merchandising-api/index.html` - -### Build commands - -To rebuild the GraphQL API references after any updates, use the following build scripts: - -#### Standard Build Commands - -Command | Description -------- |------------ -`build:merchandising-api` | Regenerates the Merchandising API reference using live introspection -`dev:merchandising-api` | Regenerates the Merchandising API reference with a live preview of updated output -`build:graphql` | Regenerates both references - -#### Enhanced Build with Description Injection - -For the Merchandising API, you can use the enhanced build process that injects custom descriptions: - -```shell -node scripts/build-with-enhanced-schema.js -``` - -This enhanced build process: - -1. Fetches the live GraphQL schema via introspection -2. Injects custom descriptions from `spectaql/metadata-merchandising.json` -3. Generates documentation with enhanced descriptions for queries, types, and fields - -**Use the enhanced build when:** - -- You've added new documentation to `spectaql/metadata-merchandising.json` -- You want descriptions to appear for queries like `categoryTree` and `navigation` -- You need custom field and argument descriptions that aren't in the live schema - -**Use the standard build when:** - -- You only need basic schema documentation without custom descriptions -- You're working with schemas that already have complete descriptions - -### Managing Custom Descriptions - -The enhanced build process uses custom descriptions stored in `spectaql/metadata-merchandising.json`. This file contains documentation for: - -- **Queries**: Descriptions for GraphQL queries like `categoryTree` and `navigation` -- **Types**: Descriptions for GraphQL types like `CategoryTreeView` and `CategoryNavigationView` -- **Fields**: Descriptions for individual fields within types -- **Arguments**: Descriptions for query and field arguments - -#### Adding New Documentation - -To add documentation for new queries, types, or fields: - -1. **Edit the metadata file**: Add entries to `spectaql/metadata-merchandising.json` following the existing structure: - - **For Query Documentation:** - - ```json - { - "OBJECT": { - "Query": { - "fields": { - "yourQueryName": { - "documentation": { - "description": "Description of what your query does and when to use it", - "undocumented": false - } - } - } - } - }, - "FIELD_ARGUMENT": { - "Query": { - "yourQueryName": { - "argumentName": { - "documentation": { - "description": "Description of what this argument does", - "undocumented": false - } - } - } - } - } - } + ```bash + cp .env.example .env ``` - **For Type Documentation:** - - ```json - { - "OBJECT": { - "YourTypeName": { - "documentation": { - "description": "Description of your type and its purpose", - "undocumented": false - }, - "fields": { - "fieldName": { - "documentation": { - "description": "Description of the field and its usage", - "undocumented": false - } - } - } - } - } - } - ``` +2. Build the API reference: - **Complete Example:** - - ```json - { - "OBJECT": { - "Query": { - "fields": { - "productSearch": { - "documentation": { - "description": "Search for products using various filters and criteria. Returns paginated results with product details.", - "undocumented": false - } - } - } - }, - "ProductSearchResult": { - "documentation": { - "description": "Contains search results with products and pagination information", - "undocumented": false - }, - "fields": { - "products": { - "documentation": { - "description": "Array of products matching the search criteria", - "undocumented": false - } - }, - "totalCount": { - "documentation": { - "description": "Total number of products found (before pagination)", - "undocumented": false - } - } - } - } - }, - "FIELD_ARGUMENT": { - "Query": { - "productSearch": { - "query": { - "documentation": { - "description": "Search term to match against product names and descriptions", - "undocumented": false - } - - }, - "filters": { - "documentation": { - "description": "Optional filters to narrow down search results by category, price, etc.", - "undocumented": false - } - } - } - } - } - } + ```bash + yarn build:merchandising-api ``` -2. **Rebuild with enhanced process**: Run `node scripts/build-with-enhanced-schema.js` - -3. **Verify**: Check the generated `static/graphql-api/merchandising-api/index.html` for your descriptions - -#### Environment Variables Required - -The enhanced build process requires these environment variables in your `.env` file: - -```bash -TENANT_ID=your_tenant_id -CATALOG_VIEW_ID=your_catalog_view_id -ENVIRONMENT_ID=your_environment_id -``` - -#### Troubleshooting Enhanced Build - -**Issue: "Missing required environment variables"** - -- Solution: Ensure your `.env` file contains `TENANT_ID`, `CATALOG_VIEW_ID`, and `ENVIRONMENT_ID` +The generated output is written to `static/graphql-api/merchandising-api/index.html` and embedded in the documentation site using the Adobe I/O theme's `frameSrc` feature. After rebuilding, verify the output in your browser before committing changes. -**Issue: "Server responded with status code 404"** +To generate a live preview during local development, run: `yarn dev:merchandising-api`. -- Solution: Verify your environment variables are correct and the API endpoint is accessible +### Prerequisites -**Issue: Descriptions not appearing in generated HTML** - -- Solution: Check that your metadata follows the correct JSON structure and run the enhanced build process - -**Issue: Build fails with permission errors** - -- Solution: The enhanced build may require network permissions to fetch the live schema - -### How to get the schema - -The Spectaql configuration files for the Merchandising Services GraphQL API references use the following endpoints to retrieve the schemas and generate the API references: - -- Channels and Policies API: https://commerce-admin-router-qa.corp.ethos501-stage-va6.ethos.adobe.net/graphql - -- Storefront API: https://catalog-service-qa.adobe.io/graphql - -If either of these endpoints change, update the live introspection URL in the corresponding config file in the `spectaql` directory with the new endpoint. - -### Update the API References - -If a schema changes, rebuild and test the API reference locally. Then, submit a PR with updates against the `ccdm-early-access` branch. After the PR is merged, someone from the documentation team will publish the changes to the documentation server. - -For local builds, ensure that your environment has the following installed: - -- Node.js that matches the version set in the [.nvmrc](https://github.com/AdobeDocs/commerce-services/blob/main/.nvmrc) ([nvm](https://github.com/nvm-sh/nvm) configuration file). +- Node.js matching the version in [.nvmrc](https://github.com/AdobeDocs/commerce-services/blob/main/.nvmrc) - Yarn -## Update schema and regenerate documentation +### Update the API reference -1. Create a branch from the `ccdm-early-access` branch. +If the schema or metadata descriptions change, rebuild and test the API reference locally: -1. To regenerate an API reference locally and test changes: +1. Create a branch from `main`. +2. Regenerate the API reference using the enhanced build (includes custom descriptions): - **For standard schema updates:** - - ```shell - yarn dev:merchandising-api - ``` - - **For enhanced documentation with custom descriptions:** - - ```shell + ```bash node scripts/build-with-enhanced-schema.js ``` - Use the enhanced build if you've added or modified descriptions in `spectaql/metadata-merchandising.json`. - -1. Commit changes and push them to your remote branch. - -1. Create and submit a PR against the `ccdm-early-access` branch, and request review from the Commerce Documentation team. - -1. After updates are approved, a documentation team member merges the PR and publishes the updates to [developer site](https://developer.adobe.com/commerce/services/merchandising-services/) for Early Access customers. - - View the published API references: - - - [Storefront API Reference](https://developer.adobe.com/commerce/services/optimizer/reference/graphql/merchandising-api/) - -### Resources +3. Verify the output in your browser. +4. Commit the updated `index.html` and `enhanced-schema.json` files. +5. After updates are approved, a documentation team member merges the PR and publishes the updates to the [developer site](https://developer.adobe.com/commerce/services/merchandising-services/). -For more information about SpectaQL, refer to . +See [`spectaql/README.md`](spectaql/README.md) for detailed configuration, build commands, offline builds, and script documentation. ## REST API Reference Generator diff --git a/scripts/build-with-enhanced-schema.js b/scripts/build-with-enhanced-schema.js index 01df2e2a..a4df00c3 100644 --- a/scripts/build-with-enhanced-schema.js +++ b/scripts/build-with-enhanced-schema.js @@ -19,10 +19,24 @@ async function buildWithEnhancedSchema() { console.log('🚀 Step 1: Generating enhanced schema...'); await enhanceSchema(); - // Step 2: Generate SpectaQL config + // Step 2: Generate SpectaQL config pointing to the enhanced schema console.log('🚀 Step 2: Generating SpectaQL configuration...'); require('./generate-spectaql-config'); + const fs = require('fs'); + const { tempConfigPath } = require('./generate-spectaql-config'); + let tempConfig = fs.readFileSync(tempConfigPath, 'utf8'); + tempConfig = tempConfig.replace( + /^(\s*)#(introspectionFile:\s*spectaql\/enhanced-schema\.json)/m, + '$1$2' + ); + tempConfig = tempConfig.replace( + /^(\s*)(url:\s*https:\/\/.*\/graphql.*)/m, + '$1#$2' + ); + fs.writeFileSync(tempConfigPath, tempConfig); + console.log('📝 Configured SpectaQL to use enhanced schema file'); + // Step 3: Run SpectaQL with enhanced schema console.log('🚀 Step 3: Running SpectaQL with enhanced schema...'); diff --git a/scripts/fetch-and-enhance-schema.js b/scripts/fetch-and-enhance-schema.js index c2850050..64c4ae80 100644 --- a/scripts/fetch-and-enhance-schema.js +++ b/scripts/fetch-and-enhance-schema.js @@ -23,13 +23,12 @@ const metadata = JSON.parse(fs.readFileSync(metadataPath, 'utf8')); async function fetchIntrospection() { const tenantId = process.env.TENANT_ID; const catalogViewId = process.env.CATALOG_VIEW_ID; - const environmentId = process.env.ENVIRONMENT_ID; - - if (!tenantId || !catalogViewId || !environmentId) { - throw new Error('Missing required environment variables: TENANT_ID, CATALOG_VIEW_ID, ENVIRONMENT_ID'); + const apiHost = process.env.API_HOST || 'na1-sandbox.api.commerce.adobe.com'; + + if (!tenantId || !catalogViewId) { + throw new Error('Missing required environment variables: TENANT_ID, CATALOG_VIEW_ID'); } - - const url = `https://na1-sandbox.api.commerce.adobe.com/${tenantId}/graphql`; + const url = `https://${apiHost}/${tenantId}/graphql`; const introspectionQuery = { query: ` query IntrospectionQuery { @@ -50,7 +49,6 @@ async function fetchIntrospection() { } } } - fragment FullType on __Type { kind name @@ -130,15 +128,14 @@ async function fetchIntrospection() { const postData = JSON.stringify(introspectionQuery); const options = { - hostname: 'na1-sandbox.api.commerce.adobe.com', + hostname: apiHost, port: 443, path: `/${tenantId}/graphql`, method: 'POST', headers: { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(postData), - 'AC-Catalog-View-ID': catalogViewId, - 'AC-Environment-ID': environmentId + 'AC-Catalog-View-ID': catalogViewId } }; @@ -207,29 +204,31 @@ function injectDescriptions(introspectionResult) { * Inject descriptions into query fields */ function injectQueryDescriptions(queryType) { - if (!queryType.fields || !metadata.OBJECT || !metadata.OBJECT.Query || !metadata.OBJECT.Query.fields) { + if (!queryType.fields) { return; } + const queryFields = metadata.OBJECT && metadata.OBJECT.Query && metadata.OBJECT.Query.fields; + const fieldArgs = metadata.FIELD_ARGUMENT && metadata.FIELD_ARGUMENT.Query; + queryType.fields.forEach(field => { - const fieldMetadata = metadata.OBJECT.Query.fields[field.name]; - if (fieldMetadata && fieldMetadata.documentation && fieldMetadata.documentation.description) { - // Always inject description, even if it already exists - field.description = fieldMetadata.documentation.description; - console.log(`📝 Injected description for query: ${field.name}`); - - // Also inject argument descriptions - if (field.args && metadata.FIELD_ARGUMENT && metadata.FIELD_ARGUMENT.Query && metadata.FIELD_ARGUMENT.Query[field.name]) { - field.args.forEach(arg => { - const argMetadata = metadata.FIELD_ARGUMENT.Query[field.name][arg.name]; - if (argMetadata && argMetadata.documentation && argMetadata.documentation.description) { - // Always inject argument description, even if it already exists - arg.description = argMetadata.documentation.description; - console.log(`📝 Injected description for argument: ${field.name}.${arg.name}`); - } - }); + if (queryFields) { + const fieldMetadata = queryFields[field.name]; + if (fieldMetadata && fieldMetadata.documentation && fieldMetadata.documentation.description) { + field.description = fieldMetadata.documentation.description; + console.log(`📝 Injected description for query: ${field.name}`); } } + + if (field.args && fieldArgs && fieldArgs[field.name]) { + field.args.forEach(arg => { + const argMetadata = fieldArgs[field.name][arg.name]; + if (argMetadata && argMetadata.documentation && argMetadata.documentation.description) { + arg.description = argMetadata.documentation.description; + console.log(`📝 Injected description for argument: ${field.name}.${arg.name}`); + } + }); + } }); } diff --git a/scripts/inject-descriptions.js b/scripts/inject-descriptions.js index 2e2b7f72..099af0d9 100644 --- a/scripts/inject-descriptions.js +++ b/scripts/inject-descriptions.js @@ -47,27 +47,31 @@ function preprocessIntrospection(introspectionResult) { * Inject descriptions into query fields */ function injectQueryDescriptions(queryType) { - if (!queryType.fields || !metadata.OBJECT || !metadata.OBJECT.Query || !metadata.OBJECT.Query.fields) { + if (!queryType.fields) { return; } + const queryFields = metadata.OBJECT && metadata.OBJECT.Query && metadata.OBJECT.Query.fields; + const fieldArgs = metadata.FIELD_ARGUMENT && metadata.FIELD_ARGUMENT.Query; + queryType.fields.forEach(field => { - const fieldMetadata = metadata.OBJECT.Query.fields[field.name]; - if (fieldMetadata && fieldMetadata.documentation && fieldMetadata.documentation.description) { - field.description = fieldMetadata.documentation.description; - console.log(`📝 Injected description for query: ${field.name}`); - - // Also inject argument descriptions - if (field.args && metadata.FIELD_ARGUMENT && metadata.FIELD_ARGUMENT.Query && metadata.FIELD_ARGUMENT.Query[field.name]) { - field.args.forEach(arg => { - const argMetadata = metadata.FIELD_ARGUMENT.Query[field.name][arg.name]; - if (argMetadata && argMetadata.documentation && argMetadata.documentation.description) { - arg.description = argMetadata.documentation.description; - console.log(`📝 Injected description for argument: ${field.name}.${arg.name}`); - } - }); + if (queryFields) { + const fieldMetadata = queryFields[field.name]; + if (fieldMetadata && fieldMetadata.documentation && fieldMetadata.documentation.description) { + field.description = fieldMetadata.documentation.description; + console.log(`📝 Injected description for query: ${field.name}`); } } + + if (field.args && fieldArgs && fieldArgs[field.name]) { + field.args.forEach(arg => { + const argMetadata = fieldArgs[field.name][arg.name]; + if (argMetadata && argMetadata.documentation && argMetadata.documentation.description) { + arg.description = argMetadata.documentation.description; + console.log(`📝 Injected description for argument: ${field.name}.${arg.name}`); + } + }); + } }); } diff --git a/spectaql/README.md b/spectaql/README.md index 6ab117ec..f7fbc0ab 100644 --- a/spectaql/README.md +++ b/spectaql/README.md @@ -1,75 +1,142 @@ -# SpectaQL configuration with environment variables +# SpectaQL configuration This directory contains SpectaQL configuration files for generating GraphQL API documentation. ## Configuration files -- `config-admin.yml` - Configuration for the Admin API +- `config-admin.yml` - Configuration for the Admin API (reference not currently implemented) - `config-merchandising.yml` - Configuration for the Merchandising API (uses environment variables) +- `metadata-merchandising.json` - Metadata file that controls which queries and types appear in the Merchandising API reference +- `enhanced-schema.json` - Cached introspection result for offline builds (generated by `scripts/fetch-and-enhance-schema.js`) -## Using environment variables +## How it works -The merchandising API configuration uses a `TENANT_ID` environment variable to dynamically set the GraphQL endpoint URL. +The Merchandising API documentation is generated by SpectaQL using **live introspection** against the GraphQL endpoint. The `metadata-merchandising.json` file filters the full schema down to only the relevant queries and their associated types. -**Security Note:** Only use `.env` files to avoid exposing sensitive information in CLI history. +### Documented queries -### Recommended: Use .env file +The metadata file is configured to include only these queries: -Create a `.env` file in the project root: +- `attributeMetadata` +- `categoryTree` +- `navigation` +- `productSearch` +- `products` +- `recommendations` +- `recommendationsByUnitIds` +- `refineProduct` +- `variants` + +All other queries and their exclusively-referenced types are marked as `undocumented` and excluded from the generated output. + +### Metadata file structure + +The metadata file uses SpectaQL's metadata format with these sections: + +- **`OBJECT.Query.fields`** — Marks unwanted queries as `undocumented: true` +- **`OBJECT.*`** — Marks unwanted Object types as `undocumented: true` +- **`INPUT_OBJECT.*`** — Marks unwanted Input types as `undocumented: true` +- **`ENUM.*`** — Marks unwanted Enum types as `undocumented: true` +- **`UNION.*`** — Marks unwanted Union types as `undocumented: true` +- **`INTERFACE.*`** — Marks unwanted Interface types as `undocumented: true` +- **`FIELD_ARGUMENT`** — Provides custom descriptions for query arguments (e.g., `categoryTree` and `navigation` arguments) + +## Environment variables + +The following environment variables are required. Set them in a `.env` file in the project root: ```bash # Copy the example file cp .env.example .env - -# Edit .env and set your tenant ID -TENANT_ID=your_tenant_id_here ``` -Then run the npm scripts: +| Variable | Description | +|---|---| +| `TENANT_ID` | Your Adobe Commerce tenant ID | +| `CATALOG_VIEW_ID` | Catalog view ID for the API context | + +## Related scripts + +| Script | Purpose | +|---|---| +| `scripts/fetch-and-enhance-schema.js` | Fetches the live schema and injects custom descriptions | +| `scripts/build-with-enhanced-schema.js` | End-to-end build: fetch schema, inject descriptions, run SpectaQL | +| `scripts/run-spectaql-with-cleanup.js` | Runs SpectaQL with automatic temp file cleanup | +| `scripts/generate-spectaql-config.js` | Generates a temp config with environment variables substituted | +| `scripts/inject-descriptions.js` | Core description injection logic (used by `fetch-and-enhance-schema.js`) | + +## Build commands + +### Standard build (live endpoint) + +Uses live introspection to fetch the schema and applies metadata filtering: ```bash # Build the documentation yarn build:merchandising-api -# Or run in development mode +# Or run in development mode with live preview yarn dev:merchandising-api ``` -## Environment variables +During a standard build, SpectaQL: -- `TENANT_ID` - Your Adobe Commerce tenant ID (required) +1. Substitutes environment variables into a temp config file +2. Introspects the live GraphQL endpoint +3. Applies the metadata file to filter queries/types and inject descriptions +4. Generates `static/graphql-api/merchandising-api/index.html` +5. Cleans up the temp config file -## Generated files +### Enhanced build (with description injection) -When using the tenant-specific scripts, a temporary configuration file `config-merchandising-temp.yml` is created with the actual tenant ID substituted. This file is automatically cleaned up after SpectaQL finishes running. +The standard build uses the live schema as-is, so any query arguments that lack descriptions in the live schema appear blank. The enhanced build solves this by fetching the live schema, injecting the custom descriptions defined in `metadata-merchandising.json` (under `FIELD_ARGUMENT`), and then running SpectaQL against the enhanced schema. -### Automatic cleanup +```bash +node scripts/build-with-enhanced-schema.js +``` -The temporary configuration files are automatically deleted after use to keep your workspace clean. This happens: +Use this build whenever `metadata-merchandising.json` includes custom descriptions that you want reflected in the generated API reference. -- When SpectaQL completes successfully -- When SpectaQL encounters an error -- When the process is interrupted (Ctrl+C) -- When the process is terminated +### Update the cached schema (for offline builds) -## Example +Fetches the current schema from the live endpoint and saves it to `enhanced-schema.json`: ```bash -# Set in .env file -TENANT_ID=abc123 +node scripts/fetch-and-enhance-schema.js +``` -# Run the build -yarn build:merchandising-api +To use the cached schema instead of the live endpoint, edit `config-merchandising.yml`: -# This will generate documentation for: -# https://na1-sandbox.api.commerce.adobe.com/abc123/graphql -``` +1. Uncomment: `introspectionFile: spectaql/enhanced-schema.json` +2. Comment out the `url` and `headers` lines + +## Update the API reference + +If the schema or metadata descriptions change, rebuild and test the API reference locally: + +1. Create a branch from `main`. +2. If you updated custom descriptions in `metadata-merchandising.json`, use the enhanced build: + + ```bash + node scripts/build-with-enhanced-schema.js + ``` + + Otherwise, use the standard build: `yarn dev:merchandising-api` +3. Open `static/graphql-api/merchandising-api/index.html` in your browser and verify the output. +4. Commit the updated `index.html` and `enhanced-schema.json` files. +5. After updates are approved, a documentation team member merges the PR and publishes the updates to the [developer site](https://developer.adobe.com/commerce/services/merchandising-services/). + +### Prerequisites + +- Node.js matching the version in [.nvmrc](https://github.com/AdobeDocs/commerce-services/blob/main/.nvmrc) +- Yarn + +## Generated output + +The build generates `static/graphql-api/merchandising-api/index.html`, which is embedded in the documentation site using the Adobe I/O theme's `frameSrc` feature. ## Notes -- The `${TENANT_ID}` placeholder in the YAML file is not processed by SpectaQL directly -- The Node.js script `scripts/generate-spectaql-config.js` handles the substitution -- Temporary configuration files are automatically cleaned up after use -- A `.env.example` file is provided as a template - copy it to `.env` and customize -- The `.env` file is already in `.gitignore` to prevent committing sensitive information -- **Security**: Only use `.env` files to avoid exposing tenant IDs in CLI history +- The `${TENANT_ID}` placeholder in the YAML config is processed by `scripts/generate-spectaql-config.js`, which creates a temporary `config-merchandising-temp.yml` file +- Temporary config files are automatically cleaned up after the build completes +- The `.env` file is in `.gitignore` to prevent committing sensitive information diff --git a/spectaql/config-merchandising.yml b/spectaql/config-merchandising.yml index cfa1033d..0bdf541d 100644 --- a/spectaql/config-merchandising.yml +++ b/spectaql/config-merchandising.yml @@ -111,11 +111,11 @@ introspection: # schemaFile: path/to/schema.gql # File containing Introspection Query response in JS module export, or JSON format - introspectionFile: spectaql/enhanced-schema.json + #introspectionFile: spectaql/enhanced-schema.json # URL of the GraphQL endpoint to hit if you want to generate the documentation based on live Introspection Query results # NOTE: If not using introspection.url OR servers[], you need to provide x-url below - # url: https://na1-sandbox.api.commerce.adobe.com/${TENANT_ID}/graphql # TENANT_ID should be set as an environment variable. This value was previously hardcoded for the Instructor Instance in the Adobe Commerce Optimizer org. + url: https://na1-qa.api.commerce.adobe.com/${TENANT_ID}/graphql # TENANT_ID should be set as an environment variable. This value was previously hardcoded for the Instructor Instance in the Adobe Commerce Optimizer org. exclude: excludeMutations: true # @@ -124,8 +124,10 @@ introspection: # If using the "url" option above, any headers (such as Authorization) can be added here. This # can also be added via the CLI options - # headers: - # AC-Catalog-View-ID: ${CATALOG_VIEW_ID} + headers: + AC-Environment-Id: ${TENANT_ID} + AC-View-Id: ${CATALOG_VIEW_ID} + Content-Type: application/json # Authorization: Bearer s3cretT0k2n # Some helpful options for those who are an "SDL-first" shop and/or want to get your metadata into diff --git a/spectaql/enhanced-schema.json b/spectaql/enhanced-schema.json index e649cc32..6f188ae0 100644 --- a/spectaql/enhanced-schema.json +++ b/spectaql/enhanced-schema.json @@ -120,7 +120,7 @@ }, { "name": "navigation", - "description": "Retrieve category navigation data optimized for storefront menu rendering with built-in performance safeguards.\n\n**Performance Features:**\n- Limited to 4 levels deep for optimal rendering\n- Single database query per family\n- Heavily cached responses\n- Excludes heavyweight category attributes", + "description": "Retrieves the navigation tree for a given product family.", "args": [ { "name": "family", @@ -146,7 +146,7 @@ }, { "name": "categoryTree", - "description": "Retrieve hierarchical category data in a tree structure with parent-child relationships and level information.\n\n**Primary Use Case:** RetailCMS applications requiring full category tree management.", + "description": "Retrieves category tree nodes, optionally filtered by slugs and limited by depth.", "args": [ { "name": "family", @@ -308,6 +308,19 @@ } } }, + { + "name": "commerceOptimizer", + "description": "Provide necessary information to build headless storefront when Adobe Commerce is connected to Commerce Optimizer.", + "args": [], + "type": { + "name": null, + "kind": "NON_NULL", + "ofType": { + "name": "CommerceOptimizerContext", + "kind": "OBJECT" + } + } + }, { "name": "company", "description": "Return detailed information about the customer's company within the current company context.", @@ -12034,6 +12047,77 @@ } ] }, + { + "kind": "OBJECT", + "name": "CategoryImage", + "description": "Represents an image associated with a category.", + "fields": [ + { + "name": "url", + "description": "The URL where the image is hosted.", + "args": [], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "label", + "description": "A descriptive label or alt text for the image.", + "args": [], + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "roles", + "description": "Standard predefined roles for the image.", + "args": [], + "type": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "customRoles", + "description": "Custom roles specific to the implementation.", + "args": [], + "type": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [], + "enumValues": null, + "possibleTypes": null + }, { "kind": "INTERFACE", "name": "CategoryInterface", @@ -12363,14 +12447,65 @@ } ] }, + { + "kind": "OBJECT", + "name": "CategoryMetaTags", + "description": "SEO metadata tags for the category.", + "fields": [ + { + "name": "title", + "description": "The page title for SEO purposes.", + "args": [], + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "description", + "description": "The meta description for SEO purposes.", + "args": [], + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "keywords", + "description": "Keywords associated with the category for SEO.", + "args": [], + "type": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [], + "enumValues": null, + "possibleTypes": null + }, { "kind": "OBJECT", "name": "CategoryNavigationView", - "description": "Represents a category optimized for storefront menu rendering with recursive child category structure.\n\n**Performance Safeguards:**\n- Limited to 4 levels deep\n- Excludes heavyweight category attributes\n- Supports heavy caching\n- Single query optimization\n\n**Ideal For:**\n- Responsive navigation components\n- Dropdown menus\n- Mobile navigation\n- Breadcrumb systems", + "description": "Represents a category optimized for navigation menus, with nested children for building navigation trees.", "fields": [ { "name": "slug", - "description": "The unique URL-friendly identifier for the category, used in routing and navigation.", + "description": "The unique URL-friendly identifier for the category.", "args": [], "type": { "kind": "NON_NULL", @@ -12386,7 +12521,7 @@ }, { "name": "name", - "description": "The display name of the category as shown to customers in the storefront navigation.", + "description": "The display name of the category.", "args": [], "type": { "kind": "NON_NULL", @@ -12402,7 +12537,7 @@ }, { "name": "children", - "description": "Array of direct child categories in a recursive structure.\n\n**Structure:**\n- Each child contains their own children (recursive)\n- Limited to 4 levels deep for performance\n- Empty array if no children or max depth reached\n\n**Optimized For:** Multi-level navigation menu rendering with built-in performance safeguards.", + "description": "The direct child categories for building nested navigation menus.", "args": [], "type": { "kind": "LIST", @@ -12428,6 +12563,91 @@ "enumValues": null, "possibleTypes": null }, + { + "kind": "OBJECT", + "name": "CategoryProductView", + "description": "Represents category information associated with a product, including hierarchical parent relationships.", + "fields": [ + { + "name": "name", + "description": "The display name of the category.", + "args": [], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "slug", + "description": "The unique URL-friendly identifier for the category.", + "args": [], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "level", + "description": "The depth level of the category in the hierarchy (0 for root categories).", + "args": [], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "Int", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "parents", + "description": "The ancestor categories in the hierarchy, ordered from root to immediate parent.", + "args": [], + "type": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "OBJECT", + "name": "CategoryProductView", + "ofType": null + } + } + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [ + { + "kind": "INTERFACE", + "name": "CategoryViewV2", + "ofType": null + } + ], + "enumValues": null, + "possibleTypes": null + }, { "kind": "OBJECT", "name": "CategoryTree", @@ -12760,11 +12980,11 @@ { "kind": "OBJECT", "name": "CategoryTreeView", - "description": "Represents a category in a hierarchical tree structure with comprehensive parent-child relationship metadata.\n\n**Key Features:**\n- Implements CategoryViewV2 interface\n- Designed for RetailCMS applications\n- Full category tree management capabilities\n\n**Provides:**\n- Level depth information\n- Parent slug references\n- Children slug collections\n- Complete hierarchy metadata", + "description": "Represents a category within a hierarchical tree structure, including parent and children relationships.", "fields": [ { "name": "slug", - "description": "The unique URL-friendly identifier for the category, used in routing and navigation.", + "description": "The unique URL-friendly identifier for the category.", "args": [], "type": { "kind": "NON_NULL", @@ -12780,7 +13000,7 @@ }, { "name": "name", - "description": "The display name of the category as shown to customers in the storefront.", + "description": "The display name of the category.", "args": [], "type": { "kind": "NON_NULL", @@ -12794,9 +13014,49 @@ "isDeprecated": false, "deprecationReason": null }, + { + "name": "description", + "description": "A detailed description of the category.", + "args": [], + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "metaTags", + "description": "SEO metadata tags for the category.", + "args": [], + "type": { + "kind": "OBJECT", + "name": "CategoryMetaTags", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "images", + "description": "Visual images associated with the category.", + "args": [], + "type": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "OBJECT", + "name": "CategoryImage", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, { "name": "level", - "description": "The hierarchical depth level of the category in the tree structure.\n\n**Level Structure:**\n- Root categories: level 0\n- First-level children: level 1\n- Second-level children: level 2\n- And so on...\n\n**Used For:** Tree traversal and hierarchy management in RetailCMS applications.", + "description": "The depth level of the category in the tree hierarchy (0 for root categories).", "args": [], "type": { "kind": "SCALAR", @@ -12808,7 +13068,7 @@ }, { "name": "parentSlug", - "description": "The slug of the immediate parent category in the hierarchy.\n\n**Values:**\n- Parent category slug for child categories\n- `null` for root-level categories\n\n**Common Uses:**\n- Building breadcrumb navigation\n- Understanding category relationships\n- Tree management system operations", + "description": "The slug of the parent category, if any.", "args": [], "type": { "kind": "SCALAR", @@ -12820,7 +13080,7 @@ }, { "name": "childrenSlugs", - "description": "Array of slugs for all direct child categories (immediate descendants only).\n\n**Contains:**\n- Slugs of immediate children only (not grandchildren)\n- Empty array if no children exist\n\n**Benefits:**\n- Determine subcategory existence without fetching full objects\n- Efficient category tree management\n- Quick hierarchy assessment", + "description": "The slugs of all direct child categories.", "args": [], "type": { "kind": "LIST", @@ -13204,11 +13464,11 @@ { "kind": "INTERFACE", "name": "CategoryViewV2", - "description": "Lightweight base interface for category view models designed for storefront APIs without backward compatibility constraints.\n\n**Design Principles:**\n- Minimal essential properties (slug and name only)\n- Optimal performance for storefront use cases\n- No coupling with search facets\n\n**Replaces:** The heavyweight CategoryView interface\n\n**Implemented By:**\n- CategoryNavigationView (menu rendering)\n- CategoryTreeView (hierarchy management)", + "description": "Base interface defining essential category fields shared across all category views.", "fields": [ { "name": "slug", - "description": "The unique URL-friendly identifier for the category, used in routing and navigation.", + "description": "The unique URL-friendly identifier for the category.", "args": [], "type": { "kind": "NON_NULL", @@ -13224,7 +13484,7 @@ }, { "name": "name", - "description": "The display name of the category as shown to customers in the storefront.", + "description": "The display name of the category.", "args": [], "type": { "kind": "NON_NULL", @@ -13248,6 +13508,11 @@ "name": "CategoryNavigationView", "ofType": null }, + { + "kind": "OBJECT", + "name": "CategoryProductView", + "ofType": null + }, { "kind": "OBJECT", "name": "CategoryTreeView", @@ -13792,6 +14057,33 @@ "enumValues": null, "possibleTypes": null }, + { + "kind": "OBJECT", + "name": "CommerceOptimizerContext", + "description": "Commerce Optimizer entities", + "fields": [ + { + "name": "priceBookId", + "description": "The priceBookId for current customer session.", + "args": [], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "ID", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [], + "enumValues": null, + "possibleTypes": null + }, { "kind": "ENUM", "name": "CompaniesSortFieldEnum", @@ -14160,6 +14452,18 @@ "isDeprecated": false, "deprecationReason": null }, + { + "name": "status", + "description": "The current status of the company.", + "args": [], + "type": { + "kind": "ENUM", + "name": "CompanyStatusEnum", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, { "name": "structure", "description": "The company structure of teams and customers in depth-first order.", @@ -14646,6 +14950,18 @@ }, "isDeprecated": false, "deprecationReason": null + }, + { + "name": "status", + "description": "The current status of the company.", + "args": [], + "type": { + "kind": "ENUM", + "name": "CompanyStatusEnum", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null } ], "inputFields": null, @@ -15800,6 +16116,41 @@ "enumValues": null, "possibleTypes": null }, + { + "kind": "ENUM", + "name": "CompanyStatusEnum", + "description": "Defines the list of company status values.", + "fields": null, + "inputFields": null, + "interfaces": null, + "enumValues": [ + { + "name": "PENDING", + "description": "Company is pending approval.", + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "APPROVED", + "description": "Company is approved.", + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "REJECTED", + "description": "Company is rejected.", + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "BLOCKED", + "description": "Company is blocked.", + "isDeprecated": false, + "deprecationReason": null + } + ], + "possibleTypes": null + }, { "kind": "OBJECT", "name": "CompanyStructure", @@ -16742,7 +17093,7 @@ }, { "name": "attributes", - "description": "A list of merchant-defined attributes designated for the storefront.", + "description": "A list of merchant-defined attributes designated for the storefront. They can be filtered by roles and names.", "args": [ { "name": "roles", @@ -16757,6 +17108,20 @@ } }, "defaultValue": null + }, + { + "name": "names", + "description": null, + "type": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + }, + "defaultValue": null } ], "type": { @@ -17045,6 +17410,37 @@ "isDeprecated": false, "deprecationReason": null }, + { + "name": "categories", + "description": "A list of categories in which the product is present.", + "args": [ + { + "name": "family", + "description": null, + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + } + ], + "type": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "OBJECT", + "name": "CategoryProductView", + "ofType": null + } + } + }, + "isDeprecated": false, + "deprecationReason": null + }, { "name": "queryType", "description": "Indicates if the product was retrieved from the primary or the backup query", @@ -24696,6 +25092,22 @@ "isDeprecated": false, "deprecationReason": null }, + { + "name": "quote_enabled", + "description": "Indicates whether negotiable quote functionality is enabled for the current customer. Global and company-level settings are factored into the result.", + "args": [], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "Boolean", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, { "name": "requisition_lists", "description": "An object that contains the customer's requisition lists.", @@ -24729,6 +25141,16 @@ "ofType": null }, "defaultValue": null + }, + { + "name": "sort", + "description": "The field to use for sorting results.", + "type": { + "kind": "INPUT_OBJECT", + "name": "RequisitionListSortInput", + "ofType": null + }, + "defaultValue": null } ], "type": { @@ -26590,6 +27012,18 @@ "isDeprecated": false, "deprecationReason": null }, + { + "name": "negotiable_quote", + "description": "The negotiable quote associated with this order.", + "args": [], + "type": { + "kind": "OBJECT", + "name": "NegotiableQuote", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, { "name": "number", "description": "The order number.", @@ -32442,6 +32876,18 @@ "isDeprecated": false, "deprecationReason": null }, + { + "name": "three_ds_mode", + "description": "3DS mode", + "args": [], + "type": { + "kind": "ENUM", + "name": "ThreeDSMode", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, { "name": "title", "description": "The name displayed for the payment method", @@ -38662,6 +39108,113 @@ "enumValues": null, "possibleTypes": null }, + { + "kind": "OBJECT", + "name": "HistoryItemNoteData", + "description": "Item note data that is added to the negotiable quote history object.", + "fields": [ + { + "name": "created_at", + "description": "Datetime of the note added.", + "args": [], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "creator_name", + "description": "Name of the creator.", + "args": [], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "creator_type", + "description": "Creator type: Buyer or Seller.", + "args": [], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "item_id", + "description": "Id of the quote item for which the note has been added.", + "args": [], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "Int", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "note", + "description": "The note added by the creator for the item", + "args": [], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "product_name", + "description": "Name of the quote item product for which note has been added.", + "args": [], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [], + "enumValues": null, + "possibleTypes": null + }, { "kind": "OBJECT", "name": "HostedFieldsConfig", @@ -40042,6 +40595,18 @@ "isDeprecated": false, "deprecationReason": null }, + { + "name": "creator_name", + "description": "Name of the creator.", + "args": [], + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, { "name": "creator_type", "description": "Type of teh user who submitted a note.", @@ -43035,35 +43600,8 @@ "deprecationReason": null }, { - "name": "finishUpload", - "description": null, - "args": [ - { - "name": "input", - "description": null, - "type": { - "kind": "NON_NULL", - "name": null, - "ofType": { - "kind": "INPUT_OBJECT", - "name": "finishUploadInput", - "ofType": null - } - }, - "defaultValue": null - } - ], - "type": { - "kind": "OBJECT", - "name": "finishUploadOutput", - "ofType": null - }, - "isDeprecated": false, - "deprecationReason": null - }, - { - "name": "generateCustomerToken", - "description": "Generate a token for specified customer.", + "name": "exchangeOtpForCustomerToken", + "description": "Exchange a customer's one time password for a customer token.", "args": [ { "name": "email", @@ -43080,8 +43618,76 @@ "defaultValue": null }, { - "name": "password", - "description": "The customer's password.", + "name": "otp", + "description": "The customer's OTP.", + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + }, + "defaultValue": null + } + ], + "type": { + "kind": "OBJECT", + "name": "CustomerToken", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "finishUpload", + "description": null, + "args": [ + { + "name": "input", + "description": null, + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "INPUT_OBJECT", + "name": "finishUploadInput", + "ofType": null + } + }, + "defaultValue": null + } + ], + "type": { + "kind": "OBJECT", + "name": "finishUploadOutput", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "generateCustomerToken", + "description": "Generate a token for specified customer.", + "args": [ + { + "name": "email", + "description": "The customer's email address.", + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + }, + "defaultValue": null + }, + { + "name": "password", + "description": "The customer's password.", "type": { "kind": "NON_NULL", "name": null, @@ -44848,6 +45454,33 @@ "isDeprecated": false, "deprecationReason": null }, + { + "name": "setQuoteTemplateExpirationDate", + "description": "Set expiration date to a negotiable quote template.", + "args": [ + { + "name": "input", + "description": "An input object that defines the quote template expiration date.", + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "INPUT_OBJECT", + "name": "QuoteTemplateExpirationDateInput", + "ofType": null + } + }, + "defaultValue": null + } + ], + "type": { + "kind": "OBJECT", + "name": "NegotiableQuoteTemplate", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, { "name": "setQuoteTemplateLineItemNote", "description": "Add buyer's note to a negotiable quote template item.", @@ -45981,6 +46614,18 @@ "isDeprecated": false, "deprecationReason": null }, + { + "name": "order", + "description": "The order created from the negotiable quote.", + "args": [], + "type": { + "kind": "OBJECT", + "name": "CustomerOrder", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, { "name": "prices", "description": "A set of subtotals and totals applied to the negotiable quote.", @@ -47490,6 +48135,18 @@ "isDeprecated": false, "deprecationReason": null }, + { + "name": "item_note", + "description": "Item note data that is added to the negotiable quote history object.", + "args": [], + "type": { + "kind": "OBJECT", + "name": "HistoryItemNoteData", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, { "name": "uid", "description": "The unique ID of a `NegotiableQuoteHistoryEntry` object.", @@ -48475,6 +49132,22 @@ "isDeprecated": false, "deprecationReason": null }, + { + "name": "created_at", + "description": "Timestamp indicating when the negotiable quote template was created.", + "args": [], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, { "name": "expiration_date", "description": "The expiration period of the negotiable quote template.", @@ -48507,6 +49180,22 @@ "isDeprecated": false, "deprecationReason": null }, + { + "name": "historyV2", + "description": null, + "args": [], + "type": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "OBJECT", + "name": "NegotiableQuoteTemplateHistoryEntry", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, { "name": "is_min_max_qty_used", "description": "Indicates whether the minimum and maximum quantity settings are used.", @@ -48647,6 +49336,22 @@ "isDeprecated": false, "deprecationReason": null }, + { + "name": "sales_rep_name", + "description": "The first and last name of the sales representative.", + "args": [], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, { "name": "shipping_addresses", "description": "A list of shipping addresses applied to the negotiable quote template.", @@ -48714,6 +49419,38 @@ }, "isDeprecated": false, "deprecationReason": null + }, + { + "name": "uid", + "description": "The unique ID of a `NegotiableQuoteTemplate` object.", + "args": [], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "ID", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "updated_at", + "description": "Timestamp indicating when the negotiable quote template was updated.", + "args": [], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null } ], "inputFields": null, @@ -48789,6 +49526,22 @@ "isDeprecated": false, "deprecationReason": null }, + { + "name": "created_at", + "description": "Timestamp indicating when the negotiable quote template was created.", + "args": [], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, { "name": "expiration_date", "description": "The expiration period of the negotiable quote template.", @@ -48821,6 +49574,22 @@ "isDeprecated": false, "deprecationReason": null }, + { + "name": "last_ordered_at", + "description": "Timestamp indicating when the last negotiable quote template order was placed.", + "args": [], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, { "name": "last_shared_at", "description": "The date and time the negotiable quote template was last shared.", @@ -48917,6 +49686,18 @@ "isDeprecated": false, "deprecationReason": null }, + { + "name": "prices", + "description": "A set of subtotals and totals applied to the negotiable quote template.", + "args": [], + "type": { + "kind": "OBJECT", + "name": "CartPrices", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, { "name": "sales_rep_name", "description": "The first and last name of the sales representative.", @@ -48996,6 +49777,278 @@ }, "isDeprecated": false, "deprecationReason": null + }, + { + "name": "uid", + "description": "The unique ID of a `NegotiableQuoteTemplate` object.", + "args": [], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "ID", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "updated_at", + "description": "Timestamp indicating when the negotiable quote template was updated.", + "args": [], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [], + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "OBJECT", + "name": "NegotiableQuoteTemplateHistoryChanges", + "description": "Contains a list of changes to a negotiable quote template.", + "fields": [ + { + "name": "comment_added", + "description": "The comment provided with a change in the negotiable quote history.", + "args": [], + "type": { + "kind": "OBJECT", + "name": "NegotiableQuoteHistoryCommentChange", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "custom_changes", + "description": "Lists log entries added by third-party extensions.", + "args": [], + "type": { + "kind": "OBJECT", + "name": "NegotiableQuoteCustomLogChange", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "expiration", + "description": "The expiration date of the negotiable quote before and after a change in the quote history.", + "args": [], + "type": { + "kind": "OBJECT", + "name": "NegotiableQuoteHistoryExpirationChange", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "products_removed", + "description": "Lists products that were removed as a result of a change in the quote history.", + "args": [], + "type": { + "kind": "OBJECT", + "name": "NegotiableQuoteHistoryProductsRemovedChange", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "statuses", + "description": "The status before and after a change in the negotiable quote template history.", + "args": [], + "type": { + "kind": "OBJECT", + "name": "NegotiableQuoteTemplateHistoryStatusesChange", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "total", + "description": "The total amount of the negotiable quote before and after a change in the quote history.", + "args": [], + "type": { + "kind": "OBJECT", + "name": "NegotiableQuoteHistoryTotalChange", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [], + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "OBJECT", + "name": "NegotiableQuoteTemplateHistoryEntry", + "description": "Contains details about a change for a negotiable quote template.", + "fields": [ + { + "name": "author", + "description": "The person who made a change in the status of the negotiable quote.", + "args": [], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "OBJECT", + "name": "NegotiableQuoteUser", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "change_type", + "description": "An enum that specifies the reason for a status change in the negotiable quote history entry.", + "args": [], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "ENUM", + "name": "NegotiableQuoteHistoryEntryChangeType", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "changes", + "description": "The set of changes in the negotiable quote template.", + "args": [], + "type": { + "kind": "OBJECT", + "name": "NegotiableQuoteTemplateHistoryChanges", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "created_at", + "description": "Timestamp indicating when the negotiable quote entry was created.", + "args": [], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "uid", + "description": "The unique ID of a `NegotiableQuoteHistoryEntry` object.", + "args": [], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "ID", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [], + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "OBJECT", + "name": "NegotiableQuoteTemplateHistoryStatusChange", + "description": "Lists a new status change applied to a negotiable quote template and the previous status.", + "fields": [ + { + "name": "new_status", + "description": "The updated status.", + "args": [], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "old_status", + "description": "The previous status. The value will be null for the first history entry in a negotiable quote.", + "args": [], + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [], + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "OBJECT", + "name": "NegotiableQuoteTemplateHistoryStatusesChange", + "description": "Contains a list of status changes that occurred for the negotiable quote template.", + "fields": [ + { + "name": "changes", + "description": "A list of status changes.", + "args": [], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "OBJECT", + "name": "NegotiableQuoteTemplateHistoryStatusChange", + "ofType": null + } + } + }, + "isDeprecated": false, + "deprecationReason": null } ], "inputFields": null, @@ -54663,6 +55716,22 @@ }, "isDeprecated": false, "deprecationReason": null + }, + { + "name": "warnings", + "description": "An array of warning messages for validation issues (e.g., sort parameter ignored due to missing categoryPath)", + "args": [], + "type": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "OBJECT", + "name": "ProductSearchWarning", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null } ], "inputFields": null, @@ -54709,6 +55778,49 @@ "enumValues": null, "possibleTypes": null }, + { + "kind": "OBJECT", + "name": "ProductSearchWarning", + "description": "Structured warning with code and message for easier client handling", + "fields": [ + { + "name": "code", + "description": "Error code for programmatic handling (e.g., EMPTY_CATEGORY_PATH)", + "args": [], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "message", + "description": "Human-readable message describing the warning", + "args": [], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [], + "enumValues": null, + "possibleTypes": null + }, { "kind": "ENUM", "name": "ProductStockStatus", @@ -54852,7 +55964,7 @@ }, { "name": "attributes", - "description": "A list of merchant-defined attributes designated for the storefront.", + "description": "A list of merchant-defined attributes designated for the storefront. They can be filtered by roles and names.", "args": [ { "name": "roles", @@ -54867,6 +55979,20 @@ } }, "defaultValue": null + }, + { + "name": "names", + "description": null, + "type": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + }, + "defaultValue": null } ], "type": { @@ -55127,6 +56253,37 @@ "isDeprecated": false, "deprecationReason": null }, + { + "name": "categories", + "description": "A list of categories in which the product is present.", + "args": [ + { + "name": "family", + "description": null, + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + } + ], + "type": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "OBJECT", + "name": "CategoryProductView", + "ofType": null + } + } + }, + "isDeprecated": false, + "deprecationReason": null + }, { "name": "queryType", "description": "Indicates if the product was retrieved from the primary or the backup query", @@ -57399,16 +58556,12 @@ "description": "The approval flows for each applied rules.", "args": [], "type": { - "kind": "NON_NULL", + "kind": "LIST", "name": null, "ofType": { - "kind": "LIST", - "name": null, - "ofType": { - "kind": "OBJECT", - "name": "PurchaseOrderRuleApprovalFlow", - "ofType": null - } + "kind": "OBJECT", + "name": "PurchaseOrderRuleApprovalFlow", + "ofType": null } }, "isDeprecated": false, @@ -59129,7 +60282,7 @@ }, { "name": "navigation", - "description": "Retrieve category navigation data optimized for storefront menu rendering with built-in performance safeguards.\n\n**Performance Features:**\n- Limited to 4 levels deep for optimal rendering\n- Single database query per family\n- Heavily cached responses\n- Excludes heavyweight category attributes", + "description": "Retrieves the navigation tree for a given product family.", "args": [ { "name": "family", @@ -59160,7 +60313,7 @@ }, { "name": "categoryTree", - "description": "Retrieve hierarchical category data in a tree structure with parent-child relationships and level information.\n\n**Primary Use Case:** RetailCMS applications requiring full category tree management.", + "description": "Retrieves category tree nodes, optionally filtered by slugs and limited by depth.", "args": [ { "name": "family", @@ -59355,6 +60508,22 @@ "isDeprecated": false, "deprecationReason": null }, + { + "name": "commerceOptimizer", + "description": "Provide necessary information to build headless storefront when Adobe Commerce is connected to Commerce Optimizer.", + "args": [], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "OBJECT", + "name": "CommerceOptimizerContext", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, { "name": "company", "description": "Return detailed information about the customer's company within the current company context.", @@ -60743,13 +61912,27 @@ }, { "kind": "INPUT_OBJECT", - "name": "QuoteTemplateLineItemNoteInput", - "description": "Sets quote item note.", + "name": "QuoteTemplateExpirationDateInput", + "description": "Sets quote template expiration date.", "fields": null, "inputFields": [ { - "name": "item_id", - "description": "The unique ID of a `CartLineItem` object.", + "name": "expiration_date", + "description": "The expiration period of the negotiable quote template.", + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + }, + "defaultValue": null + }, + { + "name": "template_id", + "description": "The unique ID of a `NegotiableQuoteTemplate` object.", "type": { "kind": "NON_NULL", "name": null, @@ -60760,6 +61943,37 @@ } }, "defaultValue": null + } + ], + "interfaces": null, + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "INPUT_OBJECT", + "name": "QuoteTemplateLineItemNoteInput", + "description": "Sets quote item note.", + "fields": null, + "inputFields": [ + { + "name": "item_id", + "description": "The unique ID of a `CartLineItem` object.", + "type": { + "kind": "SCALAR", + "name": "ID", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "item_uid", + "description": "The unique ID of a `CartLineItem` object.", + "type": { + "kind": "SCALAR", + "name": "ID", + "ofType": null + }, + "defaultValue": null }, { "name": "note", @@ -61414,6 +62628,12 @@ "description": "", "isDeprecated": false, "deprecationReason": null + }, + { + "name": "RECAPTCHA_ENTERPRISE", + "description": "", + "isDeprecated": false, + "deprecationReason": null } ], "possibleTypes": null @@ -63075,6 +64295,18 @@ "isDeprecated": false, "deprecationReason": null }, + { + "name": "sort_fields", + "description": "Contains the default sort field and all available sort fields.", + "args": [], + "type": { + "kind": "OBJECT", + "name": "SortFields", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, { "name": "total_count", "description": "The number of returned requisition lists.", @@ -63093,6 +64325,64 @@ "enumValues": null, "possibleTypes": null }, + { + "kind": "ENUM", + "name": "RequisitionListSortableField", + "description": "", + "fields": null, + "inputFields": null, + "interfaces": null, + "enumValues": [ + { + "name": "NAME", + "description": "Sorts requisition lists by requisition list name.", + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "UPDATED_AT", + "description": "Sorts requisition lists by the date they were last updated.", + "isDeprecated": false, + "deprecationReason": null + } + ], + "possibleTypes": null + }, + { + "kind": "INPUT_OBJECT", + "name": "RequisitionListSortInput", + "description": "Defines the field to use to sort a list of requisition lists.", + "fields": null, + "inputFields": [ + { + "name": "sort_direction", + "description": "Whether to return results in ascending or descending order.", + "type": { + "kind": "ENUM", + "name": "SortEnum", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "sort_field", + "description": "The specified sort field.", + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "ENUM", + "name": "RequisitionListSortableField", + "ofType": null + } + }, + "defaultValue": null + } + ], + "interfaces": null, + "enumValues": null, + "possibleTypes": null + }, { "kind": "OBJECT", "name": "RequistionListItems", @@ -68650,7 +69940,7 @@ }, { "name": "attributes", - "description": "A list of merchant-defined attributes designated for the storefront.", + "description": "A list of merchant-defined attributes designated for the storefront. They can be filtered by names and roles.", "args": [ { "name": "roles", @@ -68665,6 +69955,20 @@ } }, "defaultValue": null + }, + { + "name": "names", + "description": null, + "type": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + }, + "defaultValue": null } ], "type": { @@ -68937,6 +70241,37 @@ "isDeprecated": false, "deprecationReason": null }, + { + "name": "categories", + "description": "A list of categories in which the product is present.", + "args": [ + { + "name": "family", + "description": null, + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + } + ], + "type": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "OBJECT", + "name": "CategoryProductView", + "ofType": null + } + } + }, + "isDeprecated": false, + "deprecationReason": null + }, { "name": "queryType", "description": "Indicates if the product was retrieved from the primary or the backup query", @@ -69217,6 +70552,18 @@ "name": "SmartButtonsConfig", "description": "", "fields": [ + { + "name": "app_switch_when_available", + "description": "Indicated whether to use App Switch on enabled mobile devices", + "args": [], + "type": { + "kind": "SCALAR", + "name": "Boolean", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, { "name": "button_styles", "description": "The styles for the PayPal Smart Button configuration", @@ -71108,6 +72455,30 @@ "isDeprecated": false, "deprecationReason": null }, + { + "name": "quote_minimum_amount", + "description": "Minimum order total for quote request.", + "args": [], + "type": { + "kind": "SCALAR", + "name": "Float", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "quote_minimum_amount_message", + "description": "A message that will be shown in the cart when the subtotal (after discount) is lower than the minimum allowed amount.", + "args": [], + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, { "name": "required_character_classes_number", "description": "The number of different character classes (lowercase, uppercase, digits, special characters) required in a password.", @@ -71697,6 +73068,20 @@ "description": "Specifies the quote template properties to update.", "fields": null, "inputFields": [ + { + "name": "attachments", + "description": "Negotiable quote template comment file attachments.", + "type": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "INPUT_OBJECT", + "name": "NegotiableQuoteCommentAttachmentInput", + "ofType": null + } + }, + "defaultValue": null + }, { "name": "comment", "description": "A comment for the seller to review.", @@ -75843,6 +77228,6 @@ } }, "extensions": { - "request-id": "1c0120e5-ff89-409b-a9b1-0dfc1c8e0a86" + "request-id": "a66dc877-4f7b-4cc5-9810-56df320e9477" } } \ No newline at end of file diff --git a/spectaql/metadata-merchandising.json b/spectaql/metadata-merchandising.json index 17db940f..f5449059 100644 --- a/spectaql/metadata-merchandising.json +++ b/spectaql/metadata-merchandising.json @@ -1,5 +1,229 @@ { "OBJECT": { + "Query": { + "fields": { + "attributesForm": { + "documentation": { + "undocumented": true + } + }, + "attributesList": { + "documentation": { + "undocumented": true + } + }, + "availableStores": { + "documentation": { + "undocumented": true + } + }, + "cart": { + "documentation": { + "undocumented": true + } + }, + "categories": { + "documentation": { + "undocumented": true + } + }, + "checkoutAgreements": { + "documentation": { + "undocumented": true + } + }, + "company": { + "documentation": { + "undocumented": true + } + }, + "commerceOptimizer": { + "documentation": { + "undocumented": true + } + }, + "compareList": { + "documentation": { + "undocumented": true + } + }, + "countries": { + "documentation": { + "undocumented": true + } + }, + "country": { + "documentation": { + "undocumented": true + } + }, + "currency": { + "documentation": { + "undocumented": true + } + }, + "customAttributeMetadataV2": { + "documentation": { + "undocumented": true + } + }, + "customer": { + "documentation": { + "undocumented": true + } + }, + "customerCart": { + "documentation": { + "undocumented": true + } + }, + "customerDownloadableProducts": { + "documentation": { + "undocumented": true + } + }, + "customerGroup": { + "documentation": { + "undocumented": true + } + }, + "customerPaymentTokens": { + "documentation": { + "undocumented": true + } + }, + "customerSegments": { + "documentation": { + "undocumented": true + } + }, + "getPaymentConfig": { + "documentation": { + "undocumented": true + } + }, + "getPaymentOrder": { + "documentation": { + "undocumented": true + } + }, + "getPaymentSDK": { + "documentation": { + "undocumented": true + } + }, + "getVaultConfig": { + "documentation": { + "undocumented": true + } + }, + "giftCardAccount": { + "documentation": { + "undocumented": true + } + }, + "giftRegistry": { + "documentation": { + "undocumented": true + } + }, + "giftRegistryEmailSearch": { + "documentation": { + "undocumented": true + } + }, + "giftRegistryIdSearch": { + "documentation": { + "undocumented": true + } + }, + "giftRegistryTypeSearch": { + "documentation": { + "undocumented": true + } + }, + "giftRegistryTypes": { + "documentation": { + "undocumented": true + } + }, + "guestOrder": { + "documentation": { + "undocumented": true + } + }, + "guestOrderByToken": { + "documentation": { + "undocumented": true + } + }, + "isCompanyAdminEmailAvailable": { + "documentation": { + "undocumented": true + } + }, + "isCompanyEmailAvailable": { + "documentation": { + "undocumented": true + } + }, + "isCompanyRoleNameAvailable": { + "documentation": { + "undocumented": true + } + }, + "isCompanyUserEmailAvailable": { + "documentation": { + "undocumented": true + } + }, + "isEmailAvailable": { + "documentation": { + "undocumented": true + } + }, + "negotiableQuote": { + "documentation": { + "undocumented": true + } + }, + "negotiableQuoteTemplate": { + "documentation": { + "undocumented": true + } + }, + "negotiableQuoteTemplates": { + "documentation": { + "undocumented": true + } + }, + "negotiableQuotes": { + "documentation": { + "undocumented": true + } + }, + "pickupLocations": { + "documentation": { + "undocumented": true + } + }, + "recaptchaFormConfig": { + "documentation": { + "undocumented": true + } + }, + "recaptchaV3Config": { + "documentation": { + "undocumented": true + } + }, + "storeConfig": { + "documentation": { + "undocumented": true + } + } + } + }, "AddCustomAttributesToCartItemOutput": { "documentation": { "undocumented": true @@ -20,6 +244,11 @@ "undocumented": true } }, + "AddProductsToNewCartOutput": { + "documentation": { + "undocumented": true + } + }, "AddProductsToRequisitionListOutput": { "documentation": { "undocumented": true @@ -65,11 +294,6 @@ "undocumented": true } }, - "AggregationOptionInterface": { - "documentation": { - "undocumented": true - } - }, "ApplePayConfig": { "documentation": { "undocumented": true @@ -135,47 +359,47 @@ "undocumented": true } }, - "AttributeMetadata": { + "AttributeFile": { "documentation": { "undocumented": true } }, - "AttributeMetadataError": { + "AttributeImage": { "documentation": { "undocumented": true } }, - "AttributeOption": { + "AttributeMetadata": { "documentation": { "undocumented": true } }, - "AttributeOptionMetadata": { + "AttributeMetadataError": { "documentation": { "undocumented": true } }, - "AttributeSelectedOption": { + "AttributeOption": { "documentation": { "undocumented": true } }, - "AttributeSelectedOptionInterface": { + "AttributeOptionMetadata": { "documentation": { "undocumented": true } }, - "AttributeSelectedOptions": { + "AttributeSelectedOption": { "documentation": { "undocumented": true } }, - "AttributeValue": { + "AttributeSelectedOptions": { "documentation": { "undocumented": true } }, - "AttributeValueInterface": { + "AttributeValue": { "documentation": { "undocumented": true } @@ -310,11 +534,6 @@ "undocumented": true } }, - "CartAddressInterface": { - "documentation": { - "undocumented": true - } - }, "CartAddressRegion": { "documentation": { "undocumented": true @@ -325,17 +544,12 @@ "undocumented": true } }, - "CartItemInterface": { + "CartItemPrices": { "documentation": { "undocumented": true } }, - "CartItemPrices": { - "documentation": { - "undocumented": true - } - }, - "CartItemSelectedOptionValuePrice": { + "CartItemSelectedOptionValuePrice": { "documentation": { "undocumented": true } @@ -370,26 +584,11 @@ "undocumented": true } }, - "CategoryBucketInterface": { - "documentation": { - "undocumented": true - } - }, - "CategoryInterface": { - "documentation": { - "undocumented": true - } - }, "CategoryTree": { "documentation": { "undocumented": true } }, - "CategoryViewInterface": { - "documentation": { - "undocumented": true - } - }, "CheckoutAgreement": { "documentation": { "undocumented": true @@ -435,6 +634,11 @@ "undocumented": true } }, + "CompanyAvailableShippingMethod": { + "documentation": { + "undocumented": true + } + }, "CompanyBasicInfo": { "documentation": { "undocumented": true @@ -675,11 +879,6 @@ "undocumented": true } }, - "CreditMemoItemInterface": { - "documentation": { - "undocumented": true - } - }, "CreditMemoOutput": { "documentation": { "undocumented": true @@ -700,16 +899,6 @@ "undocumented": true } }, - "CustomAttributeMetadataInterface": { - "documentation": { - "undocumented": true - } - }, - "CustomAttributeOptionInterface": { - "documentation": { - "undocumented": true - } - }, "CustomConfigKeyValue": { "documentation": { "undocumented": true @@ -875,16 +1064,6 @@ "undocumented": true } }, - "CustomizableOptionInterface": { - "documentation": { - "undocumented": true - } - }, - "CustomizableProductInterface": { - "documentation": { - "undocumented": true - } - }, "CustomizableRadioOption": { "documentation": { "undocumented": true @@ -1020,27 +1199,22 @@ "undocumented": true } }, - "Error": { - "documentation": { - "undocumented": true - } - }, - "ErrorInterface": { + "EstimateTotalsOutput": { "documentation": { "undocumented": true } }, - "EstimateTotalsOutput": { + "ExchangeExternalCustomerTokenOutput": { "documentation": { "undocumented": true } }, - "ExchangeExternalCustomerTokenOutput": { + "ExchangeRate": { "documentation": { "undocumented": true } }, - "ExchangeRate": { + "FastlaneConfig": { "documentation": { "undocumented": true } @@ -1145,36 +1319,16 @@ "undocumented": true } }, - "GiftRegistryDynamicAttributeInterface": { - "documentation": { - "undocumented": true - } - }, "GiftRegistryDynamicAttributeMetadata": { "documentation": { "undocumented": true } }, - "GiftRegistryDynamicAttributeMetadataInterface": { - "documentation": { - "undocumented": true - } - }, "GiftRegistryItem": { "documentation": { "undocumented": true } }, - "GiftRegistryItemInterface": { - "documentation": { - "undocumented": true - } - }, - "GiftRegistryItemUserErrorInterface": { - "documentation": { - "undocumented": true - } - }, "GiftRegistryItemUserErrors": { "documentation": { "undocumented": true @@ -1190,11 +1344,6 @@ "undocumented": true } }, - "GiftRegistryOutputInterface": { - "documentation": { - "undocumented": true - } - }, "GiftRegistryRegistrant": { "documentation": { "undocumented": true @@ -1280,11 +1429,6 @@ "undocumented": true } }, - "InvoiceItemInterface": { - "documentation": { - "undocumented": true - } - }, "InvoiceOutput": { "documentation": { "undocumented": true @@ -1345,11 +1489,6 @@ "undocumented": true } }, - "MediaGalleryInterface": { - "documentation": { - "undocumented": true - } - }, "MessageStyleLogo": { "documentation": { "undocumented": true @@ -1385,11 +1524,6 @@ "undocumented": true } }, - "Mutation": { - "documentation": { - "undocumented": true - } - }, "NegotiableQuote": { "documentation": { "undocumented": true @@ -1400,22 +1534,22 @@ "undocumented": true } }, - "NegotiableQuoteAddressInterface": { + "NegotiableQuoteAddressRegion": { "documentation": { "undocumented": true } }, - "NegotiableQuoteAddressRegion": { + "NegotiableQuoteBillingAddress": { "documentation": { "undocumented": true } }, - "NegotiableQuoteBillingAddress": { + "NegotiableQuoteComment": { "documentation": { "undocumented": true } }, - "NegotiableQuoteComment": { + "NegotiableQuoteCommentAttachment": { "documentation": { "undocumented": true } @@ -1495,11 +1629,6 @@ "undocumented": true } }, - "NegotiableQuoteUidNonFatalResultInterface": { - "documentation": { - "undocumented": true - } - }, "NegotiableQuoteUidOperationSuccess": { "documentation": { "undocumented": true @@ -1545,11 +1674,6 @@ "undocumented": true } }, - "OrderItemInterface": { - "documentation": { - "undocumented": true - } - }, "OrderItemOption": { "documentation": { "undocumented": true @@ -1580,11 +1704,6 @@ "undocumented": true } }, - "PaymentConfigItem": { - "documentation": { - "undocumented": true - } - }, "PaymentConfigOutput": { "documentation": { "undocumented": true @@ -1615,22 +1734,22 @@ "undocumented": true } }, - "PhysicalProductInterface": { + "PickupLocation": { "documentation": { "undocumented": true } }, - "PickupLocation": { + "PickupLocations": { "documentation": { "undocumented": true } }, - "PickupLocations": { + "PlaceNegotiableQuoteOrderOutput": { "documentation": { "undocumented": true } }, - "PlaceNegotiableQuoteOrderOutput": { + "PlaceNegotiableQuoteOrderOutputV2": { "documentation": { "undocumented": true } @@ -1685,21 +1804,11 @@ "undocumented": true } }, - "ProductInterface": { - "documentation": { - "undocumented": true - } - }, "ProductLinks": { "documentation": { "undocumented": true } }, - "ProductLinksInterface": { - "documentation": { - "undocumented": true - } - }, "ProductMediaGalleryEntriesAssetImage": { "documentation": { "undocumented": true @@ -1730,21 +1839,6 @@ "undocumented": true } }, - "ProductViewInputOption": { - "documentation": { - "undocumented": true - } - }, - "ProductViewInputOptionImageSize": { - "documentation": { - "undocumented": true - } - }, - "ProductViewInputOptionRange": { - "documentation": { - "undocumented": true - } - }, "PurchaseOrder": { "documentation": { "undocumented": true @@ -1770,11 +1864,6 @@ "undocumented": true } }, - "PurchaseOrderApprovalRuleConditionInterface": { - "documentation": { - "undocumented": true - } - }, "PurchaseOrderApprovalRuleConditionQuantity": { "documentation": { "undocumented": true @@ -1920,11 +2009,6 @@ "undocumented": true } }, - "RequisitionListItemInterface": { - "documentation": { - "undocumented": true - } - }, "RequisitionLists": { "documentation": { "undocumented": true @@ -2095,6 +2179,11 @@ "undocumented": true } }, + "SetCartAsInactiveOutput": { + "documentation": { + "undocumented": true + } + }, "SetCustomAttributesOnCompanyOutput": { "documentation": { "undocumented": true @@ -2165,11 +2254,6 @@ "undocumented": true } }, - "ShipmentItemInterface": { - "documentation": { - "undocumented": true - } - }, "ShipmentTracking": { "documentation": { "undocumented": true @@ -2250,11 +2334,6 @@ "undocumented": true } }, - "SwatchDataInterface": { - "documentation": { - "undocumented": true - } - }, "TaxItem": { "documentation": { "undocumented": true @@ -2396,363 +2475,33 @@ } }, "WishListUserInputError": { - "documentation": { - "undocumented": true - } - }, - "Wishlist": { - "documentation": { - "undocumented": true - } - }, - "WishlistCartUserInputError": { - "documentation": { - "undocumented": true - } - }, - "WishlistItemInterface": { - "documentation": { - "undocumented": true - } - }, - "WishlistItems": { - "documentation": { - "undocumented": true - } - }, - "Query": { - "fields": { - "attributesForm": { - "documentation": { - "undocumented": true - } - }, - "attributesList": { - "documentation": { - "undocumented": true - } - }, - "attributesSearch": { - "documentation": { - "undocumented": true - } - }, - "availableStores": { - "documentation": { - "undocumented": true - } - }, - "cart": { - "documentation": { - "undocumented": true - } - }, - "categories": { - "documentation": { - "undocumented": true - } - }, - "checkoutAgreements": { - "documentation": { - "undocumented": true - } - }, - "categoryView": { - "documentation": { - "undocumented": true - } - }, - "company": { - "documentation": { - "undocumented": true - } - }, - "compareList": { - "documentation": { - "undocumented": true - } - }, - "countries": { - "documentation": { - "undocumented": true - } - }, - "country": { - "documentation": { - "undocumented": true - } - }, - "currency": { - "documentation": { - "undocumented": true - } - }, - "customerDownloadableProducts": { - "documentation": { - "undocumented": true - } - }, - "customerGroup": { - "documentation": { - "undocumented": true - } - }, - "customer": { - "documentation": { - "undocumented": true - } - }, - "customerCart": { - "documentation": { - "undocumented": true - } - }, - "customerDownloads": { - "documentation": { - "undocumented": true - } - }, - "customerGroups": { - "documentation": { - "undocumented": true - } - }, - "customerPaymentTokens": { - "documentation": { - "undocumented": true - } - }, - "customerSegments": { - "documentation": { - "undocumented": true - } - }, - "getPaymentConfig": { - "documentation": { - "undocumented": true - } - }, - "getPaymentOrder": { - "documentation": { - "undocumented": true - } - }, - "getPaymentSDK": { - "documentation": { - "undocumented": true - } - }, - "getVaultConfig": { - "documentation": { - "undocumented": true - } - }, - "giftCardAccount": { - "documentation": { - "undocumented": true - } - }, - "giftRegistry": { - "documentation": { - "undocumented": true - } - }, - "giftRegistryEmailSearch": { - "documentation": { - "undocumented": true - } - }, - "giftRegistryIdSearch": { - "documentation": { - "undocumented": true - } - }, - "giftRegistryTypeSearch": { - "documentation": { - "undocumented": true - } - }, - "giftRegistryTypes": { - "documentation": { - "undocumented": true - } - }, - "guestOrder": { - "documentation": { - "undocumented": true - } - }, - "guestOrderByToken": { - "documentation": { - "undocumented": true - } - }, - "guestOrderByTokenSearch": { - "documentation": { - "undocumented": true - } - }, - "isCompanyAdminEmailAvailable": { - "documentation": { - "undocumented": true - } - }, - "isCompanyEmailAvailable": { - "documentation": { - "undocumented": true - } - }, - "isCompanyRoleNameAvailable": { - "documentation": { - "undocumented": true - } - }, - "isCompanyUserEmailAvailable": { - "documentation": { - "undocumented": true - } - }, - "isEmailAvailable": { - "documentation": { - "undocumented": true - } - }, - "negotiableQuote": { - "documentation": { - "undocumented": true - } - }, - "negotiableQuoteTemplate": { - "documentation": { - "undocumented": true - } - }, - "negotiableQuoteTemplates": { - "documentation": { - "undocumented": true - } - }, - "negotiableQuotes": { - "documentation": { - "undocumented": true - } - }, - "pickupLocations": { - "documentation": { - "undocumented": true - } - }, - "recaptchaFormConfig": { - "documentation": { - "undocumented": true - } - }, - "recaptchaV3Config": { - "documentation": { - "undocumented": true - } - }, - "storeConfig": { - "documentation": { - "undocumented": true - } - }, - "categoryTree": { - "documentation": { - "description": "Retrieve hierarchical category data in a tree structure with parent-child relationships and level information.\n\n**Primary Use Case:** RetailCMS applications requiring full category tree management.", - "undocumented": false - } - }, - "navigation": { - "documentation": { - "description": "Retrieve category navigation data optimized for storefront menu rendering with built-in performance safeguards.\n\n**Performance Features:**\n- Limited to 4 levels deep for optimal rendering\n- Single database query per family\n- Heavily cached responses\n- Excludes heavyweight category attributes", - "undocumented": false - } - } - } - }, - "CategoryTreeView": { - "documentation": { - "description": "Represents a category in a hierarchical tree structure with comprehensive parent-child relationship metadata.\n\n**Key Features:**\n- Implements CategoryViewV2 interface\n- Designed for RetailCMS applications\n- Full category tree management capabilities\n\n**Provides:**\n- Level depth information\n- Parent slug references\n- Children slug collections\n- Complete hierarchy metadata", - "undocumented": false - }, - "fields": { - "slug": { - "documentation": { - "description": "The unique URL-friendly identifier for the category, used in routing and navigation.", - "undocumented": false - } - }, - "name": { - "documentation": { - "description": "The display name of the category as shown to customers in the storefront.", - "undocumented": false - } - }, - "level": { - "documentation": { - "description": "The hierarchical depth level of the category in the tree structure.\n\n**Level Structure:**\n- Root categories: level 0\n- First-level children: level 1\n- Second-level children: level 2\n- And so on...\n\n**Used For:** Tree traversal and hierarchy management in RetailCMS applications.", - "undocumented": false - } - }, - "parentSlug": { - "documentation": { - "description": "The slug of the immediate parent category in the hierarchy.\n\n**Values:**\n- Parent category slug for child categories\n- `null` for root-level categories\n\n**Common Uses:**\n- Building breadcrumb navigation\n- Understanding category relationships\n- Tree management system operations", - "undocumented": false - } - }, - "childrenSlugs": { - "documentation": { - "description": "Array of slugs for all direct child categories (immediate descendants only).\n\n**Contains:**\n- Slugs of immediate children only (not grandchildren)\n- Empty array if no children exist\n\n**Benefits:**\n- Determine subcategory existence without fetching full objects\n- Efficient category tree management\n- Quick hierarchy assessment", - "undocumented": false - } - } + "documentation": { + "undocumented": true } }, - "CategoryViewV2": { + "Wishlist": { "documentation": { - "description": "Lightweight base interface for category view models designed for storefront APIs without backward compatibility constraints.\n\n**Design Principles:**\n- Minimal essential properties (slug and name only)\n- Optimal performance for storefront use cases\n- No coupling with search facets\n\n**Replaces:** The heavyweight CategoryView interface\n\n**Implemented By:**\n- CategoryNavigationView (menu rendering)\n- CategoryTreeView (hierarchy management)", - "undocumented": false - }, - "fields": { - "slug": { - "documentation": { - "description": "The unique URL-friendly identifier for the category, used in routing and navigation.", - "undocumented": false - } - }, - "name": { - "documentation": { - "description": "The display name of the category as shown to customers in the storefront.", - "undocumented": false - } - } + "undocumented": true } }, - "CategoryNavigationView": { + "WishlistCartUserInputError": { "documentation": { - "description": "Represents a category optimized for storefront menu rendering with recursive child category structure.\n\n**Performance Safeguards:**\n- Limited to 4 levels deep\n- Excludes heavyweight category attributes\n- Supports heavy caching\n- Single query optimization\n\n**Ideal For:**\n- Responsive navigation components\n- Dropdown menus\n- Mobile navigation\n- Breadcrumb systems", - "undocumented": false - }, - "fields": { - "slug": { - "documentation": { - "description": "The unique URL-friendly identifier for the category, used in routing and navigation.", - "undocumented": false - } - }, - "name": { - "documentation": { - "description": "The display name of the category as shown to customers in the storefront navigation.", - "undocumented": false - } - }, - "children": { - "documentation": { - "description": "Array of direct child categories in a recursive structure.\n\n**Structure:**\n- Each child contains their own children (recursive)\n- Limited to 4 levels deep for performance\n- Empty array if no children or max depth reached\n\n**Optimized For:** Multi-level navigation menu rendering with built-in performance safeguards.", - "undocumented": false - } - } + "undocumented": true + } + }, + "WishlistItems": { + "documentation": { + "undocumented": true + } + }, + "finishUploadOutput": { + "documentation": { + "undocumented": true + } + }, + "initiateUploadOutput": { + "documentation": { + "undocumented": true } } }, @@ -2997,6 +2746,11 @@ "undocumented": true } }, + "CompleteOrderInput": { + "documentation": { + "undocumented": true + } + }, "ConfirmCancelOrderInput": { "documentation": { "undocumented": true @@ -3187,6 +2941,11 @@ "undocumented": true } }, + "FastlaneMethodInput": { + "documentation": { + "undocumented": true + } + }, "FilterEqualTypeInput": { "documentation": { "undocumented": true @@ -3297,6 +3056,11 @@ "undocumented": true } }, + "NegotiableQuoteCommentAttachmentInput": { + "documentation": { + "undocumented": true + } + }, "NegotiableQuoteCommentInput": { "documentation": { "undocumented": true @@ -3417,21 +3181,6 @@ "undocumented": true } }, - "ProductSearchFilterInput": { - "documentation": { - "undocumented": false - } - }, - "ProductSearchSortInput": { - "documentation": { - "undocumented": false - } - }, - "PurchaseHistory": { - "documentation": { - "undocumented": false - } - }, "PurchaseOrderApprovalRuleInput": { "documentation": { "undocumented": true @@ -3447,11 +3196,6 @@ "undocumented": true } }, - "QueryContextInput": { - "documentation": { - "undocumented": false - } - }, "QuoteItemsSortInput": { "documentation": { "undocumented": true @@ -3547,16 +3291,6 @@ "undocumented": true } }, - "SearchClauseInput": { - "documentation": { - "undocumented": true - } - }, - "SearchRangeInput": { - "documentation": { - "undocumented": true - } - }, "SelectedCustomAttributeInput": { "documentation": { "undocumented": true @@ -3742,32 +3476,32 @@ "undocumented": true } }, - "ViewHistory": { + "WishlistItemCopyInput": { "documentation": { - "undocumented": false + "undocumented": true } }, - "ViewHistoryInput": { + "WishlistItemInput": { "documentation": { "undocumented": true } }, - "WishlistItemCopyInput": { + "WishlistItemMoveInput": { "documentation": { "undocumented": true } }, - "WishlistItemInput": { + "WishlistItemUpdateInput": { "documentation": { "undocumented": true } }, - "WishlistItemMoveInput": { + "finishUploadInput": { "documentation": { "undocumented": true } }, - "WishlistItemUpdateInput": { + "initiateUploadInput": { "documentation": { "undocumented": true } @@ -3929,6 +3663,11 @@ "undocumented": true } }, + "MediaResourceType": { + "documentation": { + "undocumented": true + } + }, "NegotiableQuoteCommentCreatorType": { "documentation": { "undocumented": true @@ -3959,11 +3698,6 @@ "undocumented": true } }, - "PageType": { - "documentation": { - "undocumented": false - } - }, "PaymentLocation": { "documentation": { "undocumented": true @@ -4074,11 +3808,6 @@ "undocumented": true } }, - "SortEnum": { - "documentation": { - "undocumented": true - } - }, "SortQuoteItemsEnum": { "documentation": { "undocumented": true @@ -4162,6 +3891,168 @@ } } }, + "INTERFACE": { + "AggregationOptionInterface": { + "documentation": { + "undocumented": true + } + }, + "AttributeSelectedOptionInterface": { + "documentation": { + "undocumented": true + } + }, + "AttributeValueInterface": { + "documentation": { + "undocumented": true + } + }, + "CartAddressInterface": { + "documentation": { + "undocumented": true + } + }, + "CartItemInterface": { + "documentation": { + "undocumented": true + } + }, + "CategoryInterface": { + "documentation": { + "undocumented": true + } + }, + "CreditMemoItemInterface": { + "documentation": { + "undocumented": true + } + }, + "CustomAttributeMetadataInterface": { + "documentation": { + "undocumented": true + } + }, + "CustomAttributeOptionInterface": { + "documentation": { + "undocumented": true + } + }, + "CustomizableOptionInterface": { + "documentation": { + "undocumented": true + } + }, + "CustomizableProductInterface": { + "documentation": { + "undocumented": true + } + }, + "Error": { + "documentation": { + "undocumented": true + } + }, + "ErrorInterface": { + "documentation": { + "undocumented": true + } + }, + "GiftRegistryDynamicAttributeInterface": { + "documentation": { + "undocumented": true + } + }, + "GiftRegistryDynamicAttributeMetadataInterface": { + "documentation": { + "undocumented": true + } + }, + "GiftRegistryItemInterface": { + "documentation": { + "undocumented": true + } + }, + "GiftRegistryItemUserErrorInterface": { + "documentation": { + "undocumented": true + } + }, + "GiftRegistryOutputInterface": { + "documentation": { + "undocumented": true + } + }, + "InvoiceItemInterface": { + "documentation": { + "undocumented": true + } + }, + "MediaGalleryInterface": { + "documentation": { + "undocumented": true + } + }, + "NegotiableQuoteAddressInterface": { + "documentation": { + "undocumented": true + } + }, + "NegotiableQuoteUidNonFatalResultInterface": { + "documentation": { + "undocumented": true + } + }, + "OrderItemInterface": { + "documentation": { + "undocumented": true + } + }, + "PaymentConfigItem": { + "documentation": { + "undocumented": true + } + }, + "PhysicalProductInterface": { + "documentation": { + "undocumented": true + } + }, + "ProductInterface": { + "documentation": { + "undocumented": true + } + }, + "ProductLinksInterface": { + "documentation": { + "undocumented": true + } + }, + "PurchaseOrderApprovalRuleConditionInterface": { + "documentation": { + "undocumented": true + } + }, + "RequisitionListItemInterface": { + "documentation": { + "undocumented": true + } + }, + "ShipmentItemInterface": { + "documentation": { + "undocumented": true + } + }, + "SwatchDataInterface": { + "documentation": { + "undocumented": true + } + }, + "WishlistItemInterface": { + "documentation": { + "undocumented": true + } + } + }, "FIELD_ARGUMENT": { "Query": { "categoryTree": { diff --git a/src/pages/optimizer/data-ingestion/api-testing.md b/src/pages/optimizer/data-ingestion/api-testing.md index 218bafb8..54289228 100644 --- a/src/pages/optimizer/data-ingestion/api-testing.md +++ b/src/pages/optimizer/data-ingestion/api-testing.md @@ -60,7 +60,7 @@ Follow these steps to test any API operation using the interactive documentation - Click **Try it** for the operation you want to test. -2. **Configure the endpoint:** In the request template, replace the `tenantId` placeholder with your instance ID. +1. **Configure the endpoint:** In the request template, replace the `tenantId` placeholder with your instance ID. 1. **Add authentication:** Select the **Parameters** tab, and replace the **Authorization** value with the access token you generated in Step 1. @@ -106,7 +106,7 @@ Here's a practical example of testing the Create Metadata endpoint: "searchWeight": 1, "searchTypes": [ "AUTOCOMPLETE" - ] + ] } ] ``` @@ -161,6 +161,6 @@ Here's a practical example of testing the Create Metadata endpoint: After successfully testing API operations: -1. **Integrate with your application** - Use the [Get Started guide](using-the-api.md) to implement API calls in your code -3. **Explore SDKs** - Consider using the [TypeScript](https://github.com/adobe-commerce/aco-ts-sdk) or [Java](https://github.com/adobe-commerce/aco-java-sdk) SDKs for easier integration -4. **Review limitations** - Understand [rate limits and boundaries](using-the-api.md#limitations) for production use. +1. **Integrate with your application** - Use the [Get Started guide](using-the-api.md) to implement API calls in your code. +2. **Explore SDKs** - Consider using the [TypeScript](https://github.com/adobe-commerce/aco-ts-sdk) or [Java](https://github.com/adobe-commerce/aco-java-sdk) SDKs for easier integration. +3. **Review limitations** - Understand [rate limits and boundaries](using-the-api.md#limitations) for production use. diff --git a/src/pages/optimizer/merchandising-services/categories-storefront-implementation.md b/src/pages/optimizer/merchandising-services/categories-storefront-implementation.md index e506b517..a3936d4e 100644 --- a/src/pages/optimizer/merchandising-services/categories-storefront-implementation.md +++ b/src/pages/optimizer/merchandising-services/categories-storefront-implementation.md @@ -9,9 +9,9 @@ keywords: - Performance --- -# Implement Categories on the Storefront +# Implement categories on the storefront -Managing categories with Commerce projects that use Merchandising Services composable catalog data model requires two types of API operations: +Managing categories with Commerce projects that use the Merchandising Services composable catalog data model requires two types of API operations: - Create category data using the `categories` operations available in the [Data Ingestion API](https://developer.adobe.com/commerce/services/reference/rest/#tag/Categories), and using the `products` operations to manage product category assignments. @@ -21,9 +21,9 @@ Managing categories with Commerce projects that use Merchandising Services compo For Commerce sites with an Adobe Commerce as a Cloud Service or Adobe Commerce on Cloud infrastructure backend, use the [Commerce REST API](https://developer.adobe.com/commerce/webapi/rest/) and the [Catalog Service GraphQL API](https://developer.adobe.com/commerce/webapi/graphql/schema/catalog-service/) to manage categories. -## CategoryView2 interface +## CategoryViewV2 interface -The `CategoryView2` interface provides a minimal, streamlined set of category fields—`slug` and `name`—optimized for typical storefront display and navigation scenarios. +The `CategoryViewV2` interface provides a minimal, streamlined set of category fields—`slug` and `name`—optimized for typical storefront display and navigation scenarios. ### Interface definition @@ -34,12 +34,7 @@ interface CategoryViewV2 { } ``` -### Fields - -Field | Data type | Description ---- | --- | --- -`slug` | String! | The unique URL-friendly identifier for the category, used in routing and navigation -`name` | String! | The display name of the category as shown to customers +For complete field details, see [`CategoryViewV2`](https://developer.adobe.com/commerce/webapi/graphql/merchandising/#definition-CategoryViewInterface) in the Merchandising Services GraphQL API reference. ### Key benefits @@ -48,14 +43,20 @@ Field | Data type | Description ## Category types -The `CategoryViewV2` interface is implemented by two specialized types: +The `CategoryViewV2` interface is implemented by three specialized types: + +1. **[CategoryNavigationView](#categorynavigationview-type)** - For menu rendering and navigation +2. **[CategoryProductView](#categoryproductview-type)** - For category data returned with product queries +3. **[CategoryTreeView](#categorytreeview-type)** - For hierarchical category management and rich category pages + +### CategoryNavigationView type -1. **CategoryNavigationView** - For menu rendering and navigation -2. **CategoryTreeView** - For hierarchical category management (primarily RetailCMS) +The `CategoryNavigationView` type implements `CategoryViewV2` and provides category data optimized for storefront navigation. It contains: -### CategoryNavigationView +- **name** and **slug** — Category identity +- **children** — Nested subcategories for building the full menu hierarchy in a single query -The `CategoryNavigationView` type implements `CategoryViewV2` and is specifically designed for building storefront navigation menus with built-in performance optimizations. +Use this type to render top menus, dropdowns, and mobile navigation. #### Type definition @@ -67,6 +68,10 @@ type CategoryNavigationView implements CategoryViewV2 { } ``` +For complete field details, see [`CategoryNavigationView`](https://developer.adobe.com/commerce/webapi/graphql/merchandising/#definition-CategoryNavigationView) in the Merchandising Services GraphQL API reference. + +See the [Navigation query examples](#navigation-query-examples) section below for example queries and responses using this type. + #### Performance safeguards - **Depth Limitation**: Menu depth is limited to 4 levels maximum @@ -74,9 +79,48 @@ type CategoryNavigationView implements CategoryViewV2 { - **Single Query**: Retrieves entire family in one database query - **Heavy Caching**: Query responses are heavily cached for optimal performance +### CategoryProductView type + +The `CategoryProductView` type implements `CategoryViewV2` and provides category data within product query responses. Each product's `categories` field returns a list of `CategoryProductView` objects containing: + +- **name** and **slug** — Category identity +- **level** — Position in the hierarchy +- **parents** — Full chain of ancestor categories + +Use this type to render breadcrumbs, filter by category, or display category context on product detail pages. + +#### Type definition + +```graphql +type CategoryProductView implements CategoryViewV2 { + name: String! + slug: String! + level: Int! + parents: [CategoryProductView!] +} +``` + +The `parents` field is self-referencing—each parent entry is itself a `CategoryProductView` with its own `name`, `slug`, `level`, and `parents`. This allows you to reconstruct the full breadcrumb path for any category a product belongs to. + +For complete field details, see [`CategoryProductView`](https://developer.adobe.com/commerce/webapi/graphql/merchandising/#definition-CategoryProductView) in the Merchandising Services GraphQL API reference. + +See the [Products query with categories examples](#products-query-with-categories-examples) section below for example queries and responses using this type. + +#### Performance safeguards + +The `categories` field is optional on product types. Omit it when category data is not needed to avoid unnecessary overhead. + ### CategoryTreeView type -The `CategoryTreeView` type implements `CategoryViewV2` and provides comprehensive hierarchical category data, primarily designed for RetailCMS applications. +The `CategoryTreeView` type implements `CategoryViewV2` and provides the richest category data. It contains: + +- **name** and **slug** — Category identity +- **level** and **parentSlug** / **childrenSlugs** — Hierarchy and relationships +- **description** — Category descriptive content +- **metaTags** — SEO metadata (title, description, keywords) +- **images** — Category images + +Use this type for rich category landing pages, SEO-driven content, and CMS administration. #### Type definition @@ -87,10 +131,30 @@ type CategoryTreeView implements CategoryViewV2 { level: Int parentSlug: String childrenSlugs: [String] + description: String + metaTags: CategoryMetaTags + images: [CategoryImage] +} + +type CategoryMetaTags { + title: String + description: String + keywords: [String] +} + +type CategoryImage { + url: String! + label: String + roles: [String] + customRoles: [String] } ``` -## Navigation query +For complete field details, including the [`CategoryMetaTags`](https://developer.adobe.com/commerce/webapi/graphql/merchandising/#definition-CategoryMetaTags) and [`CategoryImage`](https://developer.adobe.com/commerce/webapi/graphql/merchandising/#definition-CategoryImage) types, see [`CategoryTreeView`](https://developer.adobe.com/commerce/webapi/graphql/merchandising/#definition-CategoryTreeView) in the Merchandising Services GraphQL API reference. + +See the [CategoryTree query examples](#categorytree-query-examples) section below for example queries and responses using this type. + +## Navigation query examples Retrieve category navigation data optimized for storefront menu rendering with built-in performance safeguards. @@ -100,9 +164,13 @@ type Query { } ``` -### Example: Retrieve basic top menu navigation +The `family` parameter is required and specifies which category family to retrieve. The query returns the full hierarchy for that family in a single request, with a maximum depth of 4 levels. + +### Retrieve basic top menu navigation + + -**Query:** +**Request:** ```graphql query GetTopMenuNavigation { @@ -137,9 +205,18 @@ query GetTopMenuNavigation { } ``` -### Example: Retrieve multi-Level menu navigation +The response returns a single root node with no nested children: + +```plaintext +Men clothing +└── (no children) +``` + +### Retrieve multi-level menu navigation -**Query:** + + +**Request:** ```graphql query GetFullMenuNavigation { @@ -190,19 +267,165 @@ query GetFullMenuNavigation { } ``` -## CategoryTree query +The response returns a three-level nested hierarchy: + +```plaintext +Men clothing +└── Men tops + └── Jackets +``` + +## Products query with categories examples + +Retrieve category data for products, including breadcrumb ancestors, with optional filtering by category family. + +```graphql +type ProductView { + categories(family: String): [CategoryProductView] +} +``` + +The `categories` field is available on product types such as `ProductView`. Use the optional `family` parameter to return only categories from a specific category family. When omitted, categories from all families are returned. + +### Retrieve product categories with breadcrumb ancestors + + + +**Request:** + +```graphql +query { + products(skus: ["shorts-red-m"]) { + name + sku + categories(family: "clothing") { + name + slug + level + parents { + name + slug + level + } + } + } +} +``` + +**Response:** + +```json +{ + "data": { + "products": [ + { + "name": "Red Shorts (M)", + "sku": "shorts-red-m", + "categories": [ + { + "name": "Shorts", + "slug": "men/clothes/shorts", + "level": 2, + "parents": [ + { + "name": "Men", + "slug": "men", + "level": 0 + }, + { + "name": "Clothes", + "slug": "men/clothes", + "level": 1 + } + ] + } + ] + } + ] + } +} +``` + +The `parents` array provides the full ancestor chain, which you can use to render a breadcrumb path: + +```plaintext +Men (level 0) → Clothes (level 1) → Shorts (level 2) + └── product: Red Shorts (M) +``` + +### Filter product categories by family + +A product can belong to categories in multiple families. Use the `family` parameter to return only categories from a specific family. In this example, the product belongs to categories in both the "clothing" and "seasonal" families, but the query filters for "seasonal" only. + + + +**Request:** + +```graphql +query { + products(skus: ["shorts-red-m"]) { + name + sku + categories(family: "seasonal") { + name + slug + level + parents { + name + slug + level + } + } + } +} +``` + +**Response:** + +```json +{ + "data": { + "products": [ + { + "name": "Red Shorts (M)", + "sku": "shorts-red-m", + "categories": [ + { + "name": "Summer Essentials", + "slug": "summer/essentials", + "level": 1, + "parents": [ + { + "name": "Summer", + "slug": "summer", + "level": 0 + } + ] + } + ] + } + ] + } +} +``` + +Without the `family` filter, the response would include categories from all families the product belongs to—for example, both "Shorts" from the "clothing" family and "Summer Essentials" from the "seasonal" family. The `family` parameter narrows the result to a single family, which is useful when rendering context-specific navigation or breadcrumbs. + +## CategoryTree query examples Retrieve hierarchical category data in a tree structure with parent-child relationships and level information. ```graphql type Query { - categoryTree(family: String, slugs: [String], depth: Int): [CategoryTreeView] + categoryTree(family: String!, slugs: [String!], depth: Int): [CategoryTreeView] } ``` -### Example: Retrieve full category tree +### Retrieve full category tree + + -**Query:** +**Request:** ```graphql query GetFullCategoryTree { @@ -248,9 +471,21 @@ query GetFullCategoryTree { } ``` -### Example: Retrieve specific category subtree +The flat list represents this tree, reconstructed via `parentSlug` and `childrenSlugs`: + +```plaintext +Men's Clothing (level 0) +├── Men's Tops (level 1) +│ ├── Shirts (level 2) +│ └── Jackets +└── Men's Bottoms +``` + +### Retrieve specific category subtree -**Query:** + + +**Request:** ```graphql query GetSpecificCategorySubtree { @@ -288,21 +523,52 @@ query GetSpecificCategorySubtree { "parentSlug": "men/tops", "childrenSlugs": [] }, + { + "slug": "men/tops/jackets", + "name": "Jackets", + "level": 2, + "parentSlug": "men/tops", + "childrenSlugs": [] + }, { "slug": "men/bottoms", "name": "Men's Bottoms", "level": 1, "parentSlug": "men", "childrenSlugs": ["men/bottoms/pants", "men/bottoms/shorts"] + }, + { + "slug": "men/bottoms/pants", + "name": "Pants", + "level": 2, + "parentSlug": "men/bottoms", + "childrenSlugs": [] + }, + { + "slug": "men/bottoms/shorts", + "name": "Shorts", + "level": 2, + "parentSlug": "men/bottoms", + "childrenSlugs": [] } ] } } ``` -### Example: Retrieve root categories only +The response is a flat list. Each node's `parentSlug` and `childrenSlugs` fields let you reconstruct the tree: + +```plaintext +Men's Tops (level 1) Men's Bottoms (level 1) +├── Shirts (level 2) ├── Pants (level 2) +└── Jackets (level 2) └── Shorts (level 2) +``` + +### Retrieve root categories only -**Query:** + + +**Request:** ```graphql query GetRootCategories { @@ -341,22 +607,125 @@ query GetRootCategories { } ``` -## Use Case Scenarios +With `depth: 0`, only the top-level roots are returned: + +```plaintext +Men's Clothing (level 0) Women's Clothing (level 0) + childrenSlugs: childrenSlugs: + ├── men/tops ├── women/tops + └── men/bottoms └── women/bottoms + (referenced but not fetched) (referenced but not fetched) +``` + +### Retrieve category details with metadata and images + +Use the `description`, `metaTags`, and `images` fields to build rich category landing pages that include SEO metadata and visual content. This is especially useful when rendering a category page that needs a hero image, descriptive copy, and proper `` tags for search engines. + + + +**Request:** + +```graphql +query CategoryTree { + categoryTree(slugs: ["men/clothes/shorts"], family: "clothing") { + slug + name + level + parentSlug + childrenSlugs + description + metaTags { + title + description + keywords + } + images { + url + label + roles + customRoles + } + } +} +``` + +**Response:** + +```json +{ + "data": { + "categoryTree": [ + { + "slug": "men/clothes/shorts", + "name": "Shorts", + "level": 3, + "parentSlug": "men/clothes", + "childrenSlugs": [], + "description": "Browse our full range of men's shorts, from casual to athletic styles.", + "metaTags": { + "title": "Men's Shorts", + "description": "Shop men's shorts for every occasion", + "keywords": [ + "shorts", + "men" + ] + }, + "images": [ + { + "url": "https://example.com/images/shorts.jpg", + "label": "Men's shorts collection", + "roles": [ + "BASE", + "THUMBNAIL" + ], + "customRoles": [ + "special-role" + ] + } + ] + } + ] + } +} +``` + +## Use case scenarios -### Storefront Navigation Menu +### Storefront navigation menu -Use `navigation` query with `CategoryNavigationView` for: +Use the `navigation` query with `CategoryNavigationView` for: - Building responsive navigation components - Creating dropdown menus -- Implementing breadcrumb navigation - Mobile menu rendering **Benefits**: Optimized performance with caching, depth limits, and lightweight data. -### RetailCMS Category Management +### Category landing pages and SEO + +Use the `categoryTree` query with `CategoryTreeView` to build rich category pages: + +- Render category descriptions and hero images on landing pages +- Populate `` tags (`title`, `description`, `keywords`) for SEO +- Display category images with appropriate roles (for example, `BASE` for hero, `THUMBNAIL` for previews) +- Assign custom image roles for merchant-specific layouts + +**Benefits**: Combines hierarchy data with descriptive content, SEO metadata, and images in a single query. + +### Product detail pages and breadcrumbs -Use `categoryTree` query with `CategoryTreeView` for: +Use the `categories` field on product queries with `CategoryProductView` for: + +- Rendering breadcrumb navigation on product detail pages +- Displaying category badges or tags on product cards +- Filtering or grouping products by category in search results +- Building "Shop by Category" links from a product context + +**Benefits**: The `parents` field provides the full ancestor chain in a single query, eliminating the need for separate category lookups when building breadcrumbs. + +### Retail CMS category management + +Use the `categoryTree` query with `CategoryTreeView` for: - Category hierarchy management - Building category administration interfaces @@ -365,16 +734,9 @@ Use `categoryTree` query with `CategoryTreeView` for: **Benefits**: Complete hierarchy metadata, flexible querying, and detailed relationship information. -### Performance Considerations - -1. **Navigation Query**: - - Heavily cached responses. - - Single database query per family. - - Limited to four levels for performance. - - Excludes heavyweight attributes. +## Performance considerations -2. **CategoryTree Query**: - - Use `depth` parameter to limit tree traversal. - - Use `slugs` parameter for targeted queries. - - Ideal for administrative interfaces. - - Provides complete hierarchy metadata. +- **Choose the right query for the use case.** Use `navigation` for storefront menus—it is heavily cached, limited to four levels, and returns only lightweight fields. Use `categoryTree` when you need full hierarchy metadata, descriptions, or images. +- **Limit tree depth.** Pass the `depth` parameter to `categoryTree` to avoid fetching deeper levels than you need. +- **Target specific subtrees.** Pass the `slugs` parameter to `categoryTree` to fetch only the branches you need rather than the entire tree. +- **Omit optional fields.** The `categories` field on product queries and the `description`, `metaTags`, and `images` fields on `categoryTree` are optional. Exclude them when they are not needed to reduce payload size. diff --git a/src/pages/optimizer/merchandising-services/use-cases.md b/src/pages/optimizer/merchandising-services/use-cases.md index 79e8637c..cfde8d8b 100644 --- a/src/pages/optimizer/merchandising-services/use-cases.md +++ b/src/pages/optimizer/merchandising-services/use-cases.md @@ -243,6 +243,7 @@ query { "request-id": "a95140e9-47f5-4f51-9386-8b6bbf50fd48" } } +``` #### Return details about a complex product diff --git a/static/graphql-api/merchandising-api/index.html b/static/graphql-api/merchandising-api/index.html index deb11f23..379d0c17 100644 --- a/static/graphql-api/merchandising-api/index.html +++ b/static/graphql-api/merchandising-api/index.html @@ -55,8 +55,10 @@

Types

  • Bucket
  • CategoryBucket
  • CategoryBucketInterface
    • -
  • CategoryInterface
    • +
  • CategoryImage
    • +
  • CategoryMetaTags
  • CategoryNavigationView
    • +
  • CategoryProductView
  • CategoryTreeView
  • CategoryView
  • CategoryViewInterface
    • @@ -77,22 +79,23 @@

    Types

  • IsOperatorInput
  • IsOperatorType
  • JSON
    • -
  • MediaGalleryInterface
  • NumericOperatorInput
  • NumericOperatorType
  • OperatorInput
  • PageType
  • Price
  • PriceAdjustment
    • -
  • ProductInterface
    • -
  • ProductLinksInterface
  • ProductSearchItem
  • ProductSearchResponse
  • ProductSearchSortInput
    • +
  • ProductSearchWarning
  • ProductView
  • ProductViewAttribute
  • ProductViewCurrency
  • ProductViewImage
    • +
  • ProductViewInputOption
    • +
  • ProductViewInputOptionImageSize
    • +
  • ProductViewInputOptionRange
  • ProductViewLink
  • ProductViewMoney
  • ProductViewOption
    • @@ -118,8 +121,11 @@

    Types

  • RecommendationUnit
  • Recommendations
  • ScalarBucket
    • +
  • SearchClauseInput
    • +
  • SearchRangeInput
  • SearchResultPageInfo
  • SimpleProductView
    • +
  • SortEnum
  • SortableAttribute
  • StatsBucket
  • String
    • @@ -128,6 +134,7 @@

    Types

  • SwatchType
  • UnitConfigInput
  • ViewHistory
    • +
  • ViewHistoryInput
    • @@ -254,8 +261,7 @@

    Description
    -

    Retrieve hierarchical category data in a tree structure with parent-child relationships and level information.

    -

    Primary Use Case: RetailCMS applications requiring full category tree management.

    +

    Retrieves category tree nodes, optionally filtered by slugs and limited by depth.

    @@ -350,6 +356,13 @@

    Query
    ) { slug name + description + metaTags { + ...CategoryMetaTagsFragment + } + images { + ...CategoryImageFragment + } level parentSlug childrenSlugs @@ -364,9 +377,9 @@
    Variables
    {
-  "family": "abc123",
-  "slugs": ["abc123"],
-  "depth": 987
+  "family": "xyz789",
+  "slugs": ["xyz789"],
+  "depth": 123
 }
    @@ -381,10 +394,13 @@
    Response
    "categoryTree": [ { "slug": "abc123", - "name": "abc123", + "name": "xyz789", + "description": "abc123", + "metaTags": CategoryMetaTags, + "images": [CategoryImage], "level": 123, - "parentSlug": "xyz789", - "childrenSlugs": ["abc123"] + "parentSlug": "abc123", + "childrenSlugs": ["xyz789"] } ] } @@ -408,14 +424,7 @@

    Description
    -

    Retrieve category navigation data optimized for storefront menu rendering with built-in performance safeguards.

    -

    Performance Features:

    -
      -
    • Limited to 4 levels deep for optimal rendering
      • -
    • Single database query per family
      • -
    • Heavily cached responses
      • -
    • Excludes heavyweight category attributes
      • -
    +

    Retrieves the navigation tree for a given product family.

    @@ -479,7 +488,7 @@

    Query
    Variables
    - 
    {"family": "abc123"}
+                  
    {"family": "xyz789"}
 
    
                   
                 
@@ -492,7 +501,7 @@ 
    Response
    
   "data": {
     "navigation": [
       {
-        "slug": "abc123",
+        "slug": "xyz789",
         "name": "xyz789",
         "children": [CategoryNavigationView]
       }
@@ -551,6 +560,12 @@ 
    Arguments
    
                       
                        Specifies which page of results to return. The default value is 1. Default = 1 
                     
+                    
+                      
+                        filter - [SearchClauseInput!]
+                      
+                       Identifies product attributes and conditions to filter on 
+                    
                     
                       
                         page_size - Int
@@ -582,6 +597,7 @@ 
    Query
    
                   
    query productSearch(
   $context: QueryContextInput,
   $current_page: Int,
+  $filter: [SearchClauseInput!],
   $page_size: Int,
   $phrase: String!,
   $sort: [ProductSearchSortInput!]
@@ -589,6 +605,7 @@ 
    Query
    
   productSearch(
     context: $context,
     current_page: $current_page,
+    filter: $filter,
     page_size: $page_size,
     phrase: $phrase,
     sort: $sort
@@ -605,6 +622,9 @@ 
    Query
    
     related_terms
     suggestions
     total_count
+    warnings {
+      ...ProductSearchWarningFragment
+    }
   }    
 }    
 
    
@@ -618,6 +638,7 @@ 
    Variables
    
                   
    {
   "context": QueryContextInput,
   "current_page": 1,
+  "filter": [SearchClauseInput],
   "page_size": 20,
   "phrase": "abc123",
   "sort": [ProductSearchSortInput]
@@ -636,9 +657,10 @@ 
    Response
    
       "facets": [Aggregation],
       "items": [ProductSearchItem],
       "page_info": SearchResultPageInfo,
-      "related_terms": ["xyz789"],
+      "related_terms": ["abc123"],
       "suggestions": ["abc123"],
-      "total_count": 123
+      "total_count": 987,
+      "warnings": [ProductSearchWarning]
     }
   }
 }
@@ -721,6 +743,9 @@ 
    Query
    
     metaTitle
     name
     shortDescription
+    inputOptions {
+      ...ProductViewInputOptionFragment
+    }
     sku
     externalId
     url
@@ -728,6 +753,9 @@ 
    Query
    
     links {
       ...ProductViewLinkFragment
     }
+    categories {
+      ...CategoryProductViewFragment
+    }
     queryType
     visibility
   }
@@ -754,7 +782,7 @@ 
    Response
    
     "products": [
       {
         "addToCartAllowed": true,
-        "inStock": true,
+        "inStock": false,
         "lowStock": false,
         "attributes": [ProductViewAttribute],
         "description": "xyz789",
@@ -765,15 +793,17 @@ 
    Response
    
         "metaDescription": "abc123",
         "metaKeyword": "xyz789",
         "metaTitle": "abc123",
-        "name": "abc123",
+        "name": "xyz789",
         "shortDescription": "xyz789",
-        "sku": "abc123",
-        "externalId": "xyz789",
-        "url": "xyz789",
-        "urlKey": "abc123",
+        "inputOptions": [ProductViewInputOption],
+        "sku": "xyz789",
+        "externalId": "abc123",
+        "url": "abc123",
+        "urlKey": "xyz789",
         "links": [ProductViewLink],
-        "queryType": "xyz789",
-        "visibility": "abc123"
+        "categories": [CategoryProductView],
+        "queryType": "abc123",
+        "visibility": "xyz789"
       }
     ]
   }
@@ -903,8 +933,8 @@ 
    Variables
    
                 
                   
                   
    {
-  "cartSkus": ["abc123"],
-  "category": "abc123",
+  "cartSkus": ["xyz789"],
+  "category": "xyz789",
   "currentSku": "abc123",
   "pageType": "CMS",
   "userPurchaseHistory": [PurchaseHistory],
@@ -1032,7 +1062,7 @@ 
    Variables
    
   "currentSku": "abc123",
   "userPurchaseHistory": [PurchaseHistory],
   "userViewHistory": [ViewHistory],
-  "cartSkus": ["xyz789"]
+  "cartSkus": ["abc123"]
 }
 
    
                   
@@ -1046,7 +1076,7 @@ 
    Response
    
   "data": {
     "recommendationsByUnitIds": {
       "results": [RecommendationUnit],
-      "totalResults": 987
+      "totalResults": 123
     }
   }
 }
@@ -1134,6 +1164,9 @@ 
    Query
    
     metaTitle
     name
     shortDescription
+    inputOptions {
+      ...ProductViewInputOptionFragment
+    }
     sku
     externalId
     url
@@ -1141,6 +1174,9 @@ 
    Query
    
     links {
       ...ProductViewLinkFragment
     }
+    categories {
+      ...CategoryProductViewFragment
+    }
     queryType
     visibility
   }
@@ -1154,8 +1190,8 @@ 
    Variables
    
                 
                   
                   
    {
-  "optionIds": ["abc123"],
-  "sku": "abc123"
+  "optionIds": ["xyz789"],
+  "sku": "xyz789"
 }
 
    
                   
@@ -1177,17 +1213,19 @@ 
    Response
    
       "images": [ProductViewImage],
       "videos": [ProductViewVideo],
       "lastModifiedAt": "2007-12-03T10:15:30Z",
-      "metaDescription": "abc123",
-      "metaKeyword": "abc123",
+      "metaDescription": "xyz789",
+      "metaKeyword": "xyz789",
       "metaTitle": "abc123",
-      "name": "xyz789",
+      "name": "abc123",
       "shortDescription": "abc123",
+      "inputOptions": [ProductViewInputOption],
       "sku": "xyz789",
       "externalId": "xyz789",
       "url": "xyz789",
-      "urlKey": "abc123",
+      "urlKey": "xyz789",
       "links": [ProductViewLink],
-      "queryType": "xyz789",
+      "categories": [CategoryProductView],
+      "queryType": "abc123",
       "visibility": "xyz789"
     }
   }
@@ -1289,8 +1327,8 @@ 
    Variables
    
                 
                   
                   
    {
-  "sku": "abc123",
-  "optionIds": ["abc123"],
+  "sku": "xyz789",
+  "optionIds": ["xyz789"],
   "pageSize": 123,
   "cursor": "xyz789"
 }
@@ -1306,7 +1344,7 @@ 
    Response
    
   "data": {
     "variants": {
       "variants": [ProductViewVariant],
-      "cursor": "xyz789"
+      "cursor": "abc123"
     }
   }
 }
@@ -1367,7 +1405,7 @@ 
    Example
    
                 
                   
                   
    {
-  "attribute": "abc123",
+  "attribute": "xyz789",
   "buckets": [Bucket],
   "title": "xyz789",
   "type": "INTELLIGENT"
@@ -1623,6 +1661,15 @@ 
    Description
    
               
             
             
    
+              
    
+                
    Example
    
+                
+                  
+                  
    true
+
    
+                  
+                
+              
    
             
    
             back to top
           
@@ -1699,7 +1746,7 @@ 
    Possible Types
    
                 
    Example
    
                 
                   
-                  
    {"title": "abc123"}
+                  
    {"title": "xyz789"}
 
    
                   
                 
@@ -1765,7 +1812,7 @@ 
    Example
    
                   
    {
   "count": 987,
   "id": "4",
-  "path": "xyz789",
+  "path": "abc123",
   "title": "xyz789"
 }
 
    
@@ -1825,7 +1872,7 @@ 
    Possible Types
    
                 
    Example
    
                 
                   
-                  
    {"id": 4}
+                  
    {"id": "4"}
 
    
                   
                 
@@ -1834,18 +1881,18 @@ 
    Example
    
             back to top
           
         
-        
    
+        
    
           
    
             Types
           
    
-          
    CategoryInterface
    
+          
    CategoryImage
    
           
    
             
    
               
    
                 
    Description
    
-                
    Contains the full set of attributes that can be returned in a category search.
    
+                
    Represents an image associated with a category.
    
               
    
-              
    
+              
    
                 
    Fields
    
                 
@@ -1856,136 +1903,141 @@ 
    Fields
    
-                      
-                      
-                    
-                    
-                      
-                      
-                    
-                    
-                      
-                      
-                    
-                    
-                      
-                      
-                    
-                    
-                      
-                      
-                    
-                    
-                      
-                      
-                    
-                    
-                      
-                      
+                      
-                      
-                      
+                      
-                      
-                      
+                      
-                      
-                      
+                      
+                  
+                
    
                   
                   
                   
                     
    available_sort_by - [String]
-                      
-                      
    canonical_url - String
-                       The relative canonical URL. This value is returned only if the system setting 'Use Canonical Link Meta Tag For Categories' is enabled. 
    children_count - String
-                      
-                      
    custom_layout_update_file - String
-                      
-                      
    default_sort_by - String
-                       The attribute to use for sorting. 
    description - String
-                       An optional description of the category. 
    display_mode - String
-                      
+                      url - String!
                        The URL where the image is hosted. 
                     
    
                     
    filter_price_range - Float
-                      
+                      label - String
                        A descriptive label or alt text for the image. 
                     
    
                     
    image - String
-                      
+                      roles - [String]
                        Standard predefined roles for the image. 
                     
    
                     
    include_in_menu - Int
-                      
+                      customRoles - [String]
                        Custom roles specific to the implementation. 
                     
    
+              
    
+            
    
+            
    
+              
    
+                
    Example
    
+                
+                  
+                  
    {
+  "url": "xyz789",
+  "label": "abc123",
+  "roles": ["xyz789"],
+  "customRoles": ["xyz789"]
+}
+
    
+                  
+                
+              
    
+            
    
+            back to top
+          
    
+        
    
+        
    
+          
    
+            Types
+          
    
+          
    CategoryMetaTags
    
+          
    
+            
    
+              
    
+                
    Description
    
+                
    SEO metadata tags for the category.
    
+              
    
+              
    
+                
    Fields
    
+                
+                  
-                      
-                      
+                      
+                      
+                  
+                  
-                      
-                      
+                      
-                      
-                      
+                      
-                      
-                      
+                      
+                  
+                
    
                     
    is_anchor - Int
-                      
-                      Field NameDescription
                     
    
                     
    landing_page - Int
-                      
+                      title - String
                        The page title for SEO purposes. 
                     
    
                     
    level - Int
+                      description - String
                        The depth of the category within the tree.  The meta description for SEO purposes. 
                     
    
                     
    meta_description - String
-                      
+                      keywords - [String]
                        Keywords associated with the category for SEO. 
                     
    
+              
    
+            
    
+            
    
+              
    
+                
    Example
    
+                
+                  
+                  
    {
+  "title": "abc123",
+  "description": "xyz789",
+  "keywords": ["xyz789"]
+}
+
    
+                  
+                
+              
    
+            
    
+            back to top
+          
    
+        
    
+        
    
+          
    
+            Types
+          
    
+          
    CategoryNavigationView
    
+          
    
+            
    
+              
    
+                
    Description
    
+                
    Represents a category optimized for navigation menus, with nested children for building navigation trees.
    
+              
    
+              
    
+                
    Fields
    
+                
+                  
-                      
-                      
+                      
+                      
+                  
+                  
-                      
-                      
+                      
-                      
-                      
-                      
-                    
-                    
-                      
-                      
-                    
-                    
-                      
-                      
-                    
-                    
-                      
-                      
-                    
-                    
-                      
-                      
-                    
-                    
-                      
-                      
-                    
-                    
-                      
-                      
+                      
    
                     
    meta_keywords - String
-                      
-                      Field NameDescription
                     
    
                     
    meta_title - String
-                      
+                      slug - String!
                        The unique URL-friendly identifier for the category. 
                     
    
                     
    name - String
+                      name - String!
                       
                        The display name of the category. 
                     
    
                     
    path - String
-                       The full category path. 
    path_in_store - String
-                       The category path within the store. 
    position - Int
-                       The position of the category relative to other categories at the same level in tree. 
    product_count - Int
-                       The number of products in the category that are marked as visible. By default, in complex products, parent products are visible, but their child products are not. 
    uid - ID!
-                       The unique ID for a CategoryInterface object. 
    url_key - String
-                       The URL key assigned to the category. 
    url_path - String
+                      children - [CategoryNavigationView]
                        The URL path assigned to the category.  The direct child categories for building nested navigation menus. 
                     
    
                       
                 
    
@@ -1997,30 +2049,9 @@ 
    Example
    
                 
                   
                   
    {
-  "available_sort_by": ["xyz789"],
-  "canonical_url": "xyz789",
-  "children_count": "abc123",
-  "custom_layout_update_file": "xyz789",
-  "default_sort_by": "abc123",
-  "description": "abc123",
-  "display_mode": "xyz789",
-  "filter_price_range": 123.45,
-  "image": "xyz789",
-  "include_in_menu": 123,
-  "is_anchor": 987,
-  "landing_page": 123,
-  "level": 123,
-  "meta_description": "xyz789",
-  "meta_keywords": "abc123",
-  "meta_title": "abc123",
+  "slug": "xyz789",
   "name": "xyz789",
-  "path": "xyz789",
-  "path_in_store": "xyz789",
-  "position": 987,
-  "product_count": 123,
-  "uid": "4",
-  "url_key": "abc123",
-  "url_path": "abc123"
+  "children": [CategoryNavigationView]
 }
 
    
                   
@@ -2030,30 +2061,16 @@ 
    Example
    
             back to top
           
    
         
    
-        
    
+        
    
           
    
             Types
           
    
-          
    CategoryNavigationView
    
+          
    CategoryProductView
    
           
    
             
    
               
    
                 
    Description
    
-                
    Represents a category optimized for storefront menu rendering with recursive child category structure.
    
-                
    Performance Safeguards:
    
-                
      
-                  
    • Limited to 4 levels deep
      • 
-                  
    • Excludes heavyweight category attributes
      • 
-                  
    • Supports heavy caching
      • 
-                  
    • Single query optimization
      • 
-                
    
-                
    Ideal For:
    
-                
      
-                  
    • Responsive navigation components
      • 
-                  
    • Dropdown menus
      • 
-                  
    • Mobile navigation
      • 
-                  
    • Breadcrumb systems
      • 
-                
    
+                
    Represents category information associated with a product, including hierarchical parent relationships.
    
               
    
               
    
                 
    Fields
    
@@ -2066,28 +2083,24 @@ 
    Fields
    
                   
                   
                     
-                      slug - String!
+                      name - String!
                       
-                       The unique URL-friendly identifier for the category, used in routing and navigation. 
+                       The display name of the category. 
                     
                     
-                      name - String!
+                      slug - String!
                       
-                       The display name of the category as shown to customers in the storefront navigation. 
+                       The unique URL-friendly identifier for the category. 
                     
                     
-                      children - [CategoryNavigationView]
+                      level - Int!
                       
-                      
-                        
    Array of direct child categories in a recursive structure.
    
-                        
    Structure:
    
-                        
      
-                          
    • Each child contains their own children (recursive)
      • 
-                          
    • Limited to 4 levels deep for performance
      • 
-                          
    • Empty array if no children or max depth reached
      • 
-                        
    
-                        
    Optimized For: Multi-level navigation menu rendering with built-in performance safeguards.
    
+                       The depth level of the category in the hierarchy (0 for root categories). 
+                    
+                    
+                      parents - [CategoryProductView!]
                       
+                       The ancestor categories in the hierarchy, ordered from root to immediate parent. 
                     
                   
                 
@@ -2099,9 +2112,10 @@ 
    Example
    
                 
                   
                   
    {
-  "slug": "xyz789",
   "name": "xyz789",
-  "children": [CategoryNavigationView]
+  "slug": "abc123",
+  "level": 987,
+  "parents": [CategoryProductView]
 }
 
    
                   
@@ -2120,20 +2134,7 @@ 
    CategoryTreeView
    
             
    
               
    
                 
    Description
    
-                
    Represents a category in a hierarchical tree structure with comprehensive parent-child relationship metadata.
    
-                
    Key Features:
    
-                
      
-                  
    • Implements CategoryViewV2 interface
      • 
-                  
    • Designed for RetailCMS applications
      • 
-                  
    • Full category tree management capabilities
      • 
-                
    
-                
    Provides:
    
-                
      
-                  
    • Level depth information
      • 
-                  
    • Parent slug references
      • 
-                  
    • Children slug collections
      • 
-                  
    • Complete hierarchy metadata
      • 
-                
    
+                
    Represents a category within a hierarchical tree structure, including parent and children relationships.
    
               
    
               
    
                 
    Fields
    
@@ -2148,63 +2149,42 @@ 
    Fields
    
                     
                       slug - String!
                       
-                       The unique URL-friendly identifier for the category, used in routing and navigation. 
+                       The unique URL-friendly identifier for the category. 
                     
                     
                       name - String!
                       
-                       The display name of the category as shown to customers in the storefront. 
+                       The display name of the category. 
                     
                     
-                      level - Int
+                      description - String
                       
-                      
-                        
    The hierarchical depth level of the category in the tree structure.
    
-                        
    Level Structure:
    
-                        
      
-                          
    • Root categories: level 0
      • 
-                          
    • First-level children: level 1
      • 
-                          
    • Second-level children: level 2
      • 
-                          
    • And so on...
      • 
-                        
    
-                        
    Used For: Tree traversal and hierarchy management in RetailCMS applications.
    
+                       A detailed description of the category. 
+                    
+                    
+                      metaTags - CategoryMetaTags
                       
+                       SEO metadata tags for the category. 
                     
                     
-                      parentSlug - String
+                      images - [CategoryImage]
                       
-                      
-                        
    The slug of the immediate parent category in the hierarchy.
    
-                        
    Values:
    
-                        
      
-                          
    • Parent category slug for child categories
      • 
-                          
    • null for root-level categories
      • 
-                        
    
-                        
    Common Uses:
    
-                        
      
-                          
    • Building breadcrumb navigation
      • 
-                          
    • Understanding category relationships
      • 
-                          
    • Tree management system operations
      • 
-                        
    
+                       Visual images associated with the category. 
+                    
+                    
+                      level - Int
                       
+                       The depth level of the category in the tree hierarchy (0 for root categories). 
                     
                     
-                      childrenSlugs - [String]
+                      parentSlug - String
                       
-                      
-                        
    Array of slugs for all direct child categories (immediate descendants only).
    
-                        
    Contains:
    
-                        
      
-                          
    • Slugs of immediate children only (not grandchildren)
      • 
-                          
    • Empty array if no children exist
      • 
-                        
    
-                        
    Benefits:
    
-                        
      
-                          
    • Determine subcategory existence without fetching full objects
      • 
-                          
    • Efficient category tree management
      • 
-                          
    • Quick hierarchy assessment
      • 
-                        
    
+                       The slug of the parent category, if any. 
+                    
+                    
+                      childrenSlugs - [String]
                       
+                       The slugs of all direct child categories. 
                     
                   
                 
@@ -2217,9 +2197,12 @@ 
    Example
    
                   
                   
    {
   "slug": "abc123",
-  "name": "xyz789",
+  "name": "abc123",
+  "description": "xyz789",
+  "metaTags": CategoryMetaTags,
+  "images": [CategoryImage],
   "level": 987,
-  "parentSlug": "abc123",
+  "parentSlug": "xyz789",
   "childrenSlugs": ["xyz789"]
 }
 
    
@@ -2344,18 +2327,18 @@ 
    Example
    
                   
                   
    {
   "availableSortBy": ["abc123"],
-  "children": ["abc123"],
+  "children": ["xyz789"],
   "defaultSortBy": "abc123",
-  "id": "4",
+  "id": 4,
   "level": 123,
   "name": "abc123",
-  "parentId": "abc123",
+  "parentId": "xyz789",
   "path": "xyz789",
-  "roles": ["abc123"],
-  "urlKey": "abc123",
+  "roles": ["xyz789"],
+  "urlKey": "xyz789",
   "urlPath": "xyz789",
   "count": 123,
-  "title": "xyz789"
+  "title": "abc123"
 }
 
    
                   
@@ -2465,7 +2448,7 @@ 
    Example
    
                   
                   
    {
   "availableSortBy": ["abc123"],
-  "defaultSortBy": "xyz789",
+  "defaultSortBy": "abc123",
   "id": 4,
   "level": 123,
   "name": "abc123",
@@ -2491,19 +2474,7 @@ 
    CategoryViewV2
    
             
    
               
    
                 
    Description
    
-                
    Lightweight base interface for category view models designed for storefront APIs without backward compatibility constraints.
    
-                
    Design Principles:
    
-                
      
-                  
    • Minimal essential properties (slug and name only)
      • 
-                  
    • Optimal performance for storefront use cases
      • 
-                  
    • No coupling with search facets
      • 
-                
    
-                
    Replaces: The heavyweight CategoryView interface
    
-                
    Implemented By:
    
-                
      
-                  
    • CategoryNavigationView (menu rendering)
      • 
-                  
    • CategoryTreeView (hierarchy management)
      • 
-                
    
+                
    Base interface defining essential category fields shared across all category views.
    
               
    
               
    
                 
    Fields
    
@@ -2518,12 +2489,12 @@ 
    Fields
    
                     
                       slug - String!
                       
-                       The unique URL-friendly identifier for the category, used in routing and navigation. 
+                       The unique URL-friendly identifier for the category. 
                     
                     
                       name - String!
                       
-                       The display name of the category as shown to customers in the storefront. 
+                       The display name of the category. 
                     
                   
                 
@@ -2542,6 +2513,11 @@ 
    Possible Types
    
                         
    CategoryNavigationView
    
                       
                     
+                    
+                      
+                        
    CategoryProductView
    
+                      
+                    
                     
                       
                         
    CategoryTreeView
    
@@ -2557,8 +2533,8 @@ 
    Example
    
                 
                   
                   
    {
-  "slug": "xyz789",
-  "name": "abc123"
+  "slug": "abc123",
+  "name": "xyz789"
 }
 
    
                   
@@ -2610,7 +2586,7 @@ 
    Fields
    
                     
                       attributes - [ProductViewAttribute]
                       
-                       A list of merchant-defined attributes designated for the storefront. 
+                       A list of merchant-defined attributes designated for the storefront. They can be filtered by roles and names. 
                     
                     
                       
@@ -2621,6 +2597,10 @@ 
     Arguments 
    
                               
    roles - [String]
                               
    
                             
    
+                            
    
+                              
    names - [String]
+                              
    
+                            
    
                           
    
                         
    
                       
@@ -2683,6 +2663,12 @@ 
    roles
                        Product name. 
                     
+                    
+                      inputOptions - [ProductViewInputOption]
+                      
+                       A list of input options. This field is deprecated and will be removed.
+                      
+                    
                     
                       options - [ProductViewOption]
                       
@@ -2738,6 +2724,24 @@ 
    linkTypes
                       
                     
+                    
+                      categories - [CategoryProductView!]
+                      
+                       A list of categories in which the product is present. 
+                    
+                    
+                      
+                        
    
+                          
     Arguments 
    
+                          
    
+                            
    
+                              
    family - String
+                              
    
+                            
    
+                          
    
+                        
    
+                      
+                    
                     
                       queryType - String
                       
@@ -2758,27 +2762,29 @@ 
    Example
    
                 
                   
                   
    {
-  "addToCartAllowed": true,
+  "addToCartAllowed": false,
   "inStock": false,
-  "lowStock": true,
+  "lowStock": false,
   "attributes": [ProductViewAttribute],
-  "description": "xyz789",
-  "id": "4",
+  "description": "abc123",
+  "id": 4,
   "images": [ProductViewImage],
   "videos": [ProductViewVideo],
   "lastModifiedAt": "2007-12-03T10:15:30Z",
-  "metaDescription": "xyz789",
+  "metaDescription": "abc123",
   "metaKeyword": "abc123",
   "metaTitle": "abc123",
   "name": "xyz789",
+  "inputOptions": [ProductViewInputOption],
   "options": [ProductViewOption],
   "priceRange": ProductViewPriceRange,
-  "shortDescription": "xyz789",
+  "shortDescription": "abc123",
   "sku": "xyz789",
   "externalId": "xyz789",
   "url": "xyz789",
   "urlKey": "xyz789",
   "links": [ProductViewLink],
+  "categories": [CategoryProductView],
   "queryType": "xyz789",
   "visibility": "xyz789"
 }
@@ -2892,7 +2898,7 @@ 
    Example
    
                   
                   
    {
   "type": "UNKNOWN_CUSTOMOPERATOR_TYPE",
-  "value": ["xyz789"]
+  "value": ["abc123"]
 }
 
    
                   
@@ -3237,7 +3243,7 @@ 
    Example
    
                   
    {
   "attribute": "abc123",
   "frontendInput": "abc123",
-  "label": "xyz789",
+  "label": "abc123",
   "numeric": false
 }
 
    
@@ -3265,7 +3271,7 @@ 
    Description
    
                 
    Example
    
                 
                   
-                  
    123.45
+                  
    987.65
 
    
                   
                 
@@ -3320,9 +3326,9 @@ 
    Example
    
                 
                   
                   
    {
-  "attribute": "abc123",
+  "attribute": "xyz789",
   "matched_words": ["xyz789"],
-  "value": "xyz789"
+  "value": "abc123"
 }
 
    
                   
@@ -3375,7 +3381,7 @@ 
    Description
    
                 
    Example
    
                 
                   
-                  
    123
+                  
    987
 
    
                   
                 
@@ -3424,7 +3430,7 @@ 
    Fields
    
                 
    Example
    
                 
                   
-                  
    {"type": "UNKNOWN_ISOPERATOR_TYPE", "value": true}
+                  
    {"type": "UNKNOWN_ISOPERATOR_TYPE", "value": false}
 
    
                   
                 
@@ -3500,70 +3506,6 @@ 
    Example
    
                 
                   
                   
    {}
-
    
-                  
-                
-              
    
-            
    
-            back to top
-          
    
-        
    
-        
    
-          
    
-            Types
-          
    
-          
    MediaGalleryInterface
    
-          
    
-            
    
-              
    
-                
    Description
    
-                
    Contains basic information about a product image or video.
    
-              
    
-              
    
-                
    Fields
    
-                
-                  
-                    
-                      
-                      
-                    
-                  
-                  
-                    
-                      
-                      
-                    
-                    
-                      
-                      
-                    
-                    
-                      
-                      
-                    
-                    
-                      
-                      
-                    
-                  
-                
    Field NameDescription
    disabled - Boolean
-                       Indicates whether the image is hidden from view. 
    label - String
-                       The label of the product image or video. 
    position - Int
-                       The media item's position after it has been sorted. 
    url - String
-                       The URL of the product image or video. 
    
-              
    
-            
    
-            
    
-              
    
-                
    Example
    
-                
-                  
-                  
    {
-  "disabled": false,
-  "label": "abc123",
-  "position": 123,
-  "url": "abc123"
-}
 
    
                   
                 
@@ -3920,7 +3862,7 @@ 
    Fields
    
                 
    Example
    
                 
                   
-                  
    {"amount": 123.45, "code": "abc123"}
+                  
    {"amount": 987.65, "code": "abc123"}
 
    
                   
                 
@@ -3929,18 +3871,18 @@ 
    Example
    
             back to top
           
    
         
    
-        
    
+        
    
           
    
             Types
           
    
-          
    ProductInterface
    
+          
    ProductSearchItem
    
           
    
             
    
               
    
                 
    Description
    
-                
    Contains fields that are common to all types of products.
    
+                
    A single product returned by the query
    
               
    
-              
    
+              
    
                 
    Fields
    
                 
@@ -3951,149 +3893,19 @@ 
    Fields
    
-                      
-                      
-                    
-                    
-                      
-                      
-                    
-                    
-                      
-                      
-                    
-                    
-                      
-                      
-                    
-                    
-                      
-                      
-                    
-                    
-                      
-                      
-                    
-                    
-                      
-                      
-                    
-                    
-                      
-                      
-                    
-                    
-                      
-                      
-                    
-                    
-                      
-                      
-                    
-                    
-                      
-                      
-                    
-                    
-                      
-                      
-                    
-                    
-                      
-                      
-                    
-                    
-                      
-                      
-                    
-                    
-                      
-                      
-                    
-                    
-                      
-                      
-                    
-                    
-                      
-                      
-                    
-                    
-                      
-                      
-                    
-                    
-                      
-                      
-                    
-                    
-                      
-                      
-                    
-                    
-                      
-                      
-                    
-                    
-                      
-                      
-                    
-                    
-                      
-                      
-                    
-                    
-                      
-                      
-                    
-                    
-                      
-                      
-                    
-                    
-                      
-                      
-                    
-                    
-                      
-                      
+                      
-                      
-                      
+                      
-                      
-                      
+                      
    
                   
                   
                   
                     
    canonical_url - String
-                       The relative canonical URL. This value is returned only if the system setting 'Use Canonical Link Meta Tag For Products' is enabled. 
    categories - [CategoryInterface]
-                       The categories assigned to a product. 
    country_of_manufacture - String
-                       The product's country of origin. 
    crosssell_products - [ProductInterface]
-                       Crosssell Products 
    gift_message_available - Boolean!
-                       Returns a value indicating gift message availability for the product. 
    gift_wrapping_available - Boolean!
-                       Returns a value indicating gift wrapping availability for the product. 
    is_returnable - String
-                       Indicates whether the product can be returned. 
    manufacturer - Int
-                       A number representing the product's manufacturer. 
    max_sale_qty - Float
-                       Maximum Qty Allowed in Shopping Cart 
    media_gallery - [MediaGalleryInterface]
-                       An array of media gallery objects. 
    meta_description - String
-                       A brief overview of the product for search results listings, maximum 255 characters. 
    meta_keyword - String
-                       A comma-separated list of keywords that are visible only to search engines. 
    meta_title - String
-                       A string that is displayed in the title bar and tab of the browser and in search results lists. 
    min_sale_qty - Float
-                       Minimum Qty Allowed in Shopping Cart 
    name - String
-                       The product name. Customers use this name to identify the product. 
    new_from_date - String
-                       The beginning date for new product listings, and determines if the product is featured as a new product. 
    new_to_date - String
-                       The end date for new product listings. 
    only_x_left_in_stock - Float
-                       Product stock only x left count 
    options_container - String
-                       If the product has multiple options, determines where they appear on the product page. 
    product_links - [ProductLinksInterface]
-                       An array of ProductLinks objects. 
    quantity - Float
-                       Quantity of available stock 
    related_products - [ProductInterface]
-                       An array of products to be displayed in a Related Products block. 
    sku - String
-                       A number or code assigned to a product to identify the product, options, price, and manufacturer. 
    special_price - Float
-                       The discounted price of the product. 
    special_to_date - String
-                       The end date for a product with a special price. 
    swatch_image - String
-                       The file name of a swatch image. 
    uid - ID!
+                      applied_query_rule - AppliedQueryRule
                        The unique ID for a ProductInterface object.  The query rule type that was applied to this product, if any (in preview mode only, returns null otherwise) 
                     
    
                     
    upsell_products - [ProductInterface]
+                      highlights - [Highlight]
                        Upsell Products  An object that provides highlighted text for matched words 
                     
    
                     
    url_key - String
+                      productView - ProductView
                        The part of the URL that identifies the product  Contains a product view 
                     
    
                       
                 
    
@@ -4105,35 +3917,9 @@ 
    Example
    
                 
                   
                   
    {
-  "canonical_url": "xyz789",
-  "categories": [CategoryInterface],
-  "country_of_manufacture": "abc123",
-  "crosssell_products": [ProductInterface],
-  "gift_message_available": true,
-  "gift_wrapping_available": true,
-  "is_returnable": "xyz789",
-  "manufacturer": 987,
-  "max_sale_qty": 123.45,
-  "media_gallery": [MediaGalleryInterface],
-  "meta_description": "abc123",
-  "meta_keyword": "abc123",
-  "meta_title": "xyz789",
-  "min_sale_qty": 123.45,
-  "name": "xyz789",
-  "new_from_date": "xyz789",
-  "new_to_date": "abc123",
-  "only_x_left_in_stock": 987.65,
-  "options_container": "xyz789",
-  "product_links": [ProductLinksInterface],
-  "quantity": 123.45,
-  "related_products": [ProductInterface],
-  "sku": "abc123",
-  "special_price": 987.65,
-  "special_to_date": "abc123",
-  "swatch_image": "abc123",
-  "uid": "4",
-  "upsell_products": [ProductInterface],
-  "url_key": "xyz789"
+  "applied_query_rule": AppliedQueryRule,
+  "highlights": [Highlight],
+  "productView": ProductView
 }
 
    
                   
@@ -4143,18 +3929,18 @@ 
    Example
    
             back to top
           
    
         
    
-        
    
+        
    
           
    
             Types
           
    
-          
    ProductLinksInterface
    
+          
    ProductSearchResponse
    
           
    
             
    
               
    
                 
    Description
    
-                
    Contains information about linked products, including the link type and product type of each item.
    
+                
    Contains the output of a productSearch query
    
               
    
-              
    
+              
    
                 
    Fields
    
                 
@@ -4165,29 +3951,39 @@ 
    Fields
    
-                      
+                      
+                    
+                    
+                      
+                      
+                    
+                    
+                      
-                      
+                      
-                      
-                      
+                      
-                      
-                      
+                      
-                      
-                      
+                      
-                      
-                      
+                      
    
                   
                   
                   
                     
    link_type - String
+                      facets - [Aggregation]
+                       Details about the static and dynamic facets relevant to the search 
    items - [ProductSearchItem]
+                       An array of products returned by the query 
    page_info - SearchResultPageInfo
                        One of related, associated, upsell, or crosssell.  Information for rendering pages of search results 
                     
    
                     
    linked_product_sku - String
+                      related_terms - [String]
                        The SKU of the linked product.  An array of strings that might include merchant-defined synonyms 
                     
    
                     
    linked_product_type - String
+                      suggestions - [String]
                        The type of linked product (simple, virtual, bundle, downloadable, grouped, configurable).  An array of strings that include the names of products and categories that exist in the catalog that are similar to the search query 
                     
    
                     
    position - Int
+                      total_count - Int
                        The position within the list of product links.  The total number of products returned that matched the query 
                     
    
                     
    sku - String
+                      warnings - [ProductSearchWarning]
                        The identifier of the linked product.  An array of warning messages for validation issues (e.g., sort parameter ignored due to missing categoryPath) 
                     
    
                       
                 
    
@@ -4199,11 +3995,13 @@ 
    Example
    
                 
                   
                   
    {
-  "link_type": "xyz789",
-  "linked_product_sku": "abc123",
-  "linked_product_type": "xyz789",
-  "position": 987,
-  "sku": "abc123"
+  "facets": [Aggregation],
+  "items": [ProductSearchItem],
+  "page_info": SearchResultPageInfo,
+  "related_terms": ["abc123"],
+  "suggestions": ["xyz789"],
+  "total_count": 123,
+  "warnings": [ProductSearchWarning]
 }
 
    
                   
@@ -4213,41 +4011,38 @@ 
    Example
    
             back to top
           
    
         
    
-        
    
+        
    
           
    
             Types
           
    
-          
    ProductSearchItem
    
+          
    ProductSearchSortInput
    
           
    
             
    
               
    
                 
    Description
    
-                
    A single product returned by the query
    
+                
    The product attribute to sort on
    
               
    
               
    
                 
    Fields
    
                 
-                      
+                      
-                      
-                      
-                    
-                    
-                      
-                      
+                      
-                      
-                      
+                      
    
                   
                     
    Field NameInput Field
                       Description
                     
    
                       
                   
                     
    applied_query_rule - AppliedQueryRule
-                       The query rule type that was applied to this product, if any (in preview mode only, returns null otherwise) 
    highlights - [Highlight]
+                      
+                        attribute - String!
                        An object that provides highlighted text for matched words  The attribute code of a product attribute 
                     
    
                     
    productView - ProductView
+                      
+                        direction - SortEnum!
                        Contains a product view  ASC (ascending) or DESC (descending) 
                     
    
                       
                 
    
@@ -4258,11 +4053,7 @@ 
    Fields
    
                 
    Example
    
                 
                   
-                  
    {
-  "applied_query_rule": AppliedQueryRule,
-  "highlights": [Highlight],
-  "productView": ProductView
-}
+                  
    {"attribute": "xyz789", "direction": "ASC"}
 
    
                   
                 
@@ -4271,16 +4062,16 @@ 
    Example
    
             back to top
           
    
         
    
-        
    
+        
    
           
    
             Types
           
    
-          
    ProductSearchResponse
    
+          
    ProductSearchWarning
    
           
    
             
    
               
    
                 
    Description
    
-                
    Contains the output of a productSearch query
    
+                
    Structured warning with code and message for easier client handling
    
               
    
               
    
                 
    Fields
    
@@ -4293,34 +4084,14 @@ 
    Fields
    
                   
                   
                     
-                      facets - [Aggregation]
+                      code - String!
                       
-                       Details about the static and dynamic facets relevant to the search 
+                       Error code for programmatic handling (e.g., EMPTY_CATEGORY_PATH) 
                     
                     
-                      items - [ProductSearchItem]
-                      
-                       An array of products returned by the query 
-                    
-                    
-                      page_info - SearchResultPageInfo
-                      
-                       Information for rendering pages of search results 
-                    
-                    
-                      related_terms - [String]
-                      
-                       An array of strings that might include merchant-defined synonyms 
-                    
-                    
-                      suggestions - [String]
+                      message - String!
                       
-                       An array of strings that include the names of products and categories that exist in the catalog that are similar to the search query 
-                    
-                    
-                      total_count - Int
-                      
-                       The total number of products returned that matched the query 
+                       Human-readable message describing the warning 
                     
                   
                 
@@ -4332,58 +4103,9 @@ 
    Example
    
                 
                   
                   
    {
-  "facets": [Aggregation],
-  "items": [ProductSearchItem],
-  "page_info": SearchResultPageInfo,
-  "related_terms": ["xyz789"],
-  "suggestions": ["abc123"],
-  "total_count": 987
+  "code": "xyz789",
+  "message": "xyz789"
 }
-
    
-                  
-                
-              
    
-            
    
-            back to top
-          
    
-        
    
-        
    
-          
    
-            Types
-          
    
-          
    ProductSearchSortInput
    
-          
    
-            
    
-              
    
-                
    Description
    
-                
    The product attribute to sort on
    
-              
    
-              
    
-                
    Fields
    
-                
-                  
-                    
-                      
-                      
-                    
-                  
-                  
-                    
-                      
-                      
-                    
-                  
-                
    Input FieldDescription
    
-                        attribute - String!
-                       The attribute code of a product attribute 
    
-              
    
-            
    
-            
    
-              
    
-                
    Example
    
-                
-                  
-                  
    {"attribute": "xyz789"}
 
    
                   
                 
@@ -4434,7 +4156,7 @@ 
    Fields
    
                     
                       attributes - [ProductViewAttribute]
                       
-                       A list of merchant-defined attributes designated for the storefront. 
+                       A list of merchant-defined attributes designated for the storefront. They can be filtered by roles and names. 
                     
                     
                       
@@ -4445,6 +4167,10 @@ 
     Arguments 
    
                               
    roles - [String]
                               
    
                             
    
+                            
    
+                              
    names - [String]
+                              
    
+                            
    
                           
    
                         
    
                       
@@ -4512,6 +4238,12 @@ 
    roles
                        A summary of the product. 
                     
+                    
+                      inputOptions - [ProductViewInputOption]
+                      
+                       A list of input options. This field is deprecated and will be removed.
+                      
+                    
                     
                       sku - String
                       
@@ -4552,6 +4284,24 @@ 
    linkTypes
                       
                     
+                    
+                      categories - [CategoryProductView!]
+                      
+                       A list of categories in which the product is present. 
+                    
+                    
+                      
+                        
    
+                          
     Arguments 
    
+                          
    
+                            
    
+                              
    family - String
+                              
    
+                            
    
+                          
    
+                        
    
+                      
+                    
                     
                       queryType - String
                       
@@ -4595,10 +4345,10 @@ 
    Example
    
                   
                   
    {
   "addToCartAllowed": false,
-  "inStock": true,
-  "lowStock": false,
+  "inStock": false,
+  "lowStock": true,
   "attributes": [ProductViewAttribute],
-  "description": "abc123",
+  "description": "xyz789",
   "id": "4",
   "images": [ProductViewImage],
   "videos": [ProductViewVideo],
@@ -4606,15 +4356,17 @@ 
    Example
    
   "metaDescription": "xyz789",
   "metaKeyword": "xyz789",
   "metaTitle": "abc123",
-  "name": "abc123",
-  "shortDescription": "xyz789",
-  "sku": "abc123",
-  "externalId": "xyz789",
-  "url": "xyz789",
+  "name": "xyz789",
+  "shortDescription": "abc123",
+  "inputOptions": [ProductViewInputOption],
+  "sku": "xyz789",
+  "externalId": "abc123",
+  "url": "abc123",
   "urlKey": "xyz789",
   "links": [ProductViewLink],
+  "categories": [CategoryProductView],
   "queryType": "abc123",
-  "visibility": "xyz789"
+  "visibility": "abc123"
 }
 
    
                   
@@ -4676,8 +4428,8 @@ 
    Example
    
                   
                   
    {
   "label": "abc123",
-  "name": "abc123",
-  "roles": ["abc123"],
+  "name": "xyz789",
+  "roles": ["xyz789"],
   "value": {}
 }
 
    
@@ -5963,7 +5715,7 @@ 
    Example
    
                 
                   
                   
    {
-  "label": "abc123",
+  "label": "xyz789",
   "roles": ["xyz789"],
   "url": "xyz789"
 }
@@ -5975,16 +5727,16 @@ 
    Example
    
             back to top
           
         
    
-