Adobe Suite Product Metadata API

openapi: 3.2.0
info:
  title: Catalog Data Ingestion Product Metadata 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: ProductMetadata
  description: 'Manage product attribute definitions including display settings, search behavior, and filtering capabilities.

    These settings control how product attributes appear and function throughout the storefront.


    Product attribute metadata specifies how product attributes are displayed on the storefront.

    For example, you can define a product attribute as searchable, filterable, and sortable.

    You can also define the search type for a product attribute, such as autocomplete or exact match.'
paths:
  /v1/catalog/products/metadata:
    post:
      tags:
      - ProductMetadata
      summary: Create product attribute metadata
      description: 'To ensure product data is indexed for discovery, create or replace existing product attribute metadata resources before creating products.


        For each Commerce project, you must define metadata for the following attributes for each catalog source (`locale`):

        - `sku`

        - `name`

        - `description`

        - `shortDescription`

        - `price`


        Also, you can define metadata for custom attributes.


        When creating product attribute metadata:

        - Each product attribute requires a unique `code` and `source`.

        - Use the `dataType` field to define the data type for the product attribute.

        - Use the `visibleIn` field to define where the product attribute is displayed on the storefront.

        - Use the `filterable`, `sortable`, and `searchable` fields to define how the product attribute

        is used for filtering, sorting, and searching.

        - Use the `searchWeight` field to define the search weight for the product attribute.

        - Use the `searchTypes` field to define the search type for the product attribute.


        To update existing product attribute metadata, use the update operation.'
      operationId: createProductMetadata
      parameters:
      - $ref: '#/components/parameters/Authorization'
      - $ref: '#/components/parameters/ContentType'
      - $ref: '#/components/parameters/ContentEncoding'
      responses:
        '200':
          $ref: '#/components/responses/AcceptedResponse'
        '400':
          $ref: '#/components/responses/InvalidItemsResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ForbiddenResponse'
        '429':
          $ref: '#/components/responses/TooManyRequestsResponse'
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/FeedProductMetadata'
            examples:
              FeedWithMetadataInformation:
                summary: Create product attributes metadata
                description: 'Creates searchable text attributes. This example defines metadata for the required attributes

                  with recommended default values.

                  '
                value:
                - code: sku
                  source:
                    locale: en-US
                  label: Product Name
                  dataType: TEXT
                  visibleIn:
                  - PRODUCT_DETAIL
                  - PRODUCT_LISTING
                  - SEARCH_RESULTS
                  - PRODUCT_COMPARE
                  filterable: true
                  sortable: false
                  searchable: true
                  searchWeight: 1
                  searchTypes:
                  - AUTOCOMPLETE
                - code: name
                  source:
                    locale: en-US
                  label: Product Name
                  dataType: TEXT
                  visibleIn:
                  - PRODUCT_DETAIL
                  - PRODUCT_LISTING
                  - SEARCH_RESULTS
                  - PRODUCT_COMPARE
                  filterable: false
                  sortable: true
                  searchable: true
                  searchWeight: 1
                  searchTypes:
                  - AUTOCOMPLETE
                - code: description
                  source:
                    locale: en-US
                  label: Product Description
                  dataType: TEXT
                  visibleIn:
                  - PRODUCT_DETAIL
                  filterable: false
                  sortable: false
                  searchable: false
                  searchWeight: 1
                  searchTypes:
                  - AUTOCOMPLETE
                - code: shortDescription
                  source:
                    locale: en-US
                  label: Product Short Description
                  dataType: TEXT
                  visibleIn:
                  - PRODUCT_DETAIL
                  filterable: false
                  sortable: false
                  searchable: true
                  searchWeight: 1
                  searchTypes:
                  - AUTOCOMPLETE
                - code: price
                  source:
                    locale: en-US
                  label: Price
                  dataType: DECIMAL
                  visibleIn:
                  - PRODUCT_DETAIL
                  - PRODUCT_LISTING
                  - SEARCH_RESULTS
                  - PRODUCT_COMPARE
                  filterable: true
                  sortable: true
                  searchable: false
                  searchWeight: 1
                  searchTypes: []
    patch:
      tags:
      - ProductMetadata
      summary: Update product attribute metadata
      description: 'Update existing product attribute metadata with new values.

        When the update is processed, the merge strategy is used to apply changes to `scalar` and `object` type fields. The replace strategy is used to apply changes for fields in an `array`.


        > **Note:** Before submitting an update request, verify that the target entity exists using the

        attributeMetadata GraphQL query. Update operations do not verify that the entity exists. Requests targeting a nonexistent entity are accepted, but the update has no effect.'
      operationId: updateProductMetadata
      parameters:
      - $ref: '#/components/parameters/Authorization'
      - $ref: '#/components/parameters/ContentType'
      - $ref: '#/components/parameters/ContentEncoding'
      responses:
        '200':
          $ref: '#/components/responses/AcceptedResponse'
        '400':
          $ref: '#/components/responses/InvalidItemsResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ForbiddenResponse'
        '429':
          $ref: '#/components/responses/TooManyRequestsResponse'
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/FeedProductMetadataUpdate'
            examples:
              FeedWithMetadataInformation:
                summary: Example of product attribute metadata
                description: 'Update existing product attribute metadata with new values.

                  Note that fields with the `array` type will replace existing data.

                  The example below updates the following attributes:

                  * `label` - Change the product attribute label.

                  * `visibleIn` - Add `PRODUCT_LISTING` role to the product attribute.

                  '
                value:
                - code: name
                  source:
                    locale: en-US
                  label: Updated - Product Name
                  visibleIn:
                  - PRODUCT_DETAIL
                  - PRODUCT_LISTING
  /v1/catalog/products/metadata/delete:
    post:
      tags:
      - ProductMetadata
      summary: Delete product attributes metadata
      description: Remove product attribute metadata resources from the catalog data.
      operationId: deleteProductMetadata
      parameters:
      - $ref: '#/components/parameters/Authorization'
      - $ref: '#/components/parameters/ContentType'
      - $ref: '#/components/parameters/ContentEncoding'
      responses:
        '200':
          $ref: '#/components/responses/AcceptedResponse'
        '400':
          $ref: '#/components/responses/InvalidItemsResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ForbiddenResponse'
        '429':
          $ref: '#/components/responses/TooManyRequestsResponse'
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/FeedProductMetadataDelete'
            examples:
              FeedWithMetadataInformation:
                summary: Delete product attribute metadata
                description: Marks existing product attribute metadata as deleted.
                value:
                - code: name
                  source:
                    locale: en-US
components:
  schemas:
    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
    FeedProductMetadata:
      title: Create or update product metadata attribute
      description: Metadata information for a product attribute.
      required:
      - code
      - source
      - label
      - dataType
      type: object
      properties:
        code:
          type: string
          description: Attribute code
        source:
          $ref: '#/components/schemas/Source'
        visibleIn:
          type: array
          description: 'Determines how the attribute is used on the storefront.

            * `PRODUCT_DETAIL`: Product attribute is visible on the Product Detail Page.

            * `PRODUCT_LISTING`: Product attribute is visible on Product Listing Page.

            * `SEARCH_RESULTS`: Product attribute is visible on Search Results Page.

            * `PRODUCT_COMPARE`: Product attribute is visible on Product Compare Page.

            '
          items:
            enum:
            - PRODUCT_DETAIL
            - PRODUCT_LISTING
            - SEARCH_RESULTS
            - PRODUCT_COMPARE
        label:
          type: string
          description: Label for the attribute that is displayed in user interfaces.
          example: Attribute Name
        dataType:
          type: string
          description: Data type
          example: TEXT
          enum:
          - TEXT
          - DECIMAL
          - INTEGER
          - BOOLEAN
        filterable:
          type: boolean
          description: Indicates whether the attribute can be used to filter products.
          example: true
        sortable:
          type: boolean
          description: Indicates whether the attribute can be used to sort products.
          example: true
        searchable:
          type: boolean
          description: Indicates whether the attribute value can be used in search queries to filter results.
          example: true
        searchWeight:
          type: number
          description: 'The weight associated with a searchable attribute.

            Attributes with a greater weight are returned before attributes with a lower weight.

            '
          format: float
        searchTypes:
          type: array
          description: 'Search types associated with this attribute, for example: `autocomplete`, `starts_with`, and so on.

            '
          items:
            type: string
            enum:
            - AUTOCOMPLETE
            - CONTAINS
            - STARTS_WITH
    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
    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: ''
    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.
    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
    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
    FeedProductMetadataUpdate:
      title: Update product metadata attribute
      description: Metadata information for a product attribute.
      required:
      - code
      - source
      type: object
      properties:
        code:
          type: string
          description: Attribute code
        source:
          $ref: '#/components/schemas/Source'
        visibleIn:
          type: array
          description: 'Determines how the attribute is used on the storefront.

            * `PRODUCT_DETAIL`: Product attribute is visible on the Product Detail Page.

            * `PRODUCT_LISTING`: Product attribute is visible on Product Listing Page.

            * `SEARCH_RESULTS`: Product attribute is visible on Search Results Page.

            * `PRODUCT_COMPARE`: Product attribute is visible on Product Compare Page.

            '
          items:
            enum:
            - PRODUCT_DETAIL
            - PRODUCT_LISTING
            - SEARCH_RESULTS
            - PRODUCT_COMPARE
        label:
          type: string
          description: Label for the attribute that is displayed in user interfaces.
          example: Attribute Name
        dataType:
          type: string
          description: Data type
          example: TEXT
          enum:
          - TEXT
          - DECIMAL
          - INTEGER
          - BOOLEAN
        filterable:
          type: boolean
          description: Indicates whether the attribute can be used to filter products.
          example: true
        sortable:
          type: boolean
          description: Indicates whether the attribute can be used to sort products.
          example: true
        searchable:
          type: boolean
          description: Indicates whether the attribute value can be used in search queries to filter results.
          example: true
        searchWeight:
          type: number
          description: 'The weight associated with a searchable attribute.

            Attributes with a greater weight are returned before attributes with a lower weight.

            '
          format: float
        searchTypes:
          type: array
          description: 'Search types associated with this attribute, for example: `autocomplete`, `starts_with`, and so on.

            '
          items:
            type: string
            enum:
            - AUTOCOMPLETE
            - CONTAINS
            - STARTS_WITH
    FeedProductMetadataDelete:
      title: Delete product metadata attribute
      description: Delete metadata information for a product attribute.
      required:
      - code
      - source
      type: object
      properties:
        code:
          type: string
          description: Attribute code
        source:
          $ref: '#/components/schemas/Source'
    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
  parameters:
    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
    ContentType:
      name: Content-Type
      in: header
      required: true
      schema:
        type: string
        enum:
        - application/json
        default: application/json
  responses:
    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'
    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'
    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'
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