openapi: 3.2.0
info:
  title: Catalog Data Ingestion Products 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: Products
  description: Create and manage product data including simple products, configurable products, and their variants. Control product visibility, attributes, images, and pricing
paths:
  /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.\n\nWhen creating products:\n - Each product requires a unique SKU identifier.\n - Products must have a defined catalog source, for example `locale`.\n - Add values for the required `name`, `slug`, and `status` fields.\n - Define optional fields such as descriptions, images, and custom attributes as needed.\n - Use the `links` field to define relationships between products, such as linking a product variant to its parent\n configurable product.\n - You can create multiple products in a single request, and also create product variants for configurable products in the same request.\n - Use the `routes` field to set category paths. The `path` value must match an existing category slug, for example `men/clothing`. \n - 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.\n\n<h3 id=\"simpleProducts\">Simple products</h3>\nCreate products or replace existing products with specified `sku` and `source` values.\n\nUse the <strong>[update operation](#operation/updateProducts)</strong> to modify values for an existing product.\n\n<h3 id=\"configurableProducts\">Configurable products</h3>\n\nA configurable product is a parent product that allows customers to select from multiple predefined attributes such as color, size, and material.\nEach unique combination of these attribute values (for example, `color=green`, `size=large`) represents a product variant.\n\nEach 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.\n\nThe configurable product itself acts as a container or abstraction layer, enabling a unified frontend experience while maintaining\ngranular control over each variant on the backend.\n\nTo create a configurable product, you need the following:\n\n* <strong>Product attributes</strong>—<a href=\"#operation/createProductMetadata\">Create product attributes</a> (for example, \"color\", \"size\")\nthat will be used to differentiate product variants. These attributes must be registered in the system before they can be referenced in\nproduct definitions.\n\n* <strong>Configurable product</strong>—Define the parent product and include a\n  [configurations](#operation/createProducts!path=configurations&t=request) array that specifies the selectable options\n  and maps each option to a set of possible values. Each value must include a\n  [variantReferenceId](#operation/createProducts!path=configurations/values/variantReferenceId&t=request),\n  which links to a specific variant.\n\n* <strong>Product variants</strong>—Define a product variant for each valid combination of attribute values. Each variant must:\n  * Include relevant attribute values in an [attributes](#operation/createProducts!path=attributes&t=request) array.\n  * Reference the parent configurable product using variantReferenceId.\n  * Include a [links](#operation/createProducts!path=links&t=request) array with a link of type `VARIANT_OF` pointing to the configurable product.\n\n  For example:\n\n  <pre>\n  {\n    \"sku\": \"pants-red-32\",\n    \"attributes\": [\n      {\n        \"code\": \"color\",\n        \"values\": [\"Red\"],\n        \"variantReferenceId\": \"pants-color-red\"\n      }\n    ],\n    \"links\": [\n      {\n        \"type\": \"VARIANT_OF\",\n        \"sku\": \"pants\"\n      }\n    ]\n  }\n</pre>\n\n  Each product variant links back to the configurable product through its `variantReferenceId`, which corresponds to specific `configurations[].values[].variantReferenceId` in the configurable product.\n\n  To unassign a product variant from a configurable product, do one of the following:\n  - Use [Delete Product API](#operation/deleteProducts) to delete the product variant.\n  - 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.\n\n<h3>Bundle products</h3>\n\nA 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`.\nEach group can have multiple items, and shoppers can select items from each group to create a customized bundle.\n\nTo create a bundle product, you need the following:\n\n* <strong>Bundle product</strong>—[Define the parent product](#operation/createProducts) and include a [bundles](#operation/createProducts!path=bundles) array that\nspecifies the groups and items included in the bundle. Each group must define:\n  * `group` - Name of the group (for example, \"tops\", \"bottoms\")\n  * `required` - Whether a selection from this group is mandatory\n  * `multiSelect` - Whether multiple items can be selected\n  * `items` - List of products that can be selected from this group\n\n* <strong>Simple products</strong>—Define each simple product to include in the bundle. Each product must:\n  * Include a [links](#operation/createProducts!path=links) array with a link of type `IN_BUNDLE` pointing to the bundle product\n  * Be created separately using the [create product API](#operation/createProducts)\n\n<strong>Note:</strong> A simple product can be included only once in each bundle.\nIf the same item is specified in multiple groups, the API returns a `Duplicate SKU found in bundle items` error.\n\nTo update a bundle product, do one of the following:\n* Use the [Update products API](#operation/updateProducts) to modify the groups and items in the bundle\n* Use the [Delete products API](#operation/deleteProducts) to remove items from the bundle\n"
      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
components:
  schemas:
    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'
    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.
    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'
    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
          - 'null'
          description: The main description for the product
          example: A kangaroo hoodie for all seasons
        shortDescription:
          type:
          - string
          - 'null'
          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'
    ProductAttribute:
      title: Product Attribute
      type: object
      required:
      - code
      - values
      properties:
        code:
          type: string
          description: Product Attribute Code
        values:
          type: array
          description: A list of value(s) associated with a specified attribute code.
          items:
            type: string
        variantReferenceId:
          type:
          - string
          - 'null'
          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.

            '
    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
    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
    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
    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
          - 'null'
          description: The main description for the product
          example: A kangaroo hoodie for all seasons
        shortDescription:
          type:
          - string
          - 'null'
          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'
    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
    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
    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: ''
    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
    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
    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.
    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
          - 'null'
          description: Specifies the pre-selected value variant reference id of the current option.
        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'
    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
    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
    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
    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.
  parameters:
    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.
    Authorization:
      name: Authorization
      in: header
      required: true
      schema:
        type: string
        description: Authorization Bearer token
  responses:
    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'
    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'
    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'
    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'
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