Mapp Marketing Cloud Variant Data Operations API

openapi: 3.2.0
info:
  title: Product Catalog - Public Variant Data Operations API
  version: 1.0.1
  description: Endpoints for variant data operations
servers:
- url: https://api.mapp.com
security:
- Keycloak: []
tags:
- name: Variant Data Operations
  description: Endpoints for variant data operations
paths:
  /api/product-catalog/v1/catalogs/{catalogId}/variants:
    post:
      tags:
      - Variant Data Operations
      summary: 'Add a new variant or add missing data to an existing variant. '
      description: If the variant does not exist it is created; if it already exists, only fields that are not yet present are added and existing values remain unchanged.
      operationId: addVariant
      parameters:
      - name: catalogId
        in: path
        description: Catalog identifier where the variant should be added.
        required: true
        schema:
          type: integer
          format: int64
      requestBody:
        description: Variant attributes to add. The payload must include variant_id.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddVariantOperationFlatSchema'
            example:
              variant_id: V-1001
              product_id: P-500
              status: 1
              availability: true
              color:
                en-GB: Navy Blue
                de-DE: Marineblau
                fr-FR: Bleu marine
              price:
                US: 29.99
                GB: 24.99
              size:
                US: S
                EU: '36'
        required: true
      responses:
        '400':
          description: Variant add was rejected during validation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VariantOperationResponseDTO'
              example:
                variant_id: V-1001
                catalog_id: 123
                status: failed
                message: 'Variant add failed: variant_id field must be provided'
                operation: add
                accepted_at: 1783502993000
                accepted_attributes: {}
                skipped_attributes: {}
        '202':
          description: Variant add accepted for processing
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VariantOperationResponseDTO'
              example:
                variant_id: V-1001
                catalog_id: 123
                status: accepted
                message: Variant add accepted for processing
                event_id: 550e8400-e29b-41d4-a716-446655440000
                operation: add
                accepted_at: 1783502993000
                accepted_attributes:
                  variant_id: V-1001
                  product_id: P-500
                  status: 1
                  availability: true
        '500':
          description: Variant add failed unexpectedly.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                message: Unexpected error while processing request
                httpStatus: 500
                errorCode: 500 Internal Server Error
                timestamp: '2026-07-08T12:00:00Z'
    get:
      tags:
      - Variant Data Operations
      summary: List variants with cursor pagination
      description: Returns a page of variants for the given company and catalog using cursor-based pagination. Provide either 'lastId' (forward) or 'firstId' (backward) together with a page 'size'; the two cursors are mutually exclusive. Results can additionally be filtered by attribute active status, product data layer, and a modification timestamp range. If no data is found, HTTP 204 (No Content) is returned.
      operationId: getPaginatedVariants
      parameters:
      - name: catalogId
        in: path
        description: Catalog identifier whose variants should be listed.
        required: true
        schema:
          type: integer
          format: int64
      - name: activeStatusSearch
        in: query
        description: Controls whether active attributes, inactive attributes, or all attributes are included in the returned variant data. Defaults to ALL.
        required: false
        schema:
          type: string
          default: ALL
          enum:
          - ACTIVE_ONLY
          - INACTIVE_ONLY
          - ALL
      - name: catalogType
        in: query
        description: Selects which product data layer to query. Defaults to COMBINED.
        required: false
        schema:
          type: string
          default: COMBINED
          enum:
          - SOURCE
          - ENRICHED
          - COMBINED
      - name: lastId
        in: query
        description: Forward pagination cursor. Returns variants after this document id; the cursor value itself is excluded. Cannot be used together with firstId.
        required: false
        schema:
          type: string
      - name: firstId
        in: query
        description: Backward pagination cursor. Returns variants before this document id; the cursor value itself is excluded. Cannot be used together with lastId.
        required: false
        schema:
          type: string
      - name: size
        in: query
        description: Maximum number of variants to return in one page. Defaults to 100; values less than 1 or greater than 100 are normalized to 100.
        required: false
        schema:
          type: integer
          format: int32
          default: 100
      - name: fromModifiedTimestamp
        in: query
        description: Filters variants modified at or after this timestamp. The value is epoch milliseconds and the lower bound is inclusive. If this is provided, toModifiedTimestamp is required. For paginated scans, capture this value once before the first page and keep it unchanged for every page.
        required: false
        schema:
          type: integer
          format: int64
        example: 1783503393000
      - name: toModifiedTimestamp
        in: query
        description: Filters variants modified at or before this timestamp. The value is epoch milliseconds, the upper bound is inclusive, it must not be greater than the current server time, and it is required when fromModifiedTimestamp is provided. For paginated scans, capture this value once before the first page and keep it unchanged for every page.
        required: false
        schema:
          type: integer
          format: int64
        example: 1783506993000
      responses:
        '200':
          description: Paginated variants found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedVariantsResponseDTO'
              example:
                productViewPayloads:
                - variant_id: V-1001
                  product_id: P-500
                  status:
                    value: 1
                    label: active
                  availability:
                    value: true
                    label: available
                  catalog_id: 123
                  source_creation_time: 1783502993000
                  source_update_time: 1783503093000
                  enriched_creation_time: 1783503193000
                  enriched_update_time: 1783503293000
                  color:
                    en-GB: Navy Blue
                    de-DE: Marineblau
                  fashion_material: leather
                  fashion_season: summer
                - variant_id: V-1002
                  product_id: P-500
                  status:
                    value: 1
                    label: active
                  availability:
                    value: true
                    label: available
                  catalog_id: 123
                  source_creation_time: 1783503393000
                  source_update_time: 1783503493000
                  enriched_creation_time: 1783503593000
                  enriched_update_time: 1783503693000
                  size:
                    US: M
                    EU: '38'
                  fashion_material: leather
                  fashion_season: summer
                paginationCursor:
                  lastId: 687d57eb6986be26d3f7e0b4
                  firstId: 687d57eb6986be26d3f7e0a3
                  previousPageExists: false
                  nextPageExists: true
        '400':
          description: Pagination is missing or invalid, modification date filters are invalid, or catalog attributes are not configured.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                message: Cannot specify both lastId and firstId
                httpStatus: 400
                errorCode: 400 Bad Request
                timestamp: '2026-07-08T12:00:00Z'
        '404':
          description: Catalog was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                message: 'Product feed not found for companyId: 456 and feedId: 123'
                httpStatus: 404
                errorCode: 404 Not Found
                timestamp: '2026-07-08T12:00:00Z'
        '204':
          description: No variants were found for the requested page and filters.
        '500':
          description: Unexpected error while fetching paginated variants.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                message: Unexpected error while processing request
                httpStatus: 500
                errorCode: 500 Internal Server Error
                timestamp: '2026-07-08T12:00:00Z'
  /api/product-catalog/v1/catalogs/{catalogId}/variants/{variantId}:
    put:
      tags:
      - Variant Data Operations
      summary: Create or fully replace a variant
      description: If the variant does not exist it is created; if it already exists, all of its data is completely overwritten with the provided payload.
      operationId: upsertVariant
      parameters:
      - name: catalogId
        in: path
        description: Catalog identifier where the variant should be created or replaced.
        required: true
        schema:
          type: integer
          format: int64
      - name: variantId
        in: path
        description: Variant identifier to create or fully replace.
        required: true
        schema:
          type: string
      requestBody:
        description: Complete variant payload that will replace existing variant data.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpsertVariantOperationFlatSchema'
            example:
              product_id: P-500
              status: 1
              availability: true
              color:
                en-GB: Navy Blue
                de-DE: Marineblau
                fr-FR: Bleu marine
              price:
                US: 29.99
                GB: 24.99
              size:
                US: S
                EU: '36'
        required: true
      responses:
        '500':
          description: Variant upsert failed unexpectedly.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                message: Unexpected error while processing request
                httpStatus: 500
                errorCode: 500 Internal Server Error
                timestamp: '2026-07-08T12:00:00Z'
        '400':
          description: Variant upsert was rejected during validation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VariantOperationResponseDTO'
              example:
                variant_id: V-1001
                catalog_id: 123
                status: failed
                message: 'Variant upsert failed: missingMandatoryFields=[price]'
                operation: upsert
                accepted_at: 1783502993000
                accepted_attributes: {}
                skipped_attributes: {}
        '202':
          description: Variant upsert accepted for processing
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VariantOperationResponseDTO'
              example:
                variant_id: V-1001
                catalog_id: 123
                status: accepted
                message: Variant upsert accepted for processing
                event_id: 550e8400-e29b-41d4-a716-446655440000
                operation: upsert
                accepted_at: 1783502993000
                accepted_attributes:
                  variant_id: V-1001
                  product_id: P-500
                  status: active
                  availability: available
    delete:
      tags:
      - Variant Data Operations
      summary: Delete a variant by ID
      description: Both source and enriched data is removed.
      operationId: deleteVariant
      parameters:
      - name: catalogId
        in: path
        description: Catalog identifier containing the variant to delete.
        required: true
        schema:
          type: integer
          format: int64
      - name: variantId
        in: path
        description: Variant identifier to delete.
        required: true
        schema:
          type: string
      responses:
        '202':
          description: Variant delete accepted for processing
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VariantOperationResponseDTO'
              example:
                variant_id: V-1001
                catalog_id: 123
                status: accepted
                message: Variant delete accepted for processing
                event_id: 550e8400-e29b-41d4-a716-446655440000
                operation: delete
                accepted_at: 1783502993000
        '400':
          description: Variant delete was rejected during validation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VariantOperationResponseDTO'
              example:
                variant_id: V-1001
                catalog_id: 123
                status: failed
                message: 'Variant delete failed: price mandatory field cannot be deleted'
                operation: delete
                accepted_at: 1783502993000
                accepted_attributes: {}
                skipped_attributes: {}
        '404':
          description: Variant delete target was not found by downstream validation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VariantOperationResponseDTO'
              example:
                variant_id: V-1001
                catalog_id: 123
                status: failed
                message: 'Variant delete failed: price mandatory field cannot be deleted'
                operation: delete
                accepted_at: 1783502993000
                accepted_attributes: {}
                skipped_attributes: {}
        '500':
          description: Variant delete failed unexpectedly.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                message: Unexpected error while processing request
                httpStatus: 500
                errorCode: 500 Internal Server Error
                timestamp: '2026-07-08T12:00:00Z'
    get:
      tags:
      - Variant Data Operations
      summary: Get a single variant by ID
      description: Retrieves a single variant identified by its variant ID from the specified catalog. The returned attributes can be filtered by active status and by the product data layer (source, enriched, or combined). Returns 204 (No Content) when no variant matches the requested identifier and filters.
      operationId: getVariant
      parameters:
      - name: catalogId
        in: path
        description: Catalog identifier that contains the variant.
        required: true
        schema:
          type: integer
          format: int64
      - name: variantId
        in: path
        description: Variant identifier to retrieve from the catalog.
        required: true
        schema:
          type: string
      - name: activeStatusSearch
        in: query
        description: Controls whether active attributes, inactive attributes, or all attributes are included in the returned variant data. Defaults to ALL.
        required: false
        schema:
          type: string
          default: ALL
          enum:
          - ACTIVE_ONLY
          - INACTIVE_ONLY
          - ALL
      - name: catalogType
        in: query
        description: Selects which product data layer to query. Defaults to COMBINED.
        required: false
        schema:
          type: string
          default: COMBINED
          enum:
          - SOURCE
          - ENRICHED
          - COMBINED
      responses:
        '500':
          description: Unexpected error while fetching variant data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                message: Unexpected error while processing request
                httpStatus: 500
                errorCode: 500 Internal Server Error
                timestamp: '2026-07-08T12:00:00Z'
        '404':
          description: Catalog was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                message: 'Product feed not found for companyId: 456 and feedId: 123'
                httpStatus: 404
                errorCode: 404 Not Found
                timestamp: '2026-07-08T12:00:00Z'
        '200':
          description: Variant found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VariantFlatViewResponse'
              example:
                variant_id: V-1001
                product_id: P-500
                status:
                  value: 1
                  label: active
                availability:
                  value: true
                  label: available
                catalog_id: 123
                source_creation_time: 1783502993000
                source_update_time: 1783503093000
                enriched_creation_time: 1783503193000
                enriched_update_time: 1783503293000
                color:
                  en-GB: Navy Blue
                  de-DE: Marineblau
                  fr-FR: Bleu marine
                price:
                  US: 29.99
                  GB: 24.99
                size:
                  US: S
                  EU: '36'
                fashion_material: leather
                fashion_season: summer
        '204':
          description: Variant was not found for the requested catalog and filters.
        '400':
          description: Invalid query parameters or catalog attribute configuration.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                message: Cannot specify both lastId and firstId
                httpStatus: 400
                errorCode: 400 Bad Request
                timestamp: '2026-07-08T12:00:00Z'
    patch:
      tags:
      - Variant Data Operations
      summary: Partially update a variant
      description: 'Updates selected fields of an existing variant. Only the fields present in the payload are changed; all other fields are left untouched. If the variant does not exist, no action is taken. '
      operationId: partialUpdateVariant
      parameters:
      - name: catalogId
        in: path
        description: Catalog identifier containing the variant to update.
        required: true
        schema:
          type: integer
          format: int64
      - name: variantId
        in: path
        description: Variant identifier to partially update.
        required: true
        schema:
          type: string
      requestBody:
        description: Variant attributes to update. Only provided fields are changed.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PartialUpdateVariantOperationFlatSchema'
            example:
              status: 2
              price:
                US: 39.99
                GB: 34.99
        required: true
      responses:
        '400':
          description: Variant partial update was rejected during validation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VariantOperationResponseDTO'
              example:
                variant_id: V-1001
                catalog_id: 123
                status: failed
                message: 'Variant partial update failed: status value ''archived'' is not a valid VariantStatus'
                operation: partial_update
                accepted_at: 1783502993000
                accepted_attributes: {}
                skipped_attributes: {}
        '202':
          description: Variant partial update accepted for processing
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VariantOperationResponseDTO'
              example:
                variant_id: V-1001
                catalog_id: 123
                status: accepted
                message: Variant partial update accepted for processing
                event_id: 550e8400-e29b-41d4-a716-446655440000
                operation: partial_update
                accepted_at: 1783502993000
                accepted_attributes:
                  variant_id: V-1001
                  status: discontinued
                  price:
                    US: 39.99
                    GB: 34.99
        '500':
          description: Variant partial update failed unexpectedly.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                message: Unexpected error while processing request
                httpStatus: 500
                errorCode: 500 Internal Server Error
                timestamp: '2026-07-08T12:00:00Z'
  /api/product-catalog/v1/catalogs/{catalogId}/variants/:
    delete:
      tags:
      - Variant Data Operations
      summary: Delete all variants in a catalog
      description: Deletes every variant in the specified catalog, removing both source and enriched data. This clears the entire catalog contents and cannot be undone.
      operationId: deleteAllCatalogData
      parameters:
      - name: catalogId
        in: path
        description: Catalog identifier whose variants should be deleted.
        required: true
        schema:
          type: integer
          format: int64
      responses:
        '500':
          description: Catalog variants delete failed unexpectedly.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                message: Unexpected error while processing request
                httpStatus: 500
                errorCode: 500 Internal Server Error
                timestamp: '2026-07-08T12:00:00Z'
        '202':
          description: Catalog variants delete accepted for processing
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CatalogOperationResponseDTO'
              example:
                catalog_id: 123
                status: accepted
                message: Catalog variants delete accepted for processing
                event_id: 550e8400-e29b-41d4-a716-446655440000
                operation: delete
                accepted_at: 1783502993000
        '400':
          description: Catalog variants delete was rejected during validation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CatalogOperationResponseDTO'
              example:
                catalog_id: 123
                status: failed
                message: 'Catalog variants delete failed: Product Catalog by catalogId 123 not found'
                operation: delete
                accepted_at: 1783502993000
  /api/product-catalog/v1/catalogs/{catalogId}/variants/{variantId}/attributes:
    delete:
      tags:
      - Variant Data Operations
      summary: Delete attributes from a variant
      description: Deletes the named attributes from the variant identified by its variant ID in the specified catalog. Only the attributes listed in the request body are removed; the rest of the variant is left unchanged.
      operationId: deleteVariantAttributes
      parameters:
      - name: catalogId
        in: path
        description: Catalog identifier containing the variant.
        required: true
        schema:
          type: integer
          format: int64
      - name: variantId
        in: path
        description: Variant identifier whose attributes should be deleted.
        required: true
        schema:
          type: string
      requestBody:
        description: Names of attributes to delete from the variant.
        content:
          application/json:
            schema:
              type: array
            example:
            - custom_attributeA
            - custom_attribute_B
        required: true
      responses:
        '404':
          description: Variant attributes delete target was not found by downstream validation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VariantOperationResponseDTO'
              example:
                variant_id: V-1001
                catalog_id: 123
                status: failed
                message: 'Variant attributes delete failed: attributeNames cannot be parsed'
                operation: delete_attributes
                accepted_at: 1783502993000
                accepted_attributes: {}
                skipped_attributes: {}
        '500':
          description: Variant attributes delete failed unexpectedly.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                message: Unexpected error while processing request
                httpStatus: 500
                errorCode: 500 Internal Server Error
                timestamp: '2026-07-08T12:00:00Z'
        '202':
          description: Variant attributes delete accepted for processing
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VariantOperationResponseDTO'
              example:
                variant_id: V-1001
                catalog_id: 123
                status: accepted
                message: Variant attributes delete accepted for processing
                event_id: 550e8400-e29b-41d4-a716-446655440000
                operation: delete_attributes
                accepted_at: 1783502993000
                accepted_attributes:
                  variant_id: V-1001
                  attributeNames: custom_attributeA, custom_attribute_B
        '400':
          description: Variant attributes delete was rejected during validation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VariantOperationResponseDTO'
              example:
                variant_id: V-1001
                catalog_id: 123
                status: failed
                message: 'Variant attributes delete failed: attributeNames cannot be parsed'
                operation: delete_attributes
                accepted_at: 1783502993000
                accepted_attributes: {}
                skipped_attributes: {}
components:
  schemas:
    PartialUpdateVariantOperationFlatSchema:
      type: object
      properties:
        brand:
          type: string
          description: Product brand name.
          example: AnnTaylor
        price:
          type: object
          additionalProperties:
            type: number
            description: Current selling price keyed by ISO 3166-1 alpha-2 country code or '*' fallback.
          description: Current selling price keyed by ISO 3166-1 alpha-2 country code or '*' fallback.
          example:
            US: 29.99
            GB: 24.99
            DE: 27.5
            FR: 28.0
        currency:
          type: object
          additionalProperties:
            type: string
            description: Currency keyed by the same country codes as price. Values are ISO 4217 currency codes.
            example: '{"US":"USD","GB":"GBP","DE":"EUR","FR":"EUR","*":"USD"}'
          description: Currency keyed by the same country codes as price. Values are ISO 4217 currency codes.
          example:
            US: USD
            GB: GBP
            DE: EUR
            FR: EUR
            '*': USD
        size:
          type: object
          additionalProperties:
            type: string
            description: Size keyed by ISO 3166-1 alpha-2 country code or '*' fallback.
            example: '{"US":"S","GB":"8","EU":"36"}'
          description: Size keyed by ISO 3166-1 alpha-2 country code or '*' fallback.
          example:
            US: S
            GB: '8'
            EU: '36'
        color:
          type: object
          additionalProperties:
            type: string
            description: Localized colour keyed by BCP 47 locale or '*' fallback.
            example: '{"en-GB":"Navy Blue","de-DE":"Marineblau","fr-FR":"Bleu marine"}'
          description: Localized colour keyed by BCP 47 locale or '*' fallback.
          example:
            en-GB: Navy Blue
            de-DE: Marineblau
            fr-FR: Bleu marine
        mpn:
          type: string
          description: Manufacturer Part Number. Maximum length is 70 characters.
          example: DRESS-BLK-M-2023
        gtin:
          type: string
          description: Global Trade Item Number. Expected length is 8-14 digits.
          example: '1234567890123'
        status:
          type: integer
          description: 'Variant status value: 0 = pre_order, 1 = active, 2 = discontinued.'
          format: int32
          example: 1
          enum:
          - 0
          - 1
          - 2
        availability:
          type: boolean
          description: Variant availability value.
          example: true
        material:
          type: string
          description: Material of the product.
          example: cotton
        gender:
          type: string
          description: Gender value for fashion catalogs.
          example: female
          enum:
          - female
          - male
          - girls
          - boys
          - unisex
        category:
          type: array
          description: Category hierarchy.
          example:
          - ladies
          - dresses
          - short
          items:
            type: string
            description: Category hierarchy.
            example: '["ladies","dresses","short"]'
        locale:
          type: array
          description: Supported locales for this variant.
          example:
          - en-GB
          - de-DE
          items:
            type: string
            description: Supported locales for this variant.
            example: '["en-GB","de-DE"]'
        ean:
          type: string
          description: Standardised article number.
          example: '8076809513456'
        multipack:
          type: integer
          description: Multipack quantity.
          format: int32
          example: 3
        collaboration:
          type: array
          description: Retailer-specific collaboration values.
          example:
          - designer-capsule
          - summer-edit
          items:
            type: string
            description: Retailer-specific collaboration values.
            example: '["designer-capsule","summer-edit"]'
        product_id:
          type: string
          description: Ide

# --- truncated at 32 KB (72 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/mapp/refs/heads/main/openapi/mapp-variant-data-operations-api-openapi.yml