openapi: 3.2.0
info:
  title: Catalog Data Ingestion Categories 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: 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/).

    '
paths:
  /v1/catalog/categories:
    post:
      tags:
      - Categories
      summary: Create categories
      description: "Create new categories with hierarchical structure and slug-based paths.\nCategories organize products into logical groups and support nested hierarchies.\n\nWhen creating categories:\n  - Each category requires a unique `slug` and `source`.\n  - To create parent-child relationships, create the `slug` field in a hierarchical format, for example `men/clothing/pants'.\n  - A category `slug` string can contain only lowercase letters, numbers, and hyphens with `/` used as a separator for hierarchy.\n  - Create each category as a separate entity.\n  - Use the `name` field to define the display name for the category.\n  - Use the optional `description` field to provide a full-text description of the category.\n  - Use the optional `families` field to associate categories with product families for enhanced organization.\n  - Use the optional `position` field to assign a numeric sort order to the category.\n  - Use the optional `metaTags` field to define SEO meta tags (title, description, keywords) for the category.\n  - Use the optional `images` field to associate images with the category.\n  - Use the optional `attributes` field to add additional attributes.\n\nAfter 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.\n\nTo update existing categories, use the update operation.\n"
      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
components:
  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
  schemas:
    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
    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
    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
    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
    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: ''
    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
    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
          - 'null'
          description: Full-text description of the category.
          example: Men's clothing, shoes, and accessories
        families:
          type:
          - array
          - 'null'
          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
    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
    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
          - 'null'
          description: Full-text description of the category.
          example: Men's clothing, shoes, and accessories
        families:
          type:
          - array
          - 'null'
          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
    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.
    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
  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