> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mapp.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Get a single variant by ID
> Deprecated, as it could not handle special characters for variantId in path. Will be removed soon. Use GET /variants?variantId={variantId} instead.
## OpenAPI
````json GET /api/product-catalog/v1/catalogs/{catalogId}/variants/{variantId}
{
"openapi": "3.0.1",
"info": {
"title": "Product Catalog - Public API",
"version": "1.0.3"
},
"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/{variantId}": {
"get": {
"tags": [
"Variant Data Operations"
],
"summary": "Get a single variant by ID",
"description": "Deprecated, as it could not handle special characters for variantId in path. Will be removed soon. Use GET /variants?variantId={variantId} instead.",
"operationId": "getVariantByPath",
"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. If it contains special characters, clients must URL-encode the query parameter value.",
"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": {
"200": {
"description": "OK",
"content": {
"*/*": {
"schema": {
"$ref": "#/components/schemas/VariantFlatViewResponse"
}
}
}
}
},
"deprecated": true
}
}
},
"components": {
"schemas": {
"VariantFlatViewResponse": {
"required": [
"availability",
"catalog_id",
"product_id",
"status",
"variant_id"
],
"type": "object",
"properties": {
"variant_id": {
"type": "string",
"description": "Client-defined unique identifier of the purchasable variant.",
"example": "V-1001"
},
"product_id": {
"type": "string",
"description": "Identifier used for grouping all variants belonging to the same product.",
"example": "P-500"
},
"style_id": {
"type": "string",
"description": "Groups variants that share colour or style but differ by option attributes such as size.",
"example": "S-1000"
},
"status": {
"type": "string",
"example": "{\"value\":1,\"label\":\"active\"}",
"enum": [
"PRE_ORDER",
"ACTIVE",
"DISCONTINUED"
]
},
"availability": {
"type": "string",
"example": "{\"value\":true,\"label\":\"available\"}",
"enum": [
"AVAILABLE",
"NOT_AVAILABLE"
]
},
"enrichment_type": {
"type": "string",
"description": "Enrichment type assigned to the variant.",
"example": "fashion",
"enum": [
"none",
"fashion"
]
},
"catalog_id": {
"type": "integer",
"description": "Catalog identifier.",
"format": "int64",
"example": 123
},
"source_creation_time": {
"type": "integer",
"description": "SOURCE data creation timestamp in milliseconds. Present when SOURCE data is available.",
"format": "int64",
"example": 1783502993000
},
"source_update_time": {
"type": "integer",
"description": "SOURCE data last update timestamp in milliseconds. Present when SOURCE data is available.",
"format": "int64",
"example": 1783503093000
},
"enriched_creation_time": {
"type": "integer",
"description": "ENRICHED data creation timestamp in milliseconds. Present when ENRICHED data is available.",
"format": "int64",
"example": 1783503193000
},
"enriched_update_time": {
"type": "integer",
"description": "ENRICHED data last update timestamp in milliseconds. Present when ENRICHED data is available.",
"format": "int64",
"example": 1783503293000
},
"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"
},
"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"
]
},
"categories": {
"type": "array",
"description": "Categories of the product, ordered from broadest to most specific.",
"example": [
"ladies",
"dresses",
"short"
],
"items": {
"type": "string",
"description": "Categories of the product, ordered from broadest to most specific.",
"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\"]"
}
},
"variant_title": {
"type": "string",
"description": "Human-readable title of the variant.",
"example": "Basic t-shirt, size L"
},
"style_title": {
"type": "string",
"description": "Human-readable title of the style.",
"example": "Black basic t-shirt"
},
"product_title": {
"type": "object",
"additionalProperties": {
"type": "string",
"description": "Localized product title keyed by BCP 47 locale or '*' fallback.",
"example": "{\"en-GB\":\"Summer dress\",\"de-DE\":\"Sommerkleid\",\"fr-FR\":\"Robe d'ete\",\"*\":\"Summer dress\"}"
},
"description": "Localized product title keyed by BCP 47 locale or '*' fallback.",
"example": {
"en-GB": "Summer dress",
"de-DE": "Sommerkleid",
"fr-FR": "Robe d'ete",
"*": "Summer dress"
}
},
"product_description": {
"type": "object",
"additionalProperties": {
"type": "string",
"description": "Localized product description keyed by BCP 47 locale or '*' fallback.",
"example": "{\"en-GB\":\"Light dress\",\"de-DE\":\"Leichtes Kleid\"}"
},
"description": "Localized product description keyed by BCP 47 locale or '*' fallback.",
"example": {
"en-GB": "Light dress",
"de-DE": "Leichtes Kleid"
}
},
"image_url": {
"type": "array",
"description": "List of product image URLs.",
"example": [
"https://cdn.com/photo1.jpg",
"https://cdn.com/photo2.jpg",
"https://cdn.com/photo3.jpg"
],
"items": {
"type": "string",
"description": "List of product image URLs.",
"example": "[\"https://cdn.com/photo1.jpg\",\"https://cdn.com/photo2.jpg\",\"https://cdn.com/photo3.jpg\"]"
}
},
"pdp_url": {
"type": "object",
"additionalProperties": {
"type": "string",
"description": "Localized product detail page URL keyed by BCP 47 locale or '*' fallback.",
"example": "{\"en-GB\":\"https://shop.example/gb/basic-tshirt-001\",\"de-DE\":\"https://shop.example/de/basic-tshirt-001\"}"
},
"description": "Localized product detail page URL keyed by BCP 47 locale or '*' fallback.",
"example": {
"en-GB": "https://shop.example/gb/basic-tshirt-001",
"de-DE": "https://shop.example/de/basic-tshirt-001"
}
},
"season_code": {
"type": "boolean",
"description": "Indicates whether the product belongs to a seasonal assortment.",
"example": true
},
"old_price": {
"type": "object",
"additionalProperties": {
"type": "number",
"description": "Former selling price keyed by ISO 3166-1 alpha-2 country code or '*' fallback."
},
"description": "Former selling price keyed by ISO 3166-1 alpha-2 country code or '*' fallback.",
"example": {
"US": 39.99,
"GB": 34.99
}
},
"set_id": {
"type": "string",
"description": "Identifier for products sold as a set.",
"example": "BIKINI-SET-001"
},
"extra_id": {
"type": "object",
"additionalProperties": {
"type": "string",
"description": "Additional localized or country-specific product identifier.",
"example": "{\"US\":\"EXTRA-US-1001\",\"GB\":\"EXTRA-GB-1001\"}"
},
"description": "Additional localized or country-specific product identifier.",
"example": {
"US": "EXTRA-US-1001",
"GB": "EXTRA-GB-1001"
}
},
"ancillary_product_code": {
"type": "string",
"description": "Additional product identifier.",
"example": "ANC-1001"
},
"min_age": {
"type": "integer",
"description": "Minimal age in months for children's wear.",
"format": "int32",
"example": 12
},
"max_age": {
"type": "integer",
"description": "Maximum age in months for children's wear.",
"format": "int32",
"example": 24
},
"best_model_image": {
"type": "string",
"description": "Best model image URL.",
"example": "https://cdn.com/best_model_image.jpg"
},
"best_product_image": {
"type": "string",
"description": "Best product-only image URL.",
"example": "https://cdn.com/best_product_image.jpg"
}
},
"description": "Flat variant payload based on the unified product catalog schema, where:
- predefined SOURCE attributes are documented as fields here.
- custom SOURCE attributes are added dynamically on top-level as fields.
- ENRICHED attributes are added dynamically on top-level as fields.
- SOURCE attributes have no prefix, while ENRICHED attributes have the 'fashion_' prefix.
",
"example": [
{
"variant_id": "V-1001",
"product_id": "P-500",
"style_id": "S-42",
"status": {
"value": 1,
"label": "active"
},
"availability": {
"value": true,
"label": "available"
},
"catalog_id": 12345,
"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"
},
{
"variant_id": "V-1002",
"product_id": "P-500",
"style_id": "S-42",
"status": {
"value": 1,
"label": "active"
},
"availability": {
"value": true,
"label": "available"
},
"catalog_id": 12345,
"source_creation_time": 1783503393000,
"source_update_time": 1783503493000,
"enriched_creation_time": 1783503593000,
"enriched_update_time": 1783503693000,
"color": {
"en-GB": "Navy Blue",
"de-DE": "Marineblau",
"fr-FR": "Bleu marine"
},
"price": {
"US": 29.99,
"GB": 24.99
},
"size": {
"US": "M",
"EU": "38"
},
"fashion_material": "leather",
"fashion_season": "summer"
}
]
}
},
"securitySchemes": {
"Keycloak": {
"type": "http",
"scheme": "bearer",
"bearerFormat": "JWT"
}
}
}
}
````