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 its ID from the specified catalog

Updated
  • 5 minute(s) read
Prev Next
Get
/api/product-catalog/v1/catalogs/{catalogId}/variants/{variantId}
Security
HTTP
Type bearer
Path parameters
catalogId
integer (int64) Required

Catalog identifier that contains the variant.

variantId
stringRequired

Variant identifier to retrieve from the catalog.

Query parameters
activeStatusSearch
string

Controls whether active attributes, inactive attributes, or all attributes are included in the returned variant data. Defaults to ALL.

Valid values[ "ACTIVE_ONLY", "INACTIVE_ONLY", "ALL" ]
Default"ALL"
catalogType
string

Selects which product data layer to query. Defaults to COMBINED.

Valid values[ "SOURCE", "ENRICHED", "COMBINED" ]
Default"COMBINED"
Responses
200

Variant found

{
  "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"
}
Expand All
object

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" } ]
variant_id
string

Client-defined unique identifier of the purchasable variant.

ExampleV-1001
product_id
string

Identifier used for grouping all variants belonging to the same product.

ExampleP-500
style_id
string

Groups variants that share colour or style but differ by option attributes such as size.

ExampleS-1000
status
string
Valid values[ "PRE_ORDER", "ACTIVE", "DISCONTINUED" ]
Example{"value":1,"label":"active"}
availability
string
Valid values[ "AVAILABLE", "NOT_AVAILABLE" ]
Example{"value":true,"label":"available"}
catalog_id
integer (int64)

Catalog identifier.

Example123
source_creation_time
integer (int64)

SOURCE data creation timestamp in milliseconds. Present when SOURCE data is available.

Example1783502993000
source_update_time
integer (int64)

SOURCE data last update timestamp in milliseconds. Present when SOURCE data is available.

Example1783503093000
enriched_creation_time
integer (int64)

ENRICHED data creation timestamp in milliseconds. Present when ENRICHED data is available.

Example1783503193000
enriched_update_time
integer (int64)

ENRICHED data last update timestamp in milliseconds. Present when ENRICHED data is available.

Example1783503293000
brand
string

Product brand name.

ExampleAnnTaylor
price
object

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 }
property*
number additionalProperties

Current selling price keyed by ISO 3166-1 alpha-2 country code or '*' fallback.

currency
object

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" }
property*
string additionalProperties

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
object

Size keyed by ISO 3166-1 alpha-2 country code or '*' fallback.

Example{ "US": "S", "GB": "8", "EU": "36" }
property*
string additionalProperties

Size keyed by ISO 3166-1 alpha-2 country code or '*' fallback.

Example{"US":"S","GB":"8","EU":"36"}
color
object

Localized colour keyed by BCP 47 locale or '*' fallback.

Example{ "en-GB": "Navy Blue", "de-DE": "Marineblau", "fr-FR": "Bleu marine" }
property*
string additionalProperties

Localized colour keyed by BCP 47 locale or '*' fallback.

Example{"en-GB":"Navy Blue","de-DE":"Marineblau","fr-FR":"Bleu marine"}
mpn
string

Manufacturer Part Number. Maximum length is 70 characters.

ExampleDRESS-BLK-M-2023
gtin
string

Global Trade Item Number. Expected length is 8-14 digits.

Example1234567890123
material
string

Material of the product.

Examplecotton
gender
string

Gender value for fashion catalogs.

Valid values[ "female", "male", "girls", "boys", "unisex" ]
Examplefemale
category
Array of string

Category hierarchy.

Example[ "ladies", "dresses", "short" ]
string

Category hierarchy.

Example["ladies","dresses","short"]
locale
Array of string

Supported locales for this variant.

Example[ "en-GB", "de-DE" ]
string

Supported locales for this variant.

Example["en-GB","de-DE"]
ean
string

Standardised article number.

Example8076809513456
multipack
integer (int32)

Multipack quantity.

Example3
collaboration
Array of string

Retailer-specific collaboration values.

Example[ "designer-capsule", "summer-edit" ]
string

Retailer-specific collaboration values.

Example["designer-capsule","summer-edit"]
variant_title
string

Human-readable title of the variant.

ExampleBasic t-shirt, size L
style_title
string

Human-readable title of the style.

ExampleBlack basic t-shirt
product_title
object

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" }
property*
string additionalProperties

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
object

Localized product description keyed by BCP 47 locale or '*' fallback.

Example{ "en-GB": "Light dress", "de-DE": "Leichtes Kleid" }
property*
string additionalProperties

Localized product description keyed by BCP 47 locale or '*' fallback.

Example{"en-GB":"Light dress","de-DE":"Leichtes Kleid"}
image_url
Array of string

List of product image URLs.

Example[ "https://cdn.com/photo1.jpg", "https://cdn.com/photo2.jpg", "https://cdn.com/photo3.jpg" ]
string

List of product image URLs.

Example["https://cdn.com/photo1.jpg","https://cdn.com/photo2.jpg","https://cdn.com/photo3.jpg"]
pdp_url
object

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" }
property*
string additionalProperties

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
boolean

Indicates whether the product belongs to a seasonal assortment.

Exampletrue
old_price
object

Former selling price keyed by ISO 3166-1 alpha-2 country code or '*' fallback.

Example{ "US": 39.99, "GB": 34.99 }
property*
number additionalProperties

Former selling price keyed by ISO 3166-1 alpha-2 country code or '*' fallback.

set_id
string

Identifier for products sold as a set.

ExampleBIKINI-SET-001
extra_id
object

Additional localized or country-specific product identifier.

Example{ "US": "EXTRA-US-1001", "GB": "EXTRA-GB-1001" }
property*
string additionalProperties

Additional localized or country-specific product identifier.

Example{"US":"EXTRA-US-1001","GB":"EXTRA-GB-1001"}
ancillary_product_code
string

Additional product identifier.

ExampleANC-1001
min_age
integer (int32)

Minimal age in months for children's wear.

Example12
max_age
integer (int32)

Maximum age in months for children's wear.

Example24
best_model_image
string

Best model image URL.

Examplehttps://cdn.com/best_model_image.jpg
best_product_image
string

Best product-only image URL.

Examplehttps://cdn.com/best_product_image.jpg
204

Variant was not found for the requested catalog and filters.

400

Invalid query parameters or catalog attribute configuration.

{
  "message": "Cannot specify both lastId and firstId",
  "httpStatus": 400,
  "errorCode": "400 Bad Request",
  "timestamp": "2026-07-08T12:00:00Z"
}
object
message
string
httpStatus
integer (int32)
errorCode
string
timestamp
string (date-time)
404

Catalog was not found.

{
  "message": "Product feed not found for companyId: 456 and feedId: 123",
  "httpStatus": 404,
  "errorCode": "404 Not Found",
  "timestamp": "2026-07-08T12:00:00Z"
}
object
message
string
httpStatus
integer (int32)
errorCode
string
timestamp
string (date-time)
500

Unexpected error while fetching variant data.

{
  "message": "Unexpected error while processing request",
  "httpStatus": 500,
  "errorCode": "500 Internal Server Error",
  "timestamp": "2026-07-08T12:00:00Z"
}
object
message
string
httpStatus
integer (int32)
errorCode
string
timestamp
string (date-time)