Adobe Suite Categories API

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.
  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.
paths:
  /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 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


        Cascading Deletion


        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


        Recovery Options


        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

        * **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:
  schemas:
    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
    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
    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
    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
    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.
    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
    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
    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
    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
    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
    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: ''
    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
  parameters:
    Authorization:
      name: Authorization
      in: header
      required: true
      schema:
        type: string
        description: Authorization Bearer token
    ContentEncoding:
      name: Content-Encoding
      in: header
      required: false
      schema:
        type: string
        enum:
        - gzip
      description: Use this header if the payload is compressed with gzip.
    ContentType:
      name: Content-Type
      in: header
      required: true
      schema:
        type: string
        enum:
        - application/json
        default: application/json
  responses:
    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'
    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'
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