The Product Catalog Public API manages product and variant data inside Mapp Cloud catalogs — create, replace, partially update, upsert, bulk-load and delete variants, manage variant attributes, read catalog and attribute metadata for a workspace, and list variants for a product. Bearer-JWT (Keycloak) authentication against https://api.mapp.com/api/product-catalog/v1.
openapi: 3.0.1
info:
title: Product Catalog - Public API
version: 1.0.1
servers:
- url: https://api.mapp.com
security:
- Keycloak: []
tags:
- name: Variant Data Bulk Operations
description: Endpoints for variant data bulk operations
- name: Variant Data Operations
description: Endpoints for variant data operations
- name: Catalog Metadata Operations
description: Endpoints for catalog metadata operations
- name: Product Data Operations
description: Endpoints for product 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/bulk:
post:
tags:
- Variant Data Bulk Operations
summary: Bulk add variants
description: 'Adds multiple variants in a single request. Each variant in the array is processed like a single add:
new variants are created and missing fields are added to existing ones, without changing existing values. Up to 1000
variants are allowed per request.'
operationId: bulkAddVariants
parameters:
- name: catalogId
in: path
description: Catalog identifier where variants should be added.
required: true
schema:
type: integer
format: int64
requestBody:
description: List of variant payloads to add. Each payload must include variant_id.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/AddVariantOperationFlatSchema'
required: true
responses:
'202':
description: Variant add accepted for processing
content:
application/json:
schema:
$ref: '#/components/schemas/BulkVariantOperationResponseDTO'
example:
operation_id: 350e8400-e29b-41d4-a716-546655440000
operation: add
status: accepted
catalog_id: 123
total_variants_success: 2
total_variants_failed: 0
message: Variant add accepted for processing
accepted_at: 1783502993000
variant_events_success:
- event_id: 550e8400-e29b-41d4-a716-446655440000
variant_id: V-1001
status: accepted
accepted_attributes:
variant_id: V-1001
product_id: P-500
status: active
availability: available
- event_id: 660e8400-e29b-41d4-a716-446655440000
variant_id: V-1002
status: accepted
accepted_attributes:
variant_id: V-1002
product_id: P-500
status: active
availability: available
variant_events_failed: []
'500':
description: Unexpected error while processing bulk add.
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: Bulk add payload list is missing or null.
content:
application/json:
schema:
$ref: '#/components/schemas/BulkVariantOperationResponseDTO'
example:
operation_id: 350e8400-e29b-41d4-a716-546655440000
operation: add
status: failed
catalog_id: 123
total_variants_success: 0
total_variants_failed: 0
message: Payload list is null
accepted_at: 1783502993000
variant_events_success: []
variant_events_failed: []
'422':
description: Bulk add payload exceeds the maximum allowed size of 1000 variants.
content:
application/json:
schema:
$ref: '#/components/schemas/BulkVariantOperationResponseDTO'
example:
operation_id: 350e8400-e29b-41d4-a716-546655440000
operation: add
status: failed
catalog_id: 123
total_variants_success: 0
total_variants_failed: 0
message: Payload list exceeds maximum allowed size of 1000
accepted_at: 1783502993000
variant_events_success: []
variant_events_failed: []
delete:
tags:
- Variant Data Bulk Operations
summary: Bulk delete variants
description: Deletes multiple variants in a single request. Each variant in the array is deleted if it exists and skipped
otherwise, removing both source and enriched data. Up to 1000 variants are allowed per request.
operationId: bulkDeleteVariants
parameters:
- name: catalogId
in: path
description: Catalog identifier containing the variants to delete.
required: true
schema:
type: integer
format: int64
requestBody:
description: List of variant identifiers to delete.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/BulkDeleteVariantOperationFlatSchema'
example:
- variant_id: V-1001
- variant_id: V-1002
required: true
responses:
'400':
description: Bulk delete payload list is missing or null.
content:
application/json:
schema:
$ref: '#/components/schemas/BulkVariantOperationResponseDTO'
example:
operation_id: 350e8400-e29b-41d4-a716-546655440000
operation: add
status: failed
catalog_id: 123
total_variants_success: 0
total_variants_failed: 0
message: Payload list is null
accepted_at: 1783502993000
variant_events_success: []
variant_events_failed: []
'422':
description: Bulk delete payload exceeds the maximum allowed size of 1000 variants.
content:
application/json:
schema:
$ref: '#/components/schemas/BulkVariantOperationResponseDTO'
example:
operation_id: 350e8400-e29b-41d4-a716-546655440000
operation: add
status: failed
catalog_id: 123
total_variants_success: 0
total_variants_failed: 0
message: Payload list exceeds maximum allowed size of 1000
accepted_at: 1783502993000
variant_events_success: []
variant_events_failed: []
'500':
description: Unexpected error while processing bulk delete.
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 delete accepted for processing
content:
application/json:
schema:
$ref: '#/components/schemas/BulkVariantOperationResponseDTO'
example:
operation_id: 350e8400-e29b-41d4-a716-546655440000
operation: delete
status: accepted
catalog_id: 123
total_variants_success: 2
total_variants_failed: 0
message: Variant delete accepted for processing
accepted_at: 1783502993000
variant_events_success:
- event_id: 550e8400-e29b-41d4-a716-446655440000
variant_id: V-1001
status: accepted
- event_id: 660e8400-e29b-41d4-a716-446655440000
variant_id: V-1002
status: accepted
variant_events_failed: []
patch:
tags:
- Variant Data Bulk Operations
summary: Bulk partial update variants
description: Partially updates multiple existing variants in a single request. For each variant, only the provided fields
are changed and non-existent variants are skipped. Up to 1000 variants are allowed per request.
operationId: bulkPartialUpdateVariants
parameters:
- name: catalogId
in: path
description: Catalog identifier containing the variants to update.
required: true
schema:
type: integer
format: int64
requestBody:
description: List of partial variant payloads. Only provided fields are changed for each variant.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/BulkPartialUpdateVariantOperationFlatSchema'
required: true
responses:
'202':
description: Variant partial update accepted for processing
content:
application/json:
schema:
$ref: '#/components/schemas/BulkVariantOperationResponseDTO'
example:
operation_id: 350e8400-e29b-41d4-a716-546655440000
operation: partial_update
status: accepted
catalog_id: 123
total_variants_success: 2
total_variants_failed: 0
message: Variant partial update accepted for processing
accepted_at: 1783502993000
variant_events_success:
- event_id: 550e8400-e29b-41d4-a716-446655440000
variant_id: V-1001
status: accepted
accepted_attributes:
status: discontinued
price:
US: 39.99
GB: 34.99
- event_id: 660e8400-e29b-41d4-a716-446655440000
variant_id: V-1002
status: accepted
accepted_attributes:
availability: not_available
variant_events_failed: []
'500':
description: Unexpected error while processing bulk partial update.
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'
'422':
description: Bulk partial update payload exceeds the maximum allowed size of 1000 variants.
content:
application/json:
schema:
$ref: '#/components/schemas/BulkVariantOperationResponseDTO'
example:
operation_id: 350e8400-e29b-41d4-a716-546655440000
operation: add
status: failed
catalog_id: 123
total_variants_success: 0
total_variants_failed: 0
message: Payload list exceeds maximum allowed size of 1000
accepted_at: 1783502993000
variant_events_success: []
variant_events_failed: []
'400':
description: Bulk partial update payload list is missing or null.
content:
application/json:
schema:
$ref: '#/components/schemas/BulkVariantOperationResponseDTO'
example:
operation_id: 350e8400-e29b-41d4-a716-546655440000
operation: add
status: failed
catalog_id: 123
total_variants_success: 0
total_variants_failed: 0
message: Payload list is null
accepted_at: 1783502993000
variant_events_success: []
variant_events_failed: []
put:
tags:
- Variant Data Bulk Operations
summary: Bulk upsert variants
description: Creates or fully replaces multiple variants in a single request. Each variant in the array is created if
missing or has all of its data overwritten if it already exists. Up to 1000 variants are allowed per request.
operationId: bulkUpsertVariants
parameters:
- name: catalogId
in: path
description: Catalog identifier where variants should be created or replaced.
required: true
schema:
type: integer
format: int64
requestBody:
description: List of complete variant payloads that will replace existing variant data.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/BulkUpsertVariantOperationFlatSchema'
required: true
responses:
'400':
description: Bulk upsert payload list is missing or null.
content:
application/json:
schema:
$ref: '#/components/schemas/BulkVariantOperationResponseDTO'
example:
operation_id: 350e8400-e29b-41d4-a716-546655440000
operation: add
status: failed
catalog_id: 123
total_variants_success: 0
total_variants_failed: 0
message: Payload list is null
accepted_at: 1783502993000
variant_events_success: []
variant_events_failed: []
'202':
description: Variant upsert accepted for processing
content:
application/json:
schema:
$ref: '#/components/schemas/BulkVariantOperationResponseDTO'
example:
operation_id: 350e8400-e29b-41d4-a716-546655440000
operation: upsert
status: accepted
catalog_id: 123
total_variants_success: 2
total_variants_failed: 0
message: Variant upsert accepted for processing
accepted_at: 1783502993000
variant_events_success:
- event_id: 550e8400-e29b-41d4-a716-446655440000
variant_id: V-1001
status: accepted
accepted_attributes:
variant_id: V-1001
product_id: P-500
status: active
availability: available
- event_id: 660e8400-e29b-41d4-a716-446655440000
variant_id: V-1002
status: accepted
accepted_attributes:
variant_id: V-1002
product_id: P-500
status: discontinued
availability: not_available
variant_events_failed: []
'422':
description: Bulk upsert payload exceeds the maximum allowed size of 1000 variants.
content:
application/json:
schema:
$ref: '#/components/schemas/BulkVariantOperationResponseDTO'
example:
operation_id: 350e8400-e29b-41d4-a716-546655440000
operation: add
status: failed
catalog_id: 123
total_variants_success: 0
total_variants_failed: 0
message: Payload list exceeds maximum allowed size of 1000
accepted_at: 1783502993000
variant_events_success: []
variant_events_failed: []
'500':
description: Unexpected error while processing bulk upsert.
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
# --- truncated at 32 KB (126 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/mapp/refs/heads/main/openapi/mapp-product-catalog-openapi.yml