openapi: 3.0.3
externalDocs:
  url: https://github.com/adobe-commerce/aco-ts-sdk/blob/main/README.md
  description: Learn about the Adobe Commerce Optimizer TypeScript and JavaScript SDK for Merchandising Services
info:
  title: Catalog Data Ingestion API
  description: |
    The Catalog Data Ingestion API allows you to create and manage products and price books and directly integrate catalog data with the Commerce catalog service.

    This API provides the following resource collections to create and update catalog data:

    - <strong>[Product Metadata](#tag/ProductMetadata)</strong>—define and manage product attribute metadata including display settings, search characteristics, filtering options, and sorting rules.
    - <strong>[Category Metadata](#tag/CategoryMetadata)</strong>—define and manage category attribute metadata.
    - <strong>[Categories](#tag/Categories)</strong>—Define and manage categories with hierarchical structure to build navigation menu.
    - <strong>[Products](#tag/Products)</strong>—Define and manage catalog items with their attributes (name, description, SKU, images, and variants).
    - <strong>[Price books](#tag/Price-Books)</strong>—Define and manage pricing scopes for different customer tiers and markets.
    - <strong>[Prices](#tag/Prices)</strong>—Define and manage product SKU prices and their associated price books.
    - <strong>[Product Layers](#tag/Product-Layers)</strong>—Define and manage product layers to customize and override base product data for specific contexts, locales, or business requirements.
  version: 1.0.0
servers:
  - url: https://na1-sandbox.api.commerce.adobe.com/{tenantId}
    variables:
      tenantId:
        default: string
tags:
  - name: ProductMetadata
    description: |
      Manage product attribute definitions including display settings, search behavior, and filtering capabilities.
      These settings control how product attributes appear and function throughout the storefront.

      Product attribute metadata specifies how product attributes are displayed on the storefront.
      For example, you can define a product attribute as searchable, filterable, and sortable.
      You can also define the search type for a product attribute, such as autocomplete or exact match.
  - name: CategoryMetadata
    description: |
      Manage category attribute definitions.
      These settings control how category attributes appear and function throughout the storefront.

      Category attribute metadata specifies how category attributes are displayed on the storefront.
  - name: Categories
    description: |
      Manage categories in a hierarchical structure with localization support.
      Categories organize products into logical groups and support nested hierarchies using slug-based paths.

      Category management includes:
      - Creating categories with localized names and hierarchical slugs
      - Updating existing category information
      - Deleting categories from the catalog
      - Associating categories with product families for enhanced organization
      - Adding SEO meta tags (title, description, keywords) to categories
      - Associating images with categories

      Categories use a slug-based hierarchy format to represent parent-child relationships, for example, "men/clothing/pants".

      After you create categories and assign them to products, you can retrieve category data to render storefront menus and manage hierarchical category
      trees using the GraphQL `navigation` and `categorytree` queries. See
      [Implement categories on the storefront](https://developer.adobe.com/commerce/services/optimizer/merchandising-services/categories-storefront-implementation/).

  - name: Products
    description: Create and manage product data including simple products, configurable products, and their variants. Control product visibility, attributes, images, and pricing
  - name: Price Books
    description: |
      Define pricing scopes to manage product prices across different customer tiers and markets. Price books support a hierarchical model, allowing up to three levels of nested child price books under each base price book. Each price book can reference a parent price book, forming a tree structure for pricing scopes.

      The base price book defines the currency for itself and all its child price books. Child price books inherit this currency and cannot override it.

      <strong>Note:</strong> You cannot assign a parent price book to a base price book. Due to the asynchronous nature of the API, this validation is not enforced at runtime. API requests that attempt to set a parent price book for a base price book are ignored.

  - name: Prices
    description: |
      Manage product SKU prices across different price books and customer tiers. Define regular prices,
      discounts, and tiered pricing for specific customer segments or markets by specifying a price book id.

      Before creating prices with the Prices API, first create [Price books](#tag/Price-Books). Prices that reference a non-existing price book are ignored.

      The Prices API supports three main pricing components:

      * **Regular Price** - The base price for a product SKU in a specific price book
      * **Discounts** - Percentage or fixed amount discounts applied to the regular price
      * **Tiered Pricing** - Quantity-based pricing that offers different prices based on purchase quantity.
        Tiered pricing can be configured as a fixed or percentage price.

      <h3>Price lookup logic</h3>

      The product price lookup follows a hierarchical path through price books. The search starts at the specified price book
      and traverses upward through parent price books until it finds a price or reaches the root level. A product is not assigned
      a price if:
        - No price is found in the entire hierarchy
        - The price book specified in a price record has not been created

      <h3>Important notes</h3>

      * You cannot define prices for configurable products. Prices for configurable products are calculated based on the price of the selected product variant.
      * Each discount requires a unique `code` identifier to distinguish between different discount types.
      * Tier quantities must be greater than 1.

      <h3>Best practices</h3>

      **Price Book Management**
      * Create price books before defining prices
      * Use descriptive price book IDs and names
      * Plan your pricing hierarchy before implementation
      * Test price book relationships in development

      **Pricing Strategy**
      * Use consistent discount codes across your catalog
      * Implement tiered pricing for bulk purchase incentives
      * Consider geographic and customer segment pricing
      * Monitor price performance and adjust strategies

      **Data Management**
      * Validate all price data before sending to production
      * Use bulk operations for large price updates
      * Implement proper error handling for failed requests
      * Keep backup copies of pricing configurations

      **Performance Considerations**
      * Batch price updates for better performance
      * Use gzip compression for large payloads
      * Monitor API rate limits (300 requests per minute)
      * Implement retry logic for failed requests

      <strong>Common Use Cases</strong>

      **Seasonal Pricing**
      ```json
      {
        "sku": "summer-dress",
        "priceBookId": "us-seasonal",
        "regular": 89.99,
        "discounts": [
          {
            "code": "summer_sale",
            "percentage": 30
          }
        ]
      }
      ```

      **Customer Segment Pricing**
      ```json
      {
        "sku": "premium-product",
        "priceBookId": "us-vip",
        "regular": 199.99,
        "discounts": [
          {
            "code": "vip_member",
            "percentage": 20
          }
        ],
        "tierPrices": [
          {
            "qty": 2,
            "percentage": 10
          }
        ]
      }
      ```

      **Bulk Purchase Incentives**
      ```json
      {
        "sku": "office-supplies",
        "priceBookId": "us-business",
        "regular": 15.99,
        "tierPrices": [
          {
            "qty": 10,
            "price": 12.99
          },
          {
            "qty": 25,
            "price": 10.99
          },
          {
            "qty": 50,
            "percentage": 35
          }
        ]
      }
      ```

paths:
  /v1/catalog/products/metadata:
    post:
      tags:
        - ProductMetadata
      summary: Create product attribute metadata
      description: |
        To ensure product data is indexed for discovery, create or replace existing product attribute metadata resources before creating products.

        For each Commerce project, you must define metadata for the following attributes for each catalog source (`locale`):
          - `sku`
          - `name`
          - `description`
          - `shortDescription`
          - `price`

        Also, you can define metadata for custom attributes.

        When creating product attribute metadata:
          - Each product attribute requires a unique `code` and `source`.
          - Use the `dataType` field to define the data type for the product attribute.
          - Use the `visibleIn` field to define where the product attribute is displayed on the storefront.
          - Use the `filterable`, `sortable`, and `searchable` fields to define how the product attribute
            is used for filtering, sorting, and searching.
          - Use the `searchWeight` field to define the search weight for the product attribute.
          - Use the `searchTypes` field to define the search type for the product attribute.

        To update existing product attribute metadata, use the update operation.

      operationId: createProductMetadata
      parameters:
        - $ref: "#/components/parameters/Authorization"
        - $ref: "#/components/parameters/ContentType"
        - $ref: "#/components/parameters/ContentEncoding"
      responses:
        "200":
          $ref: "#/components/responses/AcceptedResponse"
        "400":
          $ref: "#/components/responses/InvalidItemsResponse"
        "401":
          $ref: "#/components/responses/UnauthorizedResponse"
        "403":
          $ref: "#/components/responses/ForbiddenResponse"
        "429":
          $ref: "#/components/responses/TooManyRequestsResponse"
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: "#/components/schemas/FeedProductMetadata"
            examples:
              FeedWithMetadataInformation:
                summary: Create product attributes metadata
                description: |
                  Creates searchable text attributes. This example defines metadata for the required attributes
                  with recommended default values.
                value:
                  [
                    {
                      "code": "sku",
                      "source": { "locale": "en-US" },
                      "label": "Product Name",
                      "dataType": "TEXT",
                      "visibleIn":
                        [
                          "PRODUCT_DETAIL",
                          "PRODUCT_LISTING",
                          "SEARCH_RESULTS",
                          "PRODUCT_COMPARE"
                        ],
                      "filterable": true,
                      "sortable": false,
                      "searchable": true,
                      "searchWeight": 1,
                      "searchTypes": ["AUTOCOMPLETE"]
                    },
                    {
                      "code": "name",
                      "source": { "locale": "en-US" },
                      "label": "Product Name",
                      "dataType": "TEXT",
                      "visibleIn":
                        [
                          "PRODUCT_DETAIL",
                          "PRODUCT_LISTING",
                          "SEARCH_RESULTS",
                          "PRODUCT_COMPARE"
                        ],
                      "filterable": false,
                      "sortable": true,
                      "searchable": true,
                      "searchWeight": 1,
                      "searchTypes": ["AUTOCOMPLETE"]
                    },
                    {
                      "code": "description",
                      "source": { "locale": "en-US" },
                      "label": "Product Description",
                      "dataType": "TEXT",
                      "visibleIn": ["PRODUCT_DETAIL"],
                      "filterable": false,
                      "sortable": false,
                      "searchable": false,
                      "searchWeight": 1,
                      "searchTypes": ["AUTOCOMPLETE"]
                    },
                    {
                      "code": "shortDescription",
                      "source": { "locale": "en-US" },
                      "label": "Product Short Description",
                      "dataType": "TEXT",
                      "visibleIn": ["PRODUCT_DETAIL"],
                      "filterable": false,
                      "sortable": false,
                      "searchable": true,
                      "searchWeight": 1,
                      "searchTypes": ["AUTOCOMPLETE"]
                    },
                    {
                      "code": "price",
                      "source": { "locale": "en-US" },
                      "label": "Price",
                      "dataType": "DECIMAL",
                      "visibleIn":
                        [
                          "PRODUCT_DETAIL",
                          "PRODUCT_LISTING",
                          "SEARCH_RESULTS",
                          "PRODUCT_COMPARE"
                        ],
                      "filterable": true,
                      "sortable": true,
                      "searchable": false,
                      "searchWeight": 1,
                      "searchTypes": []
                    }
                  ]
    patch:
      tags:
        - ProductMetadata
      summary: Update product attribute metadata
      description: |
        Update existing product attribute metadata with new values.
        When the update is processed, the merge strategy is used to apply changes to `scalar` and `object` type fields. The replace strategy is used to apply changes for fields in an `array`.

        > **Note:** Before submitting an update request, verify that the target entity exists using the
        [attributeMetadata](https://developer.adobe.com/commerce/services/includes/autogenerated/merchandising-api#attributemetadata) GraphQL query. Update operations do not verify that the entity exists. Requests targeting a nonexistent entity are accepted, but the update has no effect.
      operationId: updateProductMetadata
      parameters:
        - $ref: "#/components/parameters/Authorization"
        - $ref: "#/components/parameters/ContentType"
        - $ref: "#/components/parameters/ContentEncoding"
      responses:
        "200":
          $ref: "#/components/responses/AcceptedResponse"
        "400":
          $ref: "#/components/responses/InvalidItemsResponse"
        "401":
          $ref: "#/components/responses/UnauthorizedResponse"
        "403":
          $ref: "#/components/responses/ForbiddenResponse"
        "429":
          $ref: "#/components/responses/TooManyRequestsResponse"
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: "#/components/schemas/FeedProductMetadataUpdate"
            examples:
              FeedWithMetadataInformation:
                summary: Example of product attribute metadata
                description: |
                  Update existing product attribute metadata with new values.
                  Note that fields with the `array` type will replace existing data.
                  The example below updates the following attributes:
                  * `label` - Change the product attribute label.
                  * `visibleIn` - Add `PRODUCT_LISTING` role to the product attribute.
                value:
                  [
                    {
                      "code": "name",
                      "source": { "locale": "en-US" },
                      "label": "Updated - Product Name",
                      "visibleIn": [
                        "PRODUCT_DETAIL",
                        "PRODUCT_LISTING"
                      ]
                    }
                  ]

  /v1/catalog/products/metadata/delete:
    post:
      tags:
        - ProductMetadata
      summary: Delete product attributes metadata
      description: Remove product attribute metadata resources from the catalog data.
      operationId: deleteProductMetadata
      parameters:
        - $ref: "#/components/parameters/Authorization"
        - $ref: "#/components/parameters/ContentType"
        - $ref: "#/components/parameters/ContentEncoding"
      responses:
        "200":
          $ref: "#/components/responses/AcceptedResponse"
        "400":
          $ref: "#/components/responses/InvalidItemsResponse"
        "401":
          $ref: "#/components/responses/UnauthorizedResponse"
        "403":
          $ref: "#/components/responses/ForbiddenResponse"
        "429":
          $ref: "#/components/responses/TooManyRequestsResponse"
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: "#/components/schemas/FeedProductMetadataDelete"
            examples:
              FeedWithMetadataInformation:
                summary: Delete product attribute metadata
                description: Marks existing product attribute metadata as deleted.
                value: [
                  {
                    "code": "name",
                    "source": { "locale": "en-US" }
                  }
                ]

  /v1/catalog/categories/metadata:
    post:
      tags:
        - CategoryMetadata
      summary: Create category attribute metadata
      description: |
        When creating category attribute metadata:
          - Each category attribute requires a unique `code` and `source`.
          - Use the `dataType` field to define the data type for the category attribute.

        To update existing category attribute metadata, use the update operation.

      operationId: createCategoryMetadata
      parameters:
        - $ref: "#/components/parameters/Authorization"
        - $ref: "#/components/parameters/ContentType"
        - $ref: "#/components/parameters/ContentEncoding"
      responses:
        "200":
          $ref: "#/components/responses/AcceptedResponse"
        "400":
          $ref: "#/components/responses/InvalidItemsResponse"
        "401":
          $ref: "#/components/responses/UnauthorizedResponse"
        "403":
          $ref: "#/components/responses/ForbiddenResponse"
        "429":
          $ref: "#/components/responses/TooManyRequestsResponse"
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: "#/components/schemas/FeedCategoryMetadata"
            examples:
              FeedWithMetadataInformation:
                summary: Create category attributes metadata
                description: |
                  This example defines metadata for the required attributes with recommended default values.
                value:
                  [
                    {
                      "code": "bottom_description",
                      "source": { "locale": "en-US" },
                      "label": "Category Description",
                      "dataType": "TEXT"
                    }
                  ]
    patch:
      tags:
        - CategoryMetadata
      summary: Update category attribute metadata
      description: |
        Update existing category attribute metadata with new values.
        When the update is processed, the merge strategy is used to apply changes to `scalar` and `object` type fields. The replace strategy is used to apply changes for fields in an `array`.

        > **Note:** Update operations do not verify that the entity exists. Requests targeting a nonexistent entity are accepted, but the update has no effect.
      operationId: updateCategoryMetadata
      parameters:
        - $ref: "#/components/parameters/Authorization"
        - $ref: "#/components/parameters/ContentType"
        - $ref: "#/components/parameters/ContentEncoding"
      responses:
        "200":
          $ref: "#/components/responses/AcceptedResponse"
        "400":
          $ref: "#/components/responses/InvalidItemsResponse"
        "401":
          $ref: "#/components/responses/UnauthorizedResponse"
        "403":
          $ref: "#/components/responses/ForbiddenResponse"
        "429":
          $ref: "#/components/responses/TooManyRequestsResponse"
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: "#/components/schemas/FeedCategoryMetadataUpdate"
            examples:
              FeedWithMetadataInformation:
                summary: Example of category attribute metadata
                description: |
                  Update existing category attribute metadata with new values.
                  Note that fields with the `array` type will replace existing data.
                  The example below updates the following attributes:
                  * `label` - Change the category attribute label.
                value:
                  [
                    {
                      "code": "bottom_description",
                      "source": { "locale": "en-US" },
                      "label": "Updated - Category Description"
                    }
                  ]

  /v1/catalog/categories/metadata/delete:
    post:
      tags:
        - CategoryMetadata
      summary: Delete category attributes metadata
      description: Remove category attribute metadata resources from the catalog data.
      operationId: deleteCategoryMetadata
      parameters:
        - $ref: "#/components/parameters/Authorization"
        - $ref: "#/components/parameters/ContentType"
        - $ref: "#/components/parameters/ContentEncoding"
      responses:
        "200":
          $ref: "#/components/responses/AcceptedResponse"
        "400":
          $ref: "#/components/responses/InvalidItemsResponse"
        "401":
          $ref: "#/components/responses/UnauthorizedResponse"
        "403":
          $ref: "#/components/responses/ForbiddenResponse"
        "429":
          $ref: "#/components/responses/TooManyRequestsResponse"
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: "#/components/schemas/FeedCategoryMetadataDelete"
            examples:
              FeedWithMetadataInformation:
                summary: Delete category attribute metadata
                description: Marks existing category attribute metadata as deleted.
                value: [
                  {
                    "code": "bottom_description",
                    "source": { "locale": "en-US" }
                  }
                ]

  /v1/catalog/categories:
    post:
      tags:
        - Categories
      summary: Create categories
      description: |
        Create new categories with hierarchical structure and slug-based paths.
        Categories organize products into logical groups and support nested hierarchies.

        When creating categories:
          - Each category requires a unique `slug` and `source`.
          - To create parent-child relationships, create the `slug` field in a hierarchical format, for example `men/clothing/pants'.
          - A category `slug` string can contain only lowercase letters, numbers, and hyphens with `/` used as a separator for hierarchy.
          - Create each category as a separate entity.
          - Use the `name` field to define the display name for the category.
          - Use the optional `description` field to provide a full-text description of the category.
          - Use the optional `families` field to associate categories with product families for enhanced organization.
          - Use the optional `position` field to assign a numeric sort order to the category.
          - Use the optional `metaTags` field to define SEO meta tags (title, description, keywords) for the category.
          - Use the optional `images` field to associate images with the category.
          - Use the optional `attributes` field to add additional attributes.

        After you create categories, link a product to a category using the `path` value for the [routes](#operation/createProducts!path=routes&t=request) field. When you create or update products. The value of `path` in the route must match the `slug` value for the category.

        To update existing categories, use the update operation.

      operationId: createCategories
      parameters:
        - $ref: "#/components/parameters/Authorization"
        - $ref: "#/components/parameters/ContentType"
        - $ref: "#/components/parameters/ContentEncoding"
      responses:
        "200":
          $ref: "#/components/responses/AcceptedResponse"
        "400":
          $ref: "#/components/responses/InvalidItemsResponse"
        "401":
          $ref: "#/components/responses/UnauthorizedResponse"
        "403":
          $ref: "#/components/responses/ForbiddenResponse"
        "429":
          $ref: "#/components/responses/TooManyRequestsResponse"
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: "#/components/schemas/FeedCategory"
            examples:
              FeedWithCategoryInformation:
                summary: Create product categories
                description: |
                  Creates hierarchical product categories. This example shows creating parent and child categories
                  with product family associations.
                value:
                  [
                    {
                      "slug": "men",
                      "source": { "locale": "en-US" },
                      "name": "Men",
                      "description": "Men's clothing, shoes, and accessories",
                      "families": ["apparel", "accessories"],
                      "position": 1,
                      "metaTags": {
                        "title": "Men's Collection",
                        "description": "Shop men's clothing, shoes, and accessories",
                        "keywords": ["men", "clothing", "accessories"]
                      },
                      "attributes": [
                        {
                          "code": "bottom_description",
                          "values": ["The bottom description"]
                        }
                      ],
                      "images": [
                        {
                          "url": "https://example.com/images/men-category.png",
                          "label": "Men's Category",
                          "roles": ["BASE"],
                          "customRoles": []
                        }
                      ]
                    },
                    {
                      "slug": "men/clothing",
                      "source": { "locale": "en-US" },
                      "name": "Men's Clothing",
                      "description": "Men's clothing and apparel",
                      "families": ["apparel"]
                    },
                    {
                      "slug": "men/clothing/pants",
                      "source": { "locale": "en-US" },
                      "name": "Men's Pants",
                      "families": ["apparel"]
                    }
                  ]
    patch:
      tags:
        - Categories
      summary: Update categories
      description: |
        Update existing product categories with new values.
        When the update is processed, the merge strategy is used to apply changes to `scalar` and `object` type fields. The replace strategy is used to apply changes for fields in an `array`.

        > **Note:** Update operations do not verify that the entity exists. Requests targeting a nonexistent entity are accepted, but the update has no effect.
      operationId: updateCategories
      parameters:
        - $ref: "#/components/parameters/Authorization"
        - $ref: "#/components/parameters/ContentType"
        - $ref: "#/components/parameters/ContentEncoding"
      responses:
        "200":
          $ref: "#/components/responses/AcceptedResponse"
        "400":
          $ref: "#/components/responses/InvalidItemsResponse"
        "401":
          $ref: "#/components/responses/UnauthorizedResponse"
        "403":
          $ref: "#/components/responses/ForbiddenResponse"
        "429":
          $ref: "#/components/responses/TooManyRequestsResponse"
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: "#/components/schemas/FeedCategoryUpdate"
            examples:
              FeedWithCategoryInformation:
                summary: Example of category updates
                description: |
                  Update existing product categories with new values.
                  Note that fields with the `array` type will replace existing data.
                  The example below updates the following:
                  * `name` - Change the category display name.
                  * `families` - Replace the product families associated with the category.
                  * `metaTags` - Update the SEO meta tags for the category.
                  * `images` - Replace the images associated with the category.
                value:
                  [
                    {
                      "slug": "men/clothing",
                      "source": { "locale": "en-US" },
                      "name": "Men's Apparel",
                      "description": "Updated collection of men's apparel and fashion",
                      "families": ["clothing", "fashion"],
                      "metaTags": {
                        "title": "Men's Apparel - Updated",
                        "description": "Updated collection of men's apparel",
                        "keywords": ["men", "apparel", "fashion"]
                      },
                      "images": [
                        {
                          "url": "https://example.com/images/mens-apparel.png",
                          "label": "Men's Apparel",
                          "roles": ["BASE"],
                          "customRoles": []
                        }
                      ]
                    }
                  ]
  /v1/catalog/categories/delete:
    post:
      tags:
        - Categories
      summary: Delete categories
      description: |
        Delete categories and all their associated children

        <h3>Cascading Deletion</h3>

        When you delete a category:
        * **Child categories**: All child categories in the hierarchy are deleted automatically
        * **Hierarchy Impact**: The entire branch below the deleted category is removed

        <h3>Recovery Options</h3>

        If a category is deleted by mistake:
        * **Time Window**: You have up to one week to restore deleted categories
        * **Restoration Method**: Recreate the top-level deleted category using the [Create category operation](#operation/createCategories)
        * **State Recovery**: Categories are restored to their exact state from the time of deletion, including all metadata, family associations, and hierarchy relationships
        * **Hierarchy Reconstruction**: The entire hierarchy is rebuilt from the restoration payload

      operationId: deleteCategories
      parameters:
        - $ref: "#/components/parameters/Authorization"
        - $ref: "#/components/parameters/ContentType"
        - $ref: "#/components/parameters/ContentEncoding"
      responses:
        "200":
          $ref: "#/components/responses/AcceptedResponse"
        "400":
          $ref: "#/components/responses/InvalidItemsResponse"
        "401":
          $ref: "#/components/responses/UnauthorizedResponse"
        "403":
          $ref: "#/components/responses/ForbiddenResponse"
        "429":
          $ref: "#/components/responses/TooManyRequestsResponse"
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: "#/components/schemas/FeedCategoryDelete"
            examples:
              FeedWithCategoryInformation:
                summary: Delete categories
                description: Marks existing categories as deleted.
                value: [
                  {
                    "slug": "men/clothing/pants",
                    "source": { "locale": "en-US" }
                  },
                  {
                    "slug": "women/shoes/boots",
                    "source": { "locale": "en-US" }
                  }
                ]

  /v1/catalog/products:
    post:
      tags:
        - Products
      summary: Create or replace products
      description: |
        You can create different types of products, such as simple products and configurable products.

        When creating products:
         - Each product requires a unique SKU identifier.
         - Products must have a defined catalog source, for example `locale`.
         - Add values for the required `name`, `slug`, and `status` fields.
         - Define optional fields such as descriptions, images, and custom attributes as needed.
         - Use the `links` field to define relationships between products, such as linking a product variant to its parent
         configurable product.
         - You can create multiple products in a single request, and also create product variants for configurable products in the same request.
         - Use the `routes` field to set category paths. The `path` value must match an existing category slug, for example `men/clothing`. 
         - Create a route for each category path. For example to include a product in each of the following categories `men`, `men/clothing`, and `men/clothing/pants`, specify three `path` values, one for each category.

        <h3 id="simpleProducts">Simple products</h3>
        Create products or replace existing products with specified `sku` and `source` values.

        Use the <strong>[update operation](#operation/updateProducts)</strong> to modify values for an existing product.

        <h3 id="configurableProducts">Configurable products</h3>

        A configurable product is a parent product that allows customers to select from multiple predefined attributes such as color, size, and material.
        Each unique combination of these attribute values (for example, `color=green`, `size=large`) represents a product variant.

        Each variant is treated as a distinct child product with its own SKU, price, and inventory. These variants are stored as separate entities in the database and linked to the parent configurable product.

        The configurable product itself acts as a container or abstraction layer, enabling a unified frontend experience while maintaining
        granular control over each variant on the backend.

        To create a configurable product, you need the following:

        * <strong>Product attributes</strong>—<a href="#operation/createProductMetadata">Create product attributes</a> (for example, "color", "size")
        that will be used to differentiate product variants. These attributes must be registered in the system before they can be referenced in
        product definitions.

        * <strong>Configurable product</strong>—Define the parent product and include a
          [configurations](#operation/createProducts!path=configurations&t=request) array that specifies the selectable options
          and maps each option to a set of possible values. Each value must include a
          [variantReferenceId](#operation/createProducts!path=configurations/values/variantReferenceId&t=request),
          which links to a specific variant.

        * <strong>Product variants</strong>—Define a product variant for each valid combination of attribute values. Each variant must:
          * Include relevant attribute values in an [attributes](#operation/createProducts!path=attributes&t=request) array.
          * Reference the parent configurable product using variantReferenceId.
          * Include a [links](#operation/createProducts!path=links&t=request) array with a link of type `VARIANT_OF` pointing to the configurable product.

          For example:

          <pre>
          {
            "sku": "pants-red-32",
            "attributes": [
              {
                "code": "color",
                "values": ["Red"],
                "variantReferenceId": "pants-color-red"
              }
            ],
            "links": [
              {
                "type": "VARIANT_OF",
                "sku": "pants"
              }
            ]
          }
        </pre>

          Each product variant links back to the configurable product through its `variantReferenceId`, which corresponds to specific `configurations[].values[].variantReferenceId` in the configurable product.

          To unassign a product variant from a configurable product, do one of the following:
          - Use [Delete Product API](#operation/deleteProducts) to delete the product variant.
          - Use [Update Product API](#operation/updateProducts) to set the ["variantReferenceId"](#operation/createProducts!path=attributes/variantReferenceId&t=request) to `null` and unassign the product variant from the configurable product by removing the ["links"](#operation/createProducts!path=links&t=request) association.

        <h3>Bundle products</h3>

        A bundle product combines several simple products into one sellable unit. Items within the bundle can be categorized into logical groups like `tops`, `bottoms`, and `accessories`.
        Each group can have multiple items, and shoppers can select items from each group to create a customized bundle.

        To create a bundle product, you need the following:

        * <strong>Bundle product</strong>—[Define the parent product](#operation/createProducts) and include a [bundles](#operation/createProducts!path=bundles) array that
        specifies the groups and items included in the bundle. Each group must define:
          * `group` - Name of the group (for example, "tops", "bottoms")
          * `required` - Whether a selection from this group is mandatory
          * `multiSelect` - Whether multiple items can be selected
          * `items` - List of products that can be selected from this group

        * <strong>Simple products</strong>—Define each simple product to include in the bundle. Each product must:
          * Include a [links](#operation/createProducts!path=links) array with a link of type `IN_BUNDLE` pointing to the bundle product
          * Be created separately using the [create product API](#operation/createProducts)

        <strong>Note:</strong> A simple product can be included only once in each bundle.
        If the same item is specified in multiple groups, the API returns a `Duplicate SKU found in bundle items` error.

        To update a bundle product, do one of the following:
        * Use the [Update products API](#operation/updateProducts) to modify the groups and items in the bundle
        * Use the [Delete products API](#operation/deleteProducts) to remove items from the bundle
      operationId: createProducts
      parameters:
        - $ref: "#/components/parameters/Authorization"
        - $ref: "#/components/parameters/ContentType"
        - $ref: "#/components/parameters/ContentEncoding"
      responses:
        "200":
          $ref: "#/components/responses/AcceptedResponse"
        "400":
          $ref: "#/components/responses/InvalidItemsResponse"
        "401":
          $ref: "#/components/responses/UnauthorizedResponse"
        "403":
          $ref: "#/components/responses/ForbiddenResponse"
        "429":
          $ref: "#/components/responses/TooManyRequestsResponse"
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: "#/components/schemas/FeedProduct"
            examples:
              SimpleProductWithImages:
                summary: Create a simple product
                description: >
                  Create a simple product with required and optional fields.
                value:
                  [
                    {
                      "sku": "red-pants",
                      "source": { "locale": "en-US" },
                      "name": "red pants",
                      "slug": "red-pants.html",
                      "status": "ENABLED",
                      "description": "long description about red pants",
                      "shortDescription": "just pants",
                      "visibleIn":
                        [
                        "CATALOG",
                        "SEARCH"
                        ],
                      "metaTags":
                        {
                          "title": "Yoga pants ",
                          "description": "Climb with Zeppelin Yoga Pant",
                          "keywords": ["pants", "yoga"]
                        },
                      "attributes":
                        [
                          {
                            "code": "cost",
                            "values": ["10.5"]
                          },
                          {
                            "code": "states",
                            "values": ["TX", "CA"]
                          }
                        ],
                      "images":
                        [
                          {
                            "url": "https://example.com/images/pants.jpg",
                            "label": "photo of my pants!",
                            "roles": ["BASE", "THUMBNAIL"],
                            "customRoles": ["widget"]
                          }
                        ],
                      "routes":
                        [
                          { "path": "men" },
                          { "path": "men/clothing/", "position": 1 },
                          { "path": "men/clothing/pants", "position": 1}
                        ]
                    }
                  ]
              ConfigurableProductWithVariants:
                summary: Create a configurable product with four product variants
                description: >
                  Create a configurable product `pants` with four product variants: `pants-red-32`, `pants-red-44`, `pants-green-32` and `pants-green-44`.
                value:
                  [
                    {
                      "sku": "pants",
                      "source": { "locale": "en-US" },
                      "name": "Yoga pants",
                      "slug": "zeppelin-yoga-pant",
                      "status": "ENABLED",
                      "visibleIn": ["CATALOG"],
                      "configurations":
                        [
                          {
                            "attributeCode": "color",
                            "label": "Pants color",
                            "defaultVariantReferenceId": "pants-color-red",
                            "type": "SWATCH",
                            "values":
                              [
                                {
                                  "variantReferenceId": "pants-color-red",
                                  "label": "Red",
                                  "colorHex": "#ff0000"
                                },
                                {
                                  "variantReferenceId": "pants-color-green",
                                  "label": "Green",
                                  "imageUrl": "https://www.example.com/media/catalog/product/green_main_1.jpg"
                                }
                              ]
                          },
                          {
                            "attributeCode": "size",
                            "label": "Pants size",
                            "defaultVariantReferenceId": "pants-size-32",
                            "type": "CONFIGURABLE",
                            "values":
                              [
                                {
                                  "variantReferenceId": "pants-size-32",
                                  "label": "32"
                                },
                                {
                                  "variantReferenceId": "pants-size-44",
                                  "label": "44"
                                }
                              ]
                          }
                        ]
                    },
                    {
                      "sku": "pants-red-32",
                      "source": { "locale": "en-US" },
                      "name": "Zeppelin Yoga Pant Red 32 size",
                      "slug": "pants-red-32",
                      "status": "ENABLED",
                      "attributes":
                        [
                          {
                            "code": "color",
                            "values": ["Red Pants"],
                            "variantReferenceId": "pants-color-red"
                          },
                          {
                            "code": "size",
                            "values": ["32"],
                            "variantReferenceId": "pants-size-32"
                          }
                        ],
                      "links":
                        [
                          {
                            "type": "variant_of",
                            "sku": "pants"
                            }
                        ]
                    },
                    {
                      "sku": "pants-red-44",
                      "source": { "locale": "en-US" },
                      "name": "Zeppelin Yoga Pant Red 44 size",
                      "slug": "pants-red-44",
                      "status": "ENABLED",
                      "attributes":
                        [
                          {
                            "code": "color",
                            "values": ["Red Pants"],
                            "variantReferenceId": "pants-color-red"
                          },
                          {
                            "code": "size",
                            "values": ["44"],
                            "variantReferenceId": "pants-size-44"
                          }
                        ],
                      "links":
                        [
                          {
                            "type": "VARIANT_OF",
                            "sku": "pants"
                          }
                        ]
                    },
                    {
                      "sku": "pants-green-32",
                      "source": { "locale": "en-US" },
                      "name": "Zeppelin Yoga Pant Green 32 size",
                      "slug": "pants-green-32",
                      "status": "ENABLED",
                      "attributes":
                        [
                          {
                            "code": "color",
                            "values": ["Green Pants"],
                            "variantReferenceId": "pants-color-green"
                          },
                          {
                            "code": "size",
                            "values": ["32"],
                            "variantReferenceId": "pants-size-32"
                          }
                        ],
                      "links":
                        [
                          {
                            "type": "VARIANT_OF",
                            "sku": "pants"
                          }
                        ]
                    },
                    {
                      "sku": "pants-green-44",
                      "source": { "locale": "en-US" },
                      "name": "Zeppelin Yoga Pant green 44 size",
                      "slug": "pants-green-44",
                      "status": "ENABLED",
                      "attributes":
                        [
                          {
                            "code": "color",
                            "values": ["Green Pants"],
                            "variantReferenceId": "pants-color-green"
                          },
                          {
                            "code": "size",
                            "values": ["44"],
                            "variantReferenceId": "pants-size-44"
                          }
                        ],
                      "links":
                        [
                          {
                            "type": "VARIANT_OF",
                            "sku": "pants"
                          }
                        ]
                    }
                  ]
              BundleProductWithItems:
                summary: Create a bundle product with multiple items
                description: >
                  Create a bundle product `bundle-outfit` with multiple items grouped into categories like `tops`, `bottoms`, and `accessories`.
                  An item can be included only once in each bundle product.
                value:
                  [
                    {
                      "sku": "bundle-outfit",
                      "source": { "locale": "en-US" },
                      "name": "Bundle Outfit",
                      "slug": "bundle-outfit",
                      "status": "ENABLED",
                      "visibleIn": ["CATALOG"],
                      "bundles":
                        [
                          {
                            "group": "tops",
                            "required": true,
                            "multiSelect": false,
                            "defaultItemSkus": ["top-red"],
                            "items":
                              [
                                {
                                  "sku": "top-red",
                                  "qty": 1,
                                  "userDefinedQty": false
                                },
                                {
                                  "sku": "top-blue",
                                  "qty": 1,
                                  "userDefinedQty": false
                                }
                              ]
                          },
                          {
                            "group": "bottoms",
                            "required": true,
                            "multiSelect": false,
                            "defaultItemSkus": ["bottom-black"],
                            "items":
                              [
                                {
                                  "sku": "bottom-black",
                                  "qty": 1,
                                  "userDefinedQty": false
                                },
                                {
                                  "sku": "bottom-white",
                                  "qty": 1,
                                  "userDefinedQty": false
                                }
                              ]
                          },
                          {
                            "group": "accessories",
                            "required": false,
                            "multiSelect": true,
                            "items":
                              [
                                {
                                  "sku": "socks",
                                  "qty": 1,
                                  "userDefinedQty": true
                                },
                                {
                                  "sku": "headband",
                                  "qty": 1,
                                  "userDefinedQty": true
                                }
                              ]
                          }
                        ]
                    },
                    {
                      "sku": "top-red",
                      "source": { "locale": "en-US" },
                      "name": "Red Top",
                      "slug": "top-red",
                      "status": "ENABLED",
                      "visibleIn": ["CATALOG"],
                      "links":
                        [
                          { "type": "in_bundle",
                          "sku": "bundle-outfit"
                          }
                        ]
                    },
                    {
                      "sku": "top-blue",
                      "source": { "locale": "en-US" },
                      "name": "Blue Top",
                      "slug": "top-blue",
                      "status": "ENABLED",
                      "visibleIn": ["CATALOG"],
                      "links":
                        [
                          { "type": "in_bundle",
                          "sku": "bundle-outfit"
                          }
                        ]
                    },
                    {
                      "sku": "bottom-black",
                      "source": { "locale": "en-US" },
                      "name": "Black Bottom",
                      "slug": "bottom-black",
                      "status": "ENABLED",
                      "visibleIn": ["CATALOG"],
                      "links":
                        [
                          { "type": "in_bundle",
                          "sku": "bundle-outfit"
                          }
                        ]
                    },
                    {
                      "sku": "bottom-white",
                      "source": { "locale": "en-US" },
                      "name": "White Bottom",
                      "slug": "bottom-white",
                      "status": "ENABLED",
                      "visibleIn": ["CATALOG"],
                      "links":
                        [
                          { "type": "in_bundle",
                          "sku": "bundle-outfit"
                          }
                        ]
                    },
                    {
                      "sku": "socks",
                      "source": { "locale": "en-US" },
                      "name": "Socks",
                      "slug": "socks",
                      "status": "ENABLED",
                      "visibleIn": ["CATALOG"],
                      "links":
                        [
                          { "type": "in_bundle",
                          "sku": "bundle-outfit"
                          }
                        ]
                    },
                    {
                      "sku": "headband",
                      "source": { "locale": "en-US" },
                      "name": "Headband",
                      "slug": "headband",
                      "status": "ENABLED",
                      "visibleIn": ["CATALOG"],
                      "links":
                        [
                          { "type": "in_bundle",
                          "sku": "bundle-outfit"
                          }
                        ]
                    }
                  ]
    patch:
      tags:
        - Products
      summary: Update products
      description: |
        Update products with specified `sku` and `source` values to replace existing field data with the data supplied in the request.
        When the update is processed, the merge strategy is used to apply changes to `scalar` and `object` type fields.

        For `array` type fields, a new value can be appended to the existing list. For an object list, you can update a specific object by matching on a key field. The following fields are supported:
        * `attributes` - match on `code`
        * `images` - match on `url`
        * `routes` - match on `path`
        * `links` - match on `type` and `sku`
        * `bundles` match on `type` and `group`
        * `configurations` match on `type` and `attributeCode`
        * `externalIds` match on `type` and `origin`

        > **Note:** Before submitting an update request, verify that the target entity exists using the [products](https://developer.adobe.com/commerce/services/includes/autogenerated/merchandising-api#products) GraphQL query. Update operations do not verify that the entity exists. Requests targeting a nonexistent entity are accepted, but the update has no effect.
      operationId: updateProducts
      parameters:
        - $ref: "#/components/parameters/Authorization"
        - $ref: "#/components/parameters/ContentType"
        - $ref: "#/components/parameters/ContentEncoding"
      responses:
        "200":
          $ref: "#/components/responses/AcceptedResponse"
        "400":
          $ref: "#/components/responses/InvalidItemsResponse"
        "401":
          $ref: "#/components/responses/UnauthorizedResponse"
        "403":
          $ref: "#/components/responses/ForbiddenResponse"
        "429":
          $ref: "#/components/responses/TooManyRequestsResponse"
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: "#/components/schemas/FeedProductUpdate"
            examples:
              SimpleProductWithImages:
                summary: Update a simple product
                description: |
                  Update a simple product with the values provided in the request.
                  On update, changes to `scalar` and `object` type fields are applied using the merge strategy.
                  The replace strategy is used to apply changes for fields in an `array`.

                  In the example below, the following attributes are updated.
                  * `name` - Change the product name.
                  * `metaTags.title` - Change the title of the product detail page.
                value:
                  [
                    {
                      "sku": "red-pants",
                      "source": { "locale": "en-US" },
                      "name": "Red pants - discounts!",
                      "metaTags": { "title": "Updated - Red" }
                    }
                  ]
              UnassignProductVariant:
                summary: Unassign product variant `pants-red-32` from configurable product `pants`
                description: |
                  To unassign product variant `pants-red-32` from configurable product `pants` you need:
                  * remove the `variantReferenceId` from the `attributes` field
                  * remove the `links` association
                value:
                  [
                    {
                      "sku": "pants-red-32",
                      "source": { "locale": "en-US" },
                      "attributes":
                        [
                          {
                            "code": "color",
                            "values": ["Red Pants"],
                            "variantReferenceId": null
                          },
                          {
                            "code": "size",
                            "values": ["32"],
                            "variantReferenceId": null
                          }
                        ],
                      "links": []
                    }
                  ]
              AddNewAccessoryItem:
                summary: Add a new item `gloves` to the accessories group of the bundle product `bundle-outfit`
                description: |
                  To add a new item `gloves` to the accessories group of the bundle product `bundle-outfit`, include the new item in the `items` array of the `accessories` group.
                  The previously created items `socks` and `headband` should be retained in the updated bundle.
                  Note that simple product `gloves` must be created separately using the create product API.
                value:
                  [
                    {
                      "sku": "bundle-outfit",
                      "source": { "locale": "en-US" },
                      "bundles":
                        [
                          {
                            "group": "accessories",
                            "required": false,
                            "multiSelect": true,
                            "items":
                              [
                                {
                                  "sku": "socks",
                                  "qty": 1,
                                  "userDefinedQty": true
                                },
                                {
                                  "sku": "headband",
                                  "qty": 1,
                                  "userDefinedQty": true
                                },
                                {
                                  "sku": "gloves",
                                  "qty": 1,
                                  "userDefinedQty": true
                                }
                              ]
                          }
                        ]
                    }
                  ]
              AddNewAttributeAndReplaceExisting:
                summary: Add a new attribute and replace existing one
                description: |
                  Add a new attribute `warehouse`, and update the value of the existing `cost` attribute for the simple product `red-pants`

                  In the example below:
                  * A new attribute with the code `warehouse` is added to the attributes list
                  * The value of the existing `cost` attribute is replaced with new value

                  The previously created `states` attribute is preserved.
                  Note: Don't forget to create the product attribute metadata (<a href="#operation/createProductMetadata">link</a> for the `warehouse` attribute if it doesn't exist yet.
                value:
                  [
                    {
                      "sku": "red-pants",
                      "source": { "locale": "en-US" },
                      "attributes":
                        [
                          {
                            "code": "warehouse",
                            "values": [ "Austin" ]
                          },
                          {
                            "code": "cost",
                            "values": ["12"]
                          }
                        ]
                    }
                  ]
  /v1/catalog/products/delete:
    post:
      tags:
        - Products
      summary: Delete products
      description: >
        Delete products with specified `sku` and `source` values
      operationId: deleteProducts
      parameters:
        - $ref: "#/components/parameters/Authorization"
        - $ref: "#/components/parameters/ContentType"
        - $ref: "#/components/parameters/ContentEncoding"
      responses:
        "200":
          $ref: "#/components/responses/AcceptedResponse"
        "400":
          $ref: "#/components/responses/InvalidItemsResponse"
        "401":
          $ref: "#/components/responses/UnauthorizedResponse"
        "403":
          $ref: "#/components/responses/ForbiddenResponse"
        "429":
          $ref: "#/components/responses/TooManyRequestsResponse"
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: "#/components/schemas/FeedProductDelete"
            examples:
              DeleteSimpleProduct:
                summary: Delete product
                description: >
                  Delete a simple product with specified `sku` and `source` values
                value:
                  [
                    {
                      "sku": "red-pants",
                      "source": { "locale": "en-US" }
                    }
                  ]
  /v1/catalog/products/layers:
    post:
      tags:
        - Product Layers
      summary: Create or replace product layers
      description: |
        Create product layers to customize and override base product data for specific contexts, locales, or business requirements.

        Product layers enable you to:
        - Override product attributes for specific markets or channels
        - Provide locale-specific content while maintaining a global base product
        - Create seasonal or promotional variations without duplicating entire product records
        - Implement A/B testing scenarios with different product presentations

        For details on how to use layers with Adobe Commerce Optimizer, see
        [Catalog Layers](https://experienceleague.adobe.com/en/docs/commerce/optimizer/setup/catalog-layer) in the
        Adobe Commerce Optimizer documentation.

        ## Layer behavior and requirements

        **Required fields:**
        - `sku`: Must match an existing base product SKU
        - `source.layer`: Identifies the layer name for organization and retrieval

        **Optional Fields:**
        - `source.locale`: When specified, layer applies only to that locale. When omitted, layer applies globally across all locales
        - All product fields (name, description, images, and so on): Override corresponding base product values

        ## Merging logic

        Product layers use intelligent merging:
        - **Simple fields** (name, description, and so on): Complete replacement of base values
        - **Array fields** (attributes, images, etc.): First-level arrays are merged with base arrays
        - **Nested arrays** (attribute.values, etc.): Complete replacement of nested arrays

        **Example:** Adding a color variant while preserving existing attributes:
        ```json
        {
          "sku": "red-pants",
          "source": {
            "locale": "en-US",
            "layer": "seasonal-colors"
          },
          "attributes": [
            {
              "code": "color",
              "values": ["Crimson Red", "Deep Red"],
              "variantReferenceId": "pants-color-crimson"
            }
          ]
        }
        ```

      operationId: createProductLayers
      parameters:
        - $ref: "#/components/parameters/Authorization"
        - $ref: "#/components/parameters/ContentType"
        - $ref: "#/components/parameters/ContentEncoding"
      responses:
        "200":
          $ref: "#/components/responses/AcceptedResponse"
        "400":
          $ref: "#/components/responses/InvalidItemsResponse"
        "401":
          $ref: "#/components/responses/UnauthorizedResponse"
        "403":
          $ref: "#/components/responses/ForbiddenResponse"
        "429":
          $ref: "#/components/responses/TooManyRequestsResponse"
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: "#/components/schemas/FeedProductLayer"
            examples:
              ProductLayerWithImages:
                summary: Create a seasonal product layer
                description: >
                  Create a product layer that overrides the base product with seasonal branding, 
                  localized content, and updated imagery for the US market.
                value:
                  [
                    {
                      "sku": "red-pants",
                      "source": {
                        "locale": "en-US",
                        "layer": "seasonal-winter-2024"
                      },
                      "name": "Premium Red Winter Pants - Limited Edition",
                      "description": "Stay warm and stylish with our premium red winter pants. Features thermal lining and water-resistant fabric perfect for cold weather adventures.",
                      "shortDescription": "Premium thermal-lined winter pants in warm, classic red",
                      "images": [
                        {
                          "url": "https://cdn.example.com/products/red-pants-winter-2024.jpg",
                          "label": "Premium Red Winter Pants - Front View",
                          "roles": ["BASE", "THUMBNAIL"],
                          "customRoles": ["hero", "seasonal-banner"]
                        }
                      ]
                    }
                  ]
  /v1/catalog/products/layers/delete:
    post:
      tags:
        - Product Layers
      summary: Delete product layers
      description: |
        Remove specific product layers by SKU and source identifiers. This operation permanently deletes
        the layer data while preserving the base product.

        **Use Cases:**
        - Remove expired seasonal or promotional layers
        - Clean up test layers after A/B testing completion
        - Delete locale-specific layers when discontinuing market support
        - Remove outdated customizations

        **Important Notes:**
        - Only the specified layer is deleted; base product and other layers remain intact
        - Both `sku` and `source` (locale + layer) must match exactly for successful deletion

      operationId: deleteProductLayers
      parameters:
        - $ref: "#/components/parameters/Authorization"
        - $ref: "#/components/parameters/ContentType"
        - $ref: "#/components/parameters/ContentEncoding"
      responses:
        "200":
          $ref: "#/components/responses/AcceptedResponse"
        "400":
          $ref: "#/components/responses/InvalidItemsResponse"
        "401":
          $ref: "#/components/responses/UnauthorizedResponse"
        "403":
          $ref: "#/components/responses/ForbiddenResponse"
        "429":
          $ref: "#/components/responses/TooManyRequestsResponse"
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: "#/components/schemas/FeedProductLayerDelete"
            examples:
              DeleteSeasonalLayer:
                summary: Delete seasonal product layer
                description: >
                  Delete a seasonal product layer after the promotion period ends, 
                  reverting the product to its base configuration.
                value:
                  [
                    {
                      "sku": "red-pants",
                      "source": {
                        "locale": "en-US",
                        "layer": "seasonal-winter-2024"
                      }
                    }
                  ]
  /v1/catalog/price-books:
    post:
      tags:
        - Price Books
      summary: Create price books
      description: |
        Create or replace existing price books with support for hierarchical pricing structures.

        <h3>Creating Base Price Books</h3>

        Base price books are the foundation of your pricing hierarchy:

        * **Required Fields**: `priceBookId`, `name`, `currency`
        * **Currency Definition**: Sets the currency for the entire branch of child price books
        * **No Parent**: Base price books cannot reference a parent price book
        * **Unique ID**: Must have a unique `priceBookId` across all price books

        <h3>Creating Child Price Books</h3>

        Child price books inherit from their parent and can extend the hierarchy:

        * **Required Fields**: `priceBookId`, `name`, `parentId`
        * **Parent Reference**: Must reference an existing parent price book
        * **Currency Inheritance**: Automatically inherits currency from parent
        * **Hierarchy Depth**: Can create up to 3 levels of nesting

        <h3>Hierarchy Management</h3>

        * **Parent Assignment**: Once a `parentId` is assigned, it cannot be changed via update operations
        * **Restructuring**: To change parent-child relationships, delete and recreate the child price book
        * **Validation**: The system validates parent references and hierarchy depth limits

        Use the [update price books operation](#operation/updatePriceBooks) to modify existing price book names or base price book currencies.
      operationId: createPriceBooks
      parameters:
        - name: Content-Type
          in: header
          required: true
          schema:
            type: string
            enum: [application/json]
        - name: Authorization
          in: header
          required: true
          schema:
            type: string
            description: Authorization Bearer token
        - name: Content-Encoding
          in: header
          required: false
          schema:
            type: string
            enum: [gzip]
          description: Use this header if the payload is compressed with gzip.
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: "#/components/schemas/FeedPricebook"
            examples:
              FeedWithPricebookInformation:
                summary: Create a hierarchical price book structure
                description: |
                  Create a comprehensive pricing hierarchy with a base price book and multiple child price books.
                  This example demonstrates geographic pricing with regional variations.
                value:
                  [
                    {
                      "priceBookId": "us",
                      "name": "US Base Price Book",
                      "currency": "USD"
                    },
                    {
                      "priceBookId": "us-north",
                      "parentId": "us",
                      "name": "US North Region"
                    },
                    {
                      "priceBookId": "us-south",
                      "parentId": "us",
                      "name": "US South Region"
                    },
                    {
                      "priceBookId": "us-north-east",
                      "parentId": "us-north",
                      "name": "US Northeast Territory"
                    },
                    {
                      "priceBookId": "us-north-west",
                      "parentId": "us-north",
                      "name": "US Northwest Territory"
                    }
                  ]
      responses:
        "200":
          description: All items in the request are accepted for further processing.
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: "#/components/schemas/ProcessFeedResponse"
        "400":
          description: Request rejected. Some of the received items are invalid. Check the "invalidFeedItems" node for specific errors.
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: "#/components/schemas/400ProcessFeedResponse"
        "401":
          description: Unauthorized request. Verify that the Bearer token provided in the `Authorization` header is still valid.
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: "#/components/schemas/401Response"
        "403":
          description: Forbidden request. Verify that the `Authorization` header is present, and that the Bearer token is still valid.
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: "#/components/schemas/403Response"
        "429":
          description: |
            Too many requests. Indicates that a client has exceeded the rate limit of 300 requests per minute.
            Check the `retry-after` header to get the time (in seconds) to wait before sending the next request.
          content:
            text/html;charset=UTF-8:
              schema:
                $ref: "#/components/schemas/429Response"
    patch:
      tags:
        - Price Books
      summary: Update price books
      description: |
        Update existing price books with limitations on hierarchical changes.

        <h3>Updatable Fields</h3>

        * **Name**: Can be updated for both base and child price books
        * **Currency**: Can only be updated for base price books (affects entire hierarchy)
        * **Parent ID**: Cannot be updated - use delete and recreate to change hierarchy

        <h3>Update Restrictions</h3>

        * **Parent Assignment**: Cannot change `parentId` via update operations
        * **Hierarchy Changes**: To restructure the hierarchy, delete and recreate child price books
        * **Currency Inheritance**: Child price books automatically inherit currency changes from parent
        * **Validation**: System validates that `parentId` references exist and hierarchy depth is maintained

        <h3>Update Strategies</h3>

        * **Base Price Books**: Update name and currency as needed
        * **Child Price Books**: Include correct `parentId` in request (will be ignored if different)
        * **Hierarchy Restructuring**: Delete child price book and recreate with new parent reference

        > **Note:** Before submitting an update request, verify that the target entity exists by checking the available price books in [Commerce Optimizer](https://experienceleague.adobe.com/en/docs/commerce/optimizer/setup/pricebooks#view-price-books-in-commerce-optimizer). Update operations do not verify that the entity exists. Requests targeting a nonexistent entity are accepted, but the update has no effect.
      operationId: updatePriceBooks
      parameters:
        - name: Content-Type
          in: header
          required: true
          schema:
            type: string
            enum: [application/json]
        - name: Authorization
          in: header
          required: true
          schema:
            type: string
            description: Authorization Bearer token.
        - name: Content-Encoding
          in: header
          required: false
          schema:
            type: string
            enum: [gzip]
          description: Use this header if the payload is compressed with gzip.
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: "#/components/schemas/FeedPricebook"
            examples:
              FeedWithPriceBookInformation:
                summary: Update existing price books
                description: Update the name of child price book, "dealer-north"
                value:
                  [
                    {
                      "priceBookId": "dealer-north",
                      "parentId": "us",
                      "name": "North dealership"
                    }
                  ]
              ComplexHierarchyExample:
                summary: Create a complex multi-level pricing hierarchy
                description: |
                  Create a comprehensive pricing structure for a global business with multiple regions,
                  customer segments, and sales channels. This demonstrates the full potential of
                  hierarchical price books.
                value:
                  [
                    {
                      "priceBookId": "global",
                      "name": "Global Base Pricing",
                      "currency": "USD"
                    },
                    {
                      "priceBookId": "us-retail",
                      "parentId": "global",
                      "name": "US Retail Channel"
                    },
                    {
                      "priceBookId": "us-online",
                      "parentId": "global",
                      "name": "US Online Channel"
                    },
                    {
                      "priceBookId": "us-retail-premium",
                      "parentId": "us-retail",
                      "name": "US Retail Premium Customers"
                    },
                    {
                      "priceBookId": "us-retail-standard",
                      "parentId": "us-retail",
                      "name": "US Retail Standard Customers"
                    },
                    {
                      "priceBookId": "us-online-vip",
                      "parentId": "us-online",
                      "name": "US Online VIP Members"
                    },
                    {
                      "priceBookId": "us-online-regular",
                      "parentId": "us-online",
                      "name": "US Online Regular Customers"
                    }
                  ]
      responses:
        "200":
          description: All items in the request are accepted for further processing.
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: "#/components/schemas/ProcessFeedResponse"
        "400":
          description: Request rejected. Some of the received items are invalid. Check the `invalidFeedItems` node for specific errors.
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: "#/components/schemas/400ProcessFeedResponse"
        "401":
          description: Unauthorized request. Verify that the Bearer token provided in the `Authorization` header is still valid.
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: "#/components/schemas/401Response"
        "403":
          description: Forbidden request. Verify that the `Authorization` header is present, and that the Bearer token is still valid.
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: "#/components/schemas/403Response"
        "429":
          description: |
            Too many requests. Indicates that a client has exceeded the rate limit of 300 requests per minute.
            Check the `retry-after` header to get the time (in seconds) to wait before sending the next request.
          content:
            text/html;charset=UTF-8:
              schema:
                $ref: "#/components/schemas/429Response"
  /v1/catalog/price-books/delete:
    post:
      tags:
        - Price Books
      summary: Delete price books
      description: |
        Delete price books and their associated pricing data with cascading effects on the hierarchy.

        <h3>Cascading Deletion</h3>

        When you delete a price book:
        * **Child Price Books**: All child price books in the hierarchy are automatically deleted
        * **Associated Prices**: All prices assigned to the deleted price book and its children are removed
        * **Hierarchy Impact**: The entire branch below the deleted price book is removed

        <h3>Deletion Scenarios</h3>

        * **Base Price Book**: Deletes entire pricing hierarchy and all associated prices
        * **Child Price Book**: Deletes the specific price book and its children, but preserves sibling price books
        * **Leaf Price Book**: Deletes only the specified price book and its associated prices

        <h3>Recovery Options</h3>

        If a price book is deleted by mistake:
        * **Time Window**: You have up to one week to restore deleted price books
        * **Restoration Method**: Recreate the top-level parent price book using the original create payload
        * **State Recovery**: Price books and prices are restored to their state when deleted
        * **Hierarchy Reconstruction**: The entire hierarchy is rebuilt from the restoration payload

        <h3>Best Practices</h3>

        * **Backup Strategy**: Keep copies of price book configurations for recovery
        * **Validation**: Verify hierarchy structure before deletion
        * **Impact Assessment**: Review associated prices before deleting price books
      operationId: deletePriceBooks
      parameters:
        - name: Content-Type
          in: header
          required: true
          schema:
            type: string
            enum: [application/json]
        - name: Authorization
          in: header
          required: true
          schema:
            type: string
            description: Authorization Bearer token.
        - name: Content-Encoding
          in: header
          required: false
          schema:
            type: string
            enum: [gzip]
          description: Use this header if the payload is compressed with gzip.
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: "#/components/schemas/FeedPriceBookDelete"
            examples:
              DeleteExistingPricebook:
                summary: Delete price book "dealer-north"
                description: Delete the "dealer-north" price book. All prices assigned to this price book are also deleted.
                value: [{ "priceBookId": "dealer-north" }]
      responses:
        "200":
          description: All items in the request are accepted for further processing.
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: "#/components/schemas/ProcessFeedResponse"
        "400":
          description: Request rejected. Some of the received items are invalid. Check the "invalidFeedItems" node for specific errors.
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: "#/components/schemas/400ProcessFeedResponse"
        "401":
          description: Unauthorized request. Verify that the Bearer token provided in the `Authorization` header is still valid.
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: "#/components/schemas/401Response"
        "403":
          description: Forbidden request. Verify that the `Authorization` header is present, and that the Bearer token is still valid.
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: "#/components/schemas/403Response"
        "429":
          description: |
            Too many requests. Indicates that a client has exceeded the rate limit of 300 requests per minute.
            Check the `retry-after` header to get the time (in seconds) to wait before sending the next request.
          content:
            text/html;charset=UTF-8:
              schema:
                $ref: "#/components/schemas/429Response"
  /v1/catalog/products/prices:
    post:
      tags:
        - Prices
      summary: Create prices
      description: |
        Create or replace existing product prices with support for regular pricing, discounts, and tiered pricing.

        <h3>Pricing structure</h3>

        Each price record can include:

        * **Regular Price** - The base price for the product SKU
        * **Discounts** - Percentage or fixed amount discounts applied to the regular price
        * **Tiered Pricing** - Quantity-based pricing for bulk purchases

        <h3>Discount configuration</h3>

        Discounts can be configured in two ways:

        * **Fixed Amount Discounts** - Use `price` field to specify a fixed discount amount (e.g., 10.00 for $10 off)
        * **Percentage Discounts** - Use `percentage` field to specify a discount percentage (e.g., 20 for 20% off)

        Each discount requires a unique `code` identifier to distinguish between different discount types.

        <h3>Tiered pricing</h3>

        Tiered pricing offers different prices based on purchase quantity:

        * **Tier Fixed Prices** - Use `price` field with `qty` to specify quantity-based fixed prices
        * **Tier Percentage Discounts** - Use `percentage` field with `qty` to specify quantity-based percentage discounts

        Tier quantities must be greater than 1.

        <h3>Pricing for configurable products</h3>
        Because configurable product price is calculated based on the price of the selected product variant, you don't need to send the price
        data for configurable product SKUs. Sending price data for these SKUs can cause incorrect price calculations.

      operationId: createPrices
      parameters:
        - $ref: "#/components/parameters/Authorization"
        - $ref: "#/components/parameters/ContentType"
        - $ref: "#/components/parameters/ContentEncoding"
      responses:
        "200":
          $ref: "#/components/responses/AcceptedResponse"
        "400":
          $ref: "#/components/responses/InvalidItemsResponse"
        "401":
          $ref: "#/components/responses/UnauthorizedResponse"
        "403":
          $ref: "#/components/responses/ForbiddenResponse"
        "429":
          $ref: "#/components/responses/TooManyRequestsResponse"
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: "#/components/schemas/FeedPrices"
            examples:
              FeedWithNewProductPrice:
                summary: Add product price information with discounts and tiered pricing
                description: |
                  Add product price information to the catalog data with examples of regular pricing,
                  percentage discounts, and tiered pricing for bulk purchases.
                value:
                  [
                    {
                      "sku": "red-pants",
                      "priceBookId": "us",
                      "regular": 20
                    },
                    {
                      "sku": "red-pants",
                      "priceBookId": "dealer-north",
                      "regular": 19.9,
                      "discounts": [
                        {
                          "code": "seasonal_sale",
                          "percentage": 10
                        },
                        {
                          "code": "loyalty_discount",
                          "price": 2.00
                        }
                      ],
                      "tierPrices": [
                        {
                          "qty": 5,
                          "percentage": 15
                        },
                        {
                          "qty": 10,
                          "price": 15.00
                        }
                      ]
                    }
                  ]
              FeedWithComplexPricing:
                summary: Complex pricing with multiple discount types and tier levels
                description: |
                  Example showing complex pricing scenarios with multiple discount types,
                  tiered pricing for different quantity levels, and geographic pricing variations.
                value:
                  [
                    {
                      "sku": "premium-watch",
                      "priceBookId": "us-premium",
                      "regular": 299.99,
                      "discounts": [
                        {
                          "code": "holiday_sale",
                          "percentage": 15
                        },
                        {
                          "code": "vip_member",
                          "price": 25.00
                        }
                      ],
                      "tierPrices": [
                        {
                          "qty": 2,
                          "percentage": 10
                        },
                        {
                          "qty": 5,
                          "percentage": 20
                        },
                        {
                          "qty": 10,
                          "price": 250.00
                        }
                      ]
                    },
                    {
                      "sku": "premium-watch",
                      "priceBookId": "us-wholesale",
                      "regular": 250.00,
                      "discounts": [
                        {
                          "code": "bulk_discount",
                          "percentage": 25
                        }
                      ],
                      "tierPrices": [
                        {
                          "qty": 10,
                          "price": 200.00
                        },
                        {
                          "qty": 25,
                          "price": 175.00
                        },
                        {
                          "qty": 50,
                          "percentage": 40
                        }
                      ]
                    }
                  ]

    patch:
      tags:
        - Prices
      summary: Update prices
      description: |
        Change existing product prices, discounts, and tiered pricing.

        When the update is processed, the merge strategy is used to apply changes to `scalar` and `object` type fields.

        For `array` type fields, a new value can be appended to the existing list. For an object list, you can update a specific object by matching on a key field. The following fields are supported:
        * `discounts` - match on `code`
        * `tierPrices` - match on `qty`

        <h3>Update strategies</h3>

        * **Regular Price** - Updated using merge strategy
        * **Discounts Array** - Updated using the append or merge strategy
        * **Tiered Pricing Array** - Updated using the append or merge strategy

        <h3>Discount and tier pricing updates</h3>

        When updating discounts or tiered pricing:

        * Include all desired discounts/tiers in the array
        * The entire array replaces the existing configuration
        * To remove all discounts/tiers, send an empty array
        * To add new discounts/tiers, include both existing and new items

        <h3>Best practices</h3>

        * Always include the complete array of discounts/tiers when updating
        * Use descriptive discount codes for easier management
        * Ensure tier quantities are in ascending order
        * Test updates in a development environment first

        > **Note:** Before submitting an update request, verify that the target entity exists using the [products GraphQL query](https://developer.adobe.com/commerce/services/includes/autogenerated/merchandising-api#products) to check the prices assigned to the product SKU. Update operations do not verify that the entity exists. Requests targeting a nonexistent entity are accepted, but the update has no effect.
      operationId: updatePrices
      parameters:
        - $ref: "#/components/parameters/Authorization"
        - $ref: "#/components/parameters/ContentType"
        - $ref: "#/components/parameters/ContentEncoding"
      responses:
        "200":
          $ref: "#/components/responses/AcceptedResponse"
        "400":
          $ref: "#/components/responses/InvalidItemsResponse"
        "401":
          $ref: "#/components/responses/UnauthorizedResponse"
        "403":
          $ref: "#/components/responses/ForbiddenResponse"
        "429":
          $ref: "#/components/responses/TooManyRequestsResponse"
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: "#/components/schemas/FeedPricesUpdate"
            examples:
              FeedWithProductPricesInformation:
                summary: Update product prices with enhanced discounts and tiered pricing
                description: |
                  Update existing product prices for the given SKU ("red-pants") and price book id ("dealer-north").
                  This example shows how to update both discounts and tiered pricing simultaneously:
                  * **discounts**: Update the existing `seasonal_sale` discount and add a new `holiday_sale` discount
                  * **tierPrices**: Update the existing  percentage discount for quantity 5 and add a new discount for quantity 20
                value:
                  [
                    {
                      "sku": "red-pants",
                      "priceBookId": "dealer-north",
                      "discounts": [
                        {
                          "code": "seasonal_sale",
                          "percentage": 30
                        },
                        {
                          "code": "holiday_sale",
                          "price": 5.00
                        }
                      ],
                      "tierPrices": [
                        {
                          "qty": 5,
                          "percentage": 20
                        },
                        {
                          "qty": 20,
                          "price": 13
                        }
                      ]
                    }
                  ]
  /v1/catalog/products/prices/delete:
    post:
      tags:
        - Prices
      summary: Delete prices
      description: >
        Delete existing product prices

      operationId: deletePrices
      parameters:
        - $ref: "#/components/parameters/Authorization"
        - $ref: "#/components/parameters/ContentType"
        - $ref: "#/components/parameters/ContentEncoding"
      responses:
        "200":
          $ref: "#/components/responses/AcceptedResponse"
        "400":
          $ref: "#/components/responses/InvalidItemsResponse"
        "401":
          $ref: "#/components/responses/UnauthorizedResponse"
        "403":
          $ref: "#/components/responses/ForbiddenResponse"
        "429":
          $ref: "#/components/responses/TooManyRequestsResponse"
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: "#/components/schemas/FeedPricesDelete"
            examples:
              FeedWithProductPricesInformation:
                summary: Delete product prices
                description: >
                  Delete the existing product prices information
                value: [{ "sku": "red-pants", "priceBookId": "dealer-north" }]

components:
  responses:
    AcceptedResponse:
      x-summary: All items accepted
      description: |
        All items accepted and will be processed asynchronously
      content:
        application/json;charset=UTF-8:
          schema:
            $ref: "#/components/schemas/ProcessFeedResponse"

    InvalidItemsResponse:
      x-summary: Request rejected
      description: |
        Some of the received items are invalid. Check the "message" and "errors" fields for details.

        Common causes of validation errors include:

        * **Invalid SKU**: SKU does not exist in the catalog
        * **Invalid Price Book**: Price book ID does not exist
        * **Invalid Discount Code**: Duplicate or invalid discount codes
        * **Invalid Tier Quantities**: Quantities not in ascending order or less than 2
        * **Configurable Product Price**: Attempting to set price for configurable product SKU
        * **Invalid Price Format**: Non-numeric or negative price values
        * **Incorrect Category Slug**: Invalid category slug format
        * **Incorrect hierarchy configuration**: Misconfiguration of price book parent-child relationship
      content:
        application/json;charset=UTF-8:
          schema:
            $ref: "#/components/schemas/400ProcessFeedResponse"
    UnauthorizedResponse:
      x-summary: Unauthorized request
      description: |
        Verify that the Bearer token provided in the `Authorization` header is still valid.
      content:
        application/json;charset=UTF-8:
          schema:
            $ref: "#/components/schemas/401Response"
    ForbiddenResponse:
      x-summary: Forbidden request
      description: |
        Verify that the `Authorization` header is present, and that the Bearer token is still valid.
      content:
        application/json;charset=UTF-8:
          schema:
            $ref: "#/components/schemas/403Response"
    TooManyRequestsResponse:
      x-summary: Too many requests
      description: |
        Indicates that a client has exceeded the rate limit of 300 requests per minute.
        Check the `retry-after` header to get the time (in seconds) to wait before sending the next request.
      content:
        text/html;charset=UTF-8:
          schema:
            $ref: "#/components/schemas/429Response"
  parameters:
    Authorization:
      name: Authorization
      in: header
      required: true
      schema:
        type: string
        description: Authorization Bearer token
    ContentType:
      name: Content-Type
      in: header
      required: true
      schema:
        type: string
        enum: [application/json]
        default: application/json
    ContentEncoding:
      name: Content-Encoding
      in: header
      required: false
      schema:
        type: string
        enum: [gzip]
      description: Use this header if the payload is compressed with gzip.
  schemas:
    FeedItemFailedValidationResult:
      title: FeedItemFailedValidationResult
      type: object
      properties:
        code:
          type: string
          description: Code name of invalid field.
        itemIndex:
          type: integer
          format: int32
          description: Reference to the line item with an invalid payload. The line count begins at 0.
        message:
          type: string
          description: Error description
        value:
          type: string
          description: Original value passed in the request.
    FeedProductMetadata:
      title: Create or update product metadata attribute
      description: Metadata information for a product attribute.
      required:
        - code
        - source
        - label
        - dataType
      type: object
      properties:
        code:
          type: string
          description: Attribute code
        source:
          $ref: "#/components/schemas/Source"
        visibleIn:
          type: array
          description: |
            Determines how the attribute is used on the storefront.
            * `PRODUCT_DETAIL`: Product attribute is visible on the Product Detail Page.
            * `PRODUCT_LISTING`: Product attribute is visible on Product Listing Page.
            * `SEARCH_RESULTS`: Product attribute is visible on Search Results Page.
            * `PRODUCT_COMPARE`: Product attribute is visible on Product Compare Page.
          items:
            enum:
              - PRODUCT_DETAIL
              - PRODUCT_LISTING
              - SEARCH_RESULTS
              - PRODUCT_COMPARE
        label:
          type: string
          description: Label for the attribute that is displayed in user interfaces.
          example: Attribute Name
        dataType:
          type: string
          description: Data type
          example: TEXT
          enum:
            - TEXT
            - DECIMAL
            - INTEGER
            - BOOLEAN
        filterable:
          type: boolean
          description: Indicates whether the attribute can be used to filter products.
          example: true
        sortable:
          type: boolean
          description: Indicates whether the attribute can be used to sort products.
          example: true
        searchable:
          type: boolean
          description: Indicates whether the attribute value can be used in search queries to filter results.
          example: true
        searchWeight:
          type: number
          description: |
            The weight associated with a searchable attribute.
            Attributes with a greater weight are returned before attributes with a lower weight.
          format: float
        searchTypes:
          type: array
          description: >
            Search types associated with this attribute, for example: `autocomplete`, `starts_with`, and so on.
          items:
            type: string
            enum:
              - AUTOCOMPLETE
              - CONTAINS
              - STARTS_WITH
    FeedProductMetadataUpdate:
      title: Update product metadata attribute
      description: Metadata information for a product attribute.
      required:
        - code
        - source
      type: object
      properties:
        code:
          type: string
          description: Attribute code
        source:
          $ref: "#/components/schemas/Source"
        visibleIn:
          type: array
          description: |
            Determines how the attribute is used on the storefront.
            * `PRODUCT_DETAIL`: Product attribute is visible on the Product Detail Page.
            * `PRODUCT_LISTING`: Product attribute is visible on Product Listing Page.
            * `SEARCH_RESULTS`: Product attribute is visible on Search Results Page.
            * `PRODUCT_COMPARE`: Product attribute is visible on Product Compare Page.
          items:
            enum:
              - PRODUCT_DETAIL
              - PRODUCT_LISTING
              - SEARCH_RESULTS
              - PRODUCT_COMPARE
        label:
          type: string
          description: Label for the attribute that is displayed in user interfaces.
          example: Attribute Name
        dataType:
          type: string
          description: Data type
          example: TEXT
          enum:
            - TEXT
            - DECIMAL
            - INTEGER
            - BOOLEAN
        filterable:
          type: boolean
          description: Indicates whether the attribute can be used to filter products.
          example: true
        sortable:
          type: boolean
          description: Indicates whether the attribute can be used to sort products.
          example: true
        searchable:
          type: boolean
          description: Indicates whether the attribute value can be used in search queries to filter results.
          example: true
        searchWeight:
          type: number
          description: |
            The weight associated with a searchable attribute.
            Attributes with a greater weight are returned before attributes with a lower weight.
          format: float
        searchTypes:
          type: array
          description: >
            Search types associated with this attribute, for example: `autocomplete`, `starts_with`, and so on.
          items:
            type: string
            enum:
              - AUTOCOMPLETE
              - CONTAINS
              - STARTS_WITH
    FeedProductMetadataDelete:
      title: Delete product metadata attribute
      description: Delete metadata information for a product attribute.
      required:
        - code
        - source
      type: object
      properties:
        code:
          type: string
          description: Attribute code
        source:
          $ref: "#/components/schemas/Source"
    FeedCategoryMetadata:
      title: Create or update category metadata attribute
      description: Metadata information for a category attribute.
      required:
        - code
        - source
        - label
        - dataType
      type: object
      properties:
        code:
          type: string
          description: Attribute code
        source:
          $ref: "#/components/schemas/Source"
        label:
          type: string
          description: Label for the attribute that is displayed in user interfaces.
          example: Attribute Name
        dataType:
          type: string
          description: Data type
          example: TEXT
          enum:
            - TEXT
            - DECIMAL
            - INTEGER
            - BOOLEAN
    FeedCategoryMetadataUpdate:
      title: Update category metadata attribute
      description: Metadata information for a category attribute.
      required:
        - code
        - source
      type: object
      properties:
        code:
          type: string
          description: Attribute code
        source:
          $ref: "#/components/schemas/Source"
        label:
          type: string
          description: Label for the attribute that is displayed in user interfaces.
          example: Attribute Name
        dataType:
          type: string
          description: Data type
          example: TEXT
          enum:
            - TEXT
            - DECIMAL
            - INTEGER
            - BOOLEAN
    FeedCategoryMetadataDelete:
      title: Delete category metadata attribute
      description: Delete metadata information for a category attribute.
      required:
        - code
        - source
      type: object
      properties:
        code:
          type: string
          description: Attribute code
        source:
          $ref: "#/components/schemas/Source"
    FeedCategory:
      title: FeedCategory
      description: Category information for organizing products with hierarchical structure and localization support.
      required:
        - slug
        - source
        - name
      type: object
      properties:
        slug:
          type: string
          minLength: 1
          maxLength: 1024
          pattern: "^[a-z0-9-]+(?:\\/[a-z0-9-]+)*$"
          description: |
            Category slug using hierarchical format with forward slashes to represent parent-child relationships.
            String can contain only lowercase letters, numbers, and hyphens.
            Examples: 'men', 'men/clothing', 'men/clothing/pants'
          example: "men/clothing/pants"
        source:
          $ref: "#/components/schemas/Source"
        name:
          type: string
          minLength: 1
          maxLength: 128
          description: Display name of the category
          example: "Men's Pants"
        description:
          type: string
          nullable: true
          description: Full-text description of the category.
          example: "Men's clothing, shoes, and accessories"
        families:
          type: array
          nullable: true
          items:
            type: string
          description: |
            Optional array of product family identifiers that this category is associated with.
            Used for enhanced product organization and filtering.
          example: ["apparel", "clothing"]
        position:
          type: integer
          format: int32
          description: Sort order for the category
        metaTags:
          $ref: "#/components/schemas/CategoryMetaAttribute"
        attributes:
          type: array
          description: A list of category attributes.
          items:
            $ref: "#/components/schemas/CategoryAttribute"
        images:
          type: array
          description: A list of category images.
          items:
            $ref: "#/components/schemas/CategoryImage"
      additionalProperties: false
    FeedCategoryUpdate:
      title: FeedCategoryUpdate
      description: Category information for updating existing categories.
      required:
        - slug
        - source
      type: object
      properties:
        slug:
          type: string
          minLength: 1
          maxLength: 1024
          pattern: "^[a-z0-9-]+(?:\\/[a-z0-9-]+)*$"
          description: |
            Category slug using hierarchical format with forward slashes to represent parent-child relationships.
            String can contain only lowercase letters, numbers, and hyphens.
            Examples: 'men', 'men/clothing', 'men/clothing/pants'
          example: "men/clothing/pants"
        source:
          $ref: "#/components/schemas/Source"
        name:
          type: string
          minLength: 1
          maxLength: 128
          description: Display name of the category
          example: "Men's Pants"
        description:
          type: string
          nullable: true
          description: Full-text description of the category.
          example: "Men's clothing, shoes, and accessories"
        families:
          type: array
          nullable: true
          items:
            type: string
          description: |
            Optional array of product family identifiers that this category is associated with.
            Used for enhanced product organization and filtering. For example, for a clothing category,
            you can associate it with the "apparel" family.
            Note: This field uses the replace strategy to replace the entire array with the new values.
          example: ["apparel", "clothing"]
        position:
          type: integer
          format: int32
          description: Sort order for the category
        metaTags:
          $ref: "#/components/schemas/CategoryMetaAttribute"
        attributes:
          type: array
          description: A list of category attributes.
          items:
            $ref: "#/components/schemas/CategoryAttribute"
        images:
          type: array
          description: A list of category images.
          items:
            $ref: "#/components/schemas/CategoryImage"
      additionalProperties: false
    FeedCategoryDelete:
      title: Delete category
      description: Delete category information for removing categories from the catalog.
      required:
        - slug
        - source
      type: object
      properties:
        slug:
          type: string
          minLength: 1
          maxLength: 1024
          pattern: "^[a-z0-9-]+(?:\\/[a-z0-9-]+)*$"
          description: |
            Category slug using hierarchical format with forward slashes to represent parent-child relationships.
            Must use only lowercase letters, numbers, and hyphens.
            Examples: 'men', 'men/clothing', 'men/clothing/pants'
          example: "men/clothing/pants"
        source:
          $ref: "#/components/schemas/Source"
      additionalProperties: false
    FeedProduct:
      title: Catalog Product payload
      type: object
      required:
        - sku
        - source
        - name
        - slug
        - status
      properties:
        sku:
          type: string
          description: SKU (Stock Keeping Unit) is a unique identifier for a product.
          example: MH01
        source:
          $ref: "#/components/schemas/Source"
        name:
          type: string
          description: Product name
          example: Kangaroo Hoodie
        slug:
          type: string
          description: The URL key for the product.
          example: kangaroo-hoodie.html
        description:
          type: string
          nullable: true
          description: The main description for the product
          example: A kangaroo hoodie for all seasons
        shortDescription:
          type: string
          nullable: true
          description: A short description of the product
          example: A hoodie for all seasons with a kangaroo pocket
        status:
          type: string
          description: |
            Indicates whether the product is visible on the storefront.
            The value is "Enabled" if it is visible, and "Disabled" if it is not visible.
          example: ENABLED
          enum:
            - ENABLED
            - DISABLED
        visibleIn:
          type: array
          description: |
            Storefront area where the product is visible. An empty list means that it is not visible as a stand alone product.
            * `CATALOG`: Product is visible on Product Listing Page and Product Detail Page.
            * `SEARCH`: Product is visible on Search Results Page and Product Detail Page.
          example: [CATALOG]
          items:
            enum:
              - CATALOG
              - SEARCH
        metaTags:
          $ref: "#/components/schemas/ProductMetaAttribute"
        attributes:
          type: array
          description: A list of product attributes.
          items:
            $ref: "#/components/schemas/ProductAttribute"
        images:
          type: array
          description: A list of product images.
          items:
            $ref: "#/components/schemas/ProductImage"
        links:
          type: array
          description: A list of linked SKUs.
          items:
            $ref: "#/components/schemas/ProductLink"
        routes:
          type: array
          description: A list of product routes.
          items:
            $ref: "#/components/schemas/ProductRoutes"
        configurations:
          type: array
          description: Composite products, such as configurable products, must provide a list of product options that a shopper can select (for example, "color", "size", etc.).
          items:
            $ref: "#/components/schemas/ProductConfiguration"
        bundles:
          type: array
          description: Composite products, such as bundle products, must include a list of individual products that are part of the bundle, organized into groups (for example, "shirts", "pants", "accessories").
          items:
            $ref: "#/components/schemas/ProductBundle"
        externalIds:
          type: array
          description: A list of external IDs for the product.
          items:
            $ref: "#/components/schemas/ProductExternalId"
    FeedProductUpdate:
      title: Catalog Product payload
      type: object
      required:
        - sku
        - source
      properties:
        sku:
          type: string
          description: SKU (Stock Keeping Unit) is a unique identifier for a product.
          example: MH01
        source:
          $ref: "#/components/schemas/Source"
        name:
          type: string
          description: Product name
          example: Kangaroo Hoodie
        slug:
          type: string
          description: The URL key for the product.
          example: kangaroo-hoodie.html
        description:
          type: string
          nullable: true
          description: The main description for the product
          example: A kangaroo hoodie for all seasons
        shortDescription:
          type: string
          nullable: true
          description: A short description of the product
          example: A hoodie for all seasons with a kangaroo pocket
        status:
          type: string
          description: |
            Indicates whether the product is visible on the storefront.
            The value is "Enabled" if it is visible, and "Disabled" if it is not visible.
          example: ENABLED
          enum:
            - ENABLED
            - DISABLED
        visibleIn:
          type: array
          description: |
            Storefront area where the product is visible. An empty list means that it is not visible as a stand alone product.
            * `CATALOG`: Product is visible on Product Listing Page and Product Detail Page.
            * `SEARCH`: Product is visible on Search Results Page and Product Detail Page.
          example: [CATALOG]
          items:
            enum:
              - CATALOG
              - SEARCH
        metaTags:
          $ref: "#/components/schemas/ProductMetaAttribute"
        attributes:
          type: array
          description: A list of product attributes.
          items:
            $ref: "#/components/schemas/ProductAttribute"
        images:
          type: array
          description: A list of product images.
          items:
            $ref: "#/components/schemas/ProductImage"
        links:
          type: array
          description: |
            A list of linked SKUs. For product variants, this is a required field that establishes a link between a product variant and the corresponding configurable product.
            `VARIANT_OF` link type must be specified to establish a connection to the configurable product SKU.
          items:
            $ref: "#/components/schemas/ProductLink"
        routes:
          type: array
          description: A list of product routes.
          items:
            $ref: "#/components/schemas/ProductRoutes"
        configurations:
          type: array
          description: Composite products, such as configurable products, must provide a list of product options that a shopper can select (for example, "color", "size", etc.).
          items:
            $ref: "#/components/schemas/ProductConfiguration"
        bundles:
          type: array
          description: Composite products, such as bundle products, must include a list of individual products that are part of the bundle, organized into groups (for example, "shirts", "pants", "accessories").
          items:
            $ref: "#/components/schemas/ProductBundle"
        externalIds:
          type: array
          description: A list of external IDs for the product.
          items:
            $ref: "#/components/schemas/ProductExternalId"
    FeedProductDelete:
      title: Catalog Product delete payload
      type: object
      required:
        - sku
        - source
      properties:
        sku:
          type: string
          description: Product unique identifier
          example: MH01
        source:
          $ref: "#/components/schemas/Source"
    FeedProductLayer:
      title: Catalog Product Layer payload
      type: object
      required:
        - sku
        - source
      properties:
        sku:
          type: string
          description: SKU (Stock Keeping Unit) that uniquely identifies the base product this layer will modify. Must match an existing product SKU in the catalog.
          example: red-pants
        source:
          $ref: "#/components/schemas/SourceLayer"
        name:
          type: string
          description: Product display name that will override the base product name. Use for localized names, seasonal branding, or promotional titles.
          example: Premium Red Winter Pants - Limited Edition
        description:
          type: string
          nullable: true
          description: Detailed product description that replaces the base product description. Use for localized content, seasonal messaging, or enhanced marketing copy.
          example: Stay warm and stylish with our premium red winter pants. Features thermal lining and water-resistant fabric perfect for cold weather adventures.
        shortDescription:
          type: string
          nullable: true
          description: Brief product summary that appears in product listings and search results. Override for concise, layer-specific messaging.
          example: Premium thermal-lined winter pants in classic red
        metaTags:
          $ref: "#/components/schemas/ProductMetaAttribute"
        attributes:
          type: array
          description: Product attributes that will be merged with base product attributes. Use to add layer-specific variants, localized values, or seasonal properties.
          items:
            $ref: "#/components/schemas/ProductAttribute"
        images:
          type: array
          description: Product images that will be merged with base product images. Use to add seasonal imagery, locale-specific photos, or promotional visuals.
          items:
            $ref: "#/components/schemas/ProductImage"
        links:
          type: array
          description: Related product SKUs that will be merged with base product links. Use to add seasonal recommendations, locale-specific cross-sells, or promotional bundles.
          items:
            $ref: "#/components/schemas/ProductLink"
        externalIds:
          type: array
          description: External system identifiers that will be merged with base product external IDs. Use to add layer-specific tracking codes, campaign IDs, or integration references.
          items:
            $ref: "#/components/schemas/ProductExternalId"
    FeedProductLayerDelete:
      title: Catalog Product Layer delete payload
      type: object
      required:
        - sku
        - source
      properties:
        sku:
          type: string
          description: SKU (Stock Keeping Unit) that identifies the base product containing the layer to delete. Must match an existing product SKU in the catalog.
          example: red-pants
        source:
          $ref: "#/components/schemas/SourceLayer"
    FeedPricebook:
      title: FeedPricebook
      description: |
        Price book information supporting hierarchical pricing structures. Use base price books to define currency
        and create child price books for specific pricing scenarios.
      oneOf:
        - $ref: '#/components/schemas/PriceBookBase'
        - $ref: '#/components/schemas/PriceBookChild'
    PriceBookBase:
      title: Base price book
      type: object
      required: [priceBookId, name, currency]
      properties:
        priceBookId:
          type: string
          description: | 
            Unique identifier for the base price book. Must be unique across all price books.
            Used to reference this price book in child price books and pricing data.
          minLength: 1
          maxLength: 64
          example: "us-base"
        name:
          type: string
          description: |
             Human-readable name for the price book. Used for display and identification purposes.
          minLength: 1
          example: "US Base Pricing"
        currency:
          type: string
          description: |
            Currency code that applies to this price book and all its child price books in ISO format.
            Child price books inherit this currency and cannot override it.
          minLength: 1
          maxLength: 5
          example: "USD"
    PriceBookChild:
      title: Child price book
      description: |
         Nested price book that inherits currency from its parent and can extend the pricing hierarchy.
         Child price books can have up to 3 levels of nesting from the base price book.
      type: object
      required: [priceBookId, name, parentId]
      properties:
        priceBookId:
          type: string
          description: |
            Unique identifier for the child price book. Must be unique across all price books.
            Used to reference this price book in pricing data and potential child price books.
          minLength: 1
          maxLength: 64
          example: "us-retail"
        name:
          type: string
          description: |
            Human-readable name for the child price book. Used for display and identification purposes.
          minLength: 1
          example: "US Retail Channel"
        parentId:
          type: string
          description: |
             Reference to the parent price book ID. Must reference an existing price book.
             Determines the currency inheritance and hierarchy level.
          minLength: 1
          maxLength: 64
    FeedPriceBookDelete:
      title: FeedPriceBookDelete
      description: Price book information
      required:
        - priceBookId
      type: object
      properties:
        priceBookId:
          type: string
          description: Price book id
    FeedPrices:
      title: FeedPrices
      description: |
        Product price information with support for regular pricing, discounts, and tiered pricing.
        Each price record must reference an existing price book and can include multiple discount types
        and tiered pricing levels for different quantity thresholds.
      required:
        - sku
        - priceBookId
        - regular
      type: object
      properties:
        sku:
          type: string
          description: |
            Product SKU identifier. Must match an existing product in the catalog.
            For configurable products, use the variant SKU, not the parent SKU.
          example: "red-pants-xl"
        priceBookId:
          type: string
          description: |
            Price book identifier. Must reference an existing price book.
            Prices referencing non-existing price books are ignored.
          example: "us-retail"
        regular:
          type: number
          format: float
          description: |
            Base price for the product SKU in the specified price book.
            This is the price before any discounts or tiered pricing are applied.
          example: 29.99
        discounts:
          type: array
          description: |
            Array of active discounts applied to the regular price.
            Each discount requires a unique code identifier.
            Supports both percentage and fixed amount discounts.
          items:
            anyOf:
              - $ref: "#/components/schemas/DiscountsFinalPrice"
              - $ref: "#/components/schemas/DiscountsPercentage"
          example:
            - code: "seasonal_sale"
              percentage: 15
            - code: "loyalty_discount"
              price: 5.00
        tierPrices:
          type: array
          description: |
            Array of tiered pricing for quantity-based discounts.
            Quantities must be greater than 1. Supports both percentage and fixed price tiers.
          items:
            anyOf:
              - $ref: "#/components/schemas/TierFinalPrice"
              - $ref: "#/components/schemas/TierPercentage"
          example:
            - qty: 5
              percentage: 10
            - qty: 10
              price: 25.00
    FeedPricesUpdate:
      title: FeedPrices
      description: Product price information.
      required:
        - sku
        - priceBookId
      type: object
      properties:
        sku:
          type: string
          description: Product SKU
        priceBookId:
          type: string
          description: Price book id
        regular:
          type: number
          format: float
          description: Regular price
        discounts:
          type: array
          description: Active discounts
          items:
            anyOf:
              - $ref: "#/components/schemas/DiscountsFinalPrice"
              - $ref: "#/components/schemas/DiscountsPercentage"
        tierPrices:
          type: array
          description: Tier prices for quantities greater-than one
          items:
            anyOf:
              - $ref: "#/components/schemas/TierFinalPrice"
              - $ref: "#/components/schemas/TierPercentage"
    FeedPricesDelete:
      title: FeedPricesDelete
      description: Delete product price information.
      required:
        - sku
        - priceBookId
      type: object
      properties:
        sku:
          type: string
          description: Product SKU
        priceBookId:
          type: string
          description: Price book id
    DiscountsFinalPrice:
      title: Fixed Amount Discount
      description: |
        Fixed amount discount that reduces the regular price by a specific monetary value.
        Example: $100 regular price with a $10 fixed discount results in $90 final price.
      type: object
      required:
        - code
        - price
      properties:
        code:
          type: string
          description: |
            Unique identifier for the discount. Must be unique within the price record.
            Use descriptive codes for easier management (e.g., "loyalty_discount", "holiday_sale").
          example: "loyalty_discount"
        price:
          type: number
          format: float
          description: |
            Fixed discount amount in the same currency as the price book.
            Must be a positive number less than the regular price.
          example: 10.00
    DiscountsPercentage:
      title: Percentage Discount
      description: |
        Percentage discount that reduces the regular price by a specified percentage.
        Example: $100 regular price with a 20% discount results in $80 final price.
      type: object
      required:
        - code
        - percentage
      properties:
        code:
          type: string
          description: |
            Unique identifier for the discount. Must be unique within the price record.
            Use descriptive codes for easier management (e.g., "seasonal_sale", "vip_member").
          example: "seasonal_sale"
        percentage:
          type: number
          format: float
          description: |
            Discount percentage as a positive number. Valid range is 0.01 to 99.99 (1% to 99.99%).
          example: 15.5
    TierFinalPrice:
      title: Tier Final Price
      description: |
        Final price offered for bulk purchases at a specific quantity threshold.
        Example: $100 regular price with tier price of $80 for quantity of 5 or more.
      type: object
      required:
        - qty
        - price
      properties:
        qty:
          type: number
          format: float
          description: |
            Minimum quantity required to qualify for this tier price.
            Must be greater than 1.
          example: 5
        price:
          type: number
          format: float
          description: |
            Fixed price offered for the specified quantity threshold.
            Must be a positive number less than or equal to the regular price.
          example: 80.00
    TierPercentage:
      title: Tier Percentage Discount
      description: |
        Percentage discount applied to the regular price when purchasing at or above a specific quantity threshold.
        Example: $100 regular price with 20% discount for quantity of 10 or more.
      type: object
      required:
        - qty
        - percentage
      properties:
        qty:
          type: number
          format: float
          description: |
            Minimum quantity required to qualify for this tier discount.
            Must be greater than 1.
          example: 10
        percentage:
          type: number
          format: float
          description: |
            Discount percentage applied to the specified quantity threshold.
            Valid range is 0.01 to 99.99 (1% to 99.99%).
          example: 20.0
    Source:
      title: Catalog source
      description: Source of the entity, for example, "en-US" for US English.
      type: object
      required:
        - locale
      properties:
        locale:
          type: string
          description: A single value that represents content locale, for example, English.
          example: English
    SourceLayer:
      title: Catalog layer source
      description: |
        Identifies the source context for a product layer, combining locale and layer name to create 
        a unique layer identifier. This allows for precise targeting of content overrides.
      type: object
      required:
        - layer
      properties:
        locale:
          type: string
          description: |
            ISO locale code (for example, "en-US", "fr-FR", "de-DE") that specifies the target market or language. 
            When omitted, the layer applies globally across all locales. Use for market-specific customizations.
          example: en-US
        layer:
          type: string
          description: |
            Unique identifier for the layer within the product's layer hierarchy. Use descriptive names 
            that indicate the layer's purpose (for example, "seasonal-winter-2024", "promotional-black-friday", "a-b-test-variant").
          example: seasonal-winter-2024
    ProductMetaAttribute:
      title: Meta Attributes
      description: Meta attributes that are specified in <meta> tags.
      type: object
      properties:
        title:
          type: string
          description: A meta title
        keywords:
          type: array
          description: A meta keywords
          items:
            type: string
        description:
          type: string
          description: A meta description
    CategoryMetaAttribute:
      title: Meta Attributes
      description: Meta attributes that are specified in <meta> tags.
      type: object
      properties:
        title:
          type: string
          description: A meta title
        keywords:
          type: array
          description: A meta keywords
          items:
            type: string
        description:
          type: string
          description: A meta description
    ProductAttribute:
      title: Product Attribute
      type: object
      required:
        - code
        - values
      properties:
        code:
          type: string
          description: Product Attribute Code
# DCAT-2461:
#        type:
#          enum:
#            - BOOLEAN
#            - NUMBER
#            - STRING
#            - ARRAY
#            - OBJECT
#          description: |
#            Type of attribute value to be applied during the rendering phase. Validation occurs only when the code is rendered. Invalid values are ignored.
#            - `BOOLEAN`: Accept single value: "true" or false
#            - `NUMBER`: Accept single number,e.g. "85", "0.42", etc.
#            - `STRING`: Accept single string,e.g. "Great day, yall!"
#            - `ARRAY`: Accept list of strings ,e.g. ["red", "green", "blue"]
#            - `OBJECT`: Accept JSON object `"{"name": "swatch", "color": "red"}"`
        values:
          type: array
          description: A list of value(s) associated with a specified attribute code.
          items:
            type: string
        variantReferenceId:
          type: string
          nullable: true
          description: |
            The variant reference ID establishes a link between a product variant and the corresponding
            [Option Value ID](#operation/createProducts!path=options/values/id&t=request) in a configurable product.

            A variant reference ID can be specified only for a product that represents a variant of a configurable product.
    CategoryAttribute:
      title: Category Attribute
      type: object
      required:
        - code
        - values
      properties:
        code:
          type: string
          description: Category Attribute Code
        values:
          type: array
          description: A list of value(s) associated with a specified attribute code.
          items:
            type: string
    ProductRoutes:
      title: Routes
      type: object
      required:
        - path
      properties:
        path:
          type: string
          description: URL path
        position:
          type: integer
          description: Position of a product in the URL path. The default value is 0.
          format: int32
    ProductImage:
      title: Product Image
      type: object
      required:
        - url
      properties:
        url:
          type: string
          description: Media resource URL
        label:
          type: string
          description: Media resource label
        roles:
          type: array
          description: |
            Roles associated with this image that determine how the image is used on the storefront.
            - `BASE`: Product image is visible as a main image on the Product Detail Page.
            - `SMALL`: Product image is visible as a main image on the Category or search result page or other product listing pages.
            - `THUMBNAIL`: Thumbnail images appear in the thumbnail gallery, shopping cart, etc.
            - `SWATCH`: A swatch can be used to illustrate the color, pattern, or texture.
          items:
            enum:
              - BASE
              - SMALL
              - THUMBNAIL
              - SWATCH
        customRoles:
          type: array
          description: >
            Custom image role. Merchants can define custom roles in addition to the predefined values.
          items:
            type: string
    CategoryImage:
      title: Category Image
      type: object
      required:
        - url
      properties:
        url:
          type: string
          description: Media resource URL
        label:
          type: string
          description: Media resource label
        roles:
          type: array
          description: |
            Roles associated with this image that determine how the image is used on the storefront.
            - `BASE`: Category image is visible as a main image on the Category Detail Page.
            - `THUMBNAIL`: Thumbnail images appear in the thumbnail gallery, shopping cart, etc.
          items:
            enum:
              - BASE
              - THUMBNAIL
        customRoles:
          type: array
          description: >
            Custom image role. Merchants can define custom roles in addition to the predefined values.
          items:
            type: string
    ProductConfiguration:
      title: Configurations
      type: object
      required:
        - attributeCode
        - type
        - values
      properties:
        attributeCode:
          type: string
          description: |
            Product option attribute code. For `CONFIGURABLE` or `SWATCH` option types, this ID must match the
            ["attribute code"](#operation/createProducts!path=attributes/code&t=request)
            used for the configurable product (for example, "color").
        label:
          type: string
          description: Option label
        defaultVariantReferenceId:
          type: string
          description: Specifies the pre-selected value variant reference id of the current option.
          nullable: true
        type:
          type: string
          enum:
            - CONFIGURABLE
            - SWATCH
          description: |
            Option type. Indicates the product type the option can be assigned to.
            - `CONFIGURABLE`: Configurable product option
            - `SWATCH`: Swatch product option. Must be used for color or text swatches attributes
        values:
          type: array
          description: A list of option values. Defines option values available to shoppers (for example, "red" color or "large" size).
          items:
            $ref: "#/components/schemas/ProductOptionValue"
    ProductOptionValue:
      title: ProductOptionValue
      type: object
      required:
        - variantReferenceId
      properties:
        variantReferenceId:
          type: string
          description: |
            Option value ID.
            For `CONFIGURABLE` or `SWATCH` option types, this ID must match the ["variantReferenceId"](#operation/createProducts!path=attributes/variantReferenceId&t=request)
            defined in the product variant.
        label:
          type: string
          description: Option value label
        colorHex:
          type: string
          description: A hex representation of the color of the option value. Can be used for option with a SWATCH type.
        imageUrl:
          type: string
          description: Image URL of the option value. Can be used for option with a SWATCH type.
    ProductBundle:
      title: Bundles
      type: object
      required:
        - group
        - items
      properties:
        group:
          type: string
          description: |
            Name of the group that organizes the bundle items.
            This helps in categorizing the items within the bundle for better organization.
            For example, groups can be "shirts", "pants", "accessories", etc.
        required:
          type: boolean
          description: Indicates whether a shopper is required to select any products from this group to add the bundle to the shopping cart.
          example: false
        multiSelect:
          type: boolean
          description: Indicates whether multiple products can be selected by a shopper.
          example: false
        defaultItemSkus:
          type: array
          description: A list of default product SKUs that are selected in this bundle group.
          items:
            type: string
        items:
          type: array
          description: |
            A list of individual products that are part of the bundle.
            Each item in the list represents a product that can be selected as part of the bundle.
          items:
            $ref: "#/components/schemas/ProductBundleItem"
    ProductExternalId:
      title: External Ids
      type: object
      required:
        - id
        - origin
      properties:
        id:
          type: string
          description: External ID of the product.
        origin:
          type: string
          description: External ID origin. Specifies the system that generated the external ID, such as Adobe Commerce, Google Product Ratings, etc.
    ProductBundleItem:
      title: ProductBundleItem
      type: object
      required:
        - sku
      properties:
        sku:
          type: string
          description: Product SKU of the bundle item.
        qty:
          type: number
          description: Quantity of the item in the bundle.
          format: float
        userDefinedQty:
          type: boolean
          description: Indicates whether the quantity of the item in the bundle can be defined by a shopper.
          example: false
    ProductLink:
      title: Links
      required:
        - type
        - sku
      type: object
      properties:
        type:
          type: string
          description: |
            Product link type. Merchants can define custom types in addition to the predefined values.
            - `VARIANT_OF` link type must be specified to establish a connection to the configurable product SKU.
            - `IN_BUNDLE` link type must be specified to establish a connection to the bundle product SKU.
        sku:
          type: string
          description: Product SKU
      description: Product association
    ProcessFeedResponse:
      title: Response payload
      type: object
      properties:
        status:
          type: string
          description: Request status.
          default: ACCEPTED
        acceptedCount:
          type: integer
          description: The number of received and accepted items.
          format: int32
      example: { "status": "ACCEPTED", "acceptedCount": 4 }
    400ProcessFeedResponse:
      title: Response payload
      type: object
      properties:
        status:
          type: string
          description: Request status.
          default: FAILED
        message:
          type: string
          description: Error summary.
        errors:
          type: array
          description: List of items that did not pass validation. Fix the payload for invalid items before resubmitting the request.
          items:
            $ref: "#/components/schemas/FeedItemFailedValidationResult"
      example:
        {
          "status": "FAILED",
          "message": "Items validation failed for 2 items",
          "errors":
            [
              {
                "itemIndex": 0,
                "code": "status",
                "message": 'status: does not have a value in the enumeration ["ENABLED", "DISABLED"]',
                "value": "active"
              },
              {
                "itemIndex": 1,
                "code": "source",
                "message": "required property 'source' not found",
                "value": ""
              }
            ]
        }
    401Response:
      title: 401 Unauthorized
      type: object
      properties:
        title:
          type: string
          description: Error title
        status:
          type: string
          description: Error status code
        error_code:
          type: string
          description: Error code
        message:
          type: string
          description: Error message
      example:
        {
          "title": "ErrInvalidOauthToken",
          "status": "401",
          "error_code": "401013",
          "message": "Oauth token is not valid"
        }
    403Response:
      title: 403 Forbidden
      type: object
      properties:
        title:
          type: string
          description: Error title
        status:
          type: string
          description: Error status code
        error_code:
          type: string
          description: Error code
        message:
          type: string
          description: Error message
      example:
        {
          "title": "ErrMissingOauthToken",
          "status": "403",
          "error_code": "403010",
          "message": "Oauth token is missing"
        }
    429Response:
      title: 429 Too Many Requests
      description: |
        Too many requests. Indicates that a client has exceeded the rate limit of 300 requests per minute.
        Check the `retry-after` header to get the time (in seconds) to wait before sending the next request.
      type: string