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.

Add a new variant or add missing data to an existing variant

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

Catalog identifier where the variant should be added.

Body parameters

Variant attributes to add. The payload must include variant_id.

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

Flat request payload for adding a SOURCE variant, where:
- predefined SOURCE attributes are documented as fields here.
- custom SOURCE attributes are added dynamically on top-level as fields.
- ENRICHED attributes are not accepted by this endpoint; this endpoint writes SOURCE data only.
The field variant_id is always required. product_id should be provided when creating a new variant.

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
status
integer (int32)

Variant status value: 0 = pre_order, 1 = active, 2 = discontinued.

Valid values[ 0, 1, 2 ]
Example1
availability
boolean

Variant availability value.

Exampletrue
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_id
string Required

Client-defined unique identifier of the purchasable variant. Maximum length is 255 characters.

ExampleV-1001
product_id
string

Identifier used for grouping all variants belonging to the same product. Provide it when creating a new variant.

ExampleP-500
style_id
string

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

ExampleS-1000
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
Responses
202

Variant add accepted for processing

{
  "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
  }
}
Expand All
object
variant_id
string
ExampleV-1001
catalog_id
integer (int64)
Example123
status
string
Valid values[ "accepted", "failed" ]
Exampleaccepted
message
string
ExampleVariant add accepted for processing
event_id
string

Unique generated UUID assigned to the event and preserved throughout its whole lifecycle. The event_id is used in logs and is also sent back to the client with webhook events when webhooks are configured, so clients are advised to log/save it on their side.

Example550e8400-e29b-41d4-a716-446655440000
operation
string
Valid values[ "add", "upsert", "partial_update", "delete", "delete_attributes", "add_existing_only", "overwrite", "overwrite_existing_only", "update", "update_existing_only", "update_localized_attribute", "update_localized_attribute_existing_only", "clean" ]
Exampleadd
accepted_at
integer (int64)
Example1783502993000
accepted_attributes
object
Example{ "color": { "en-GB": "Navy Blue", "de-DE": "Marineblau", "fr-FR": "Bleu marine" }, "size": { "US": "S", "EU": "36" } }
property*
object additionalProperties
Example{ "color": { "en-GB": "Navy Blue", "de-DE": "Marineblau", "fr-FR": "Bleu marine" }, "size": { "US": "S", "EU": "36" } }
skipped_attributes
object (SkippedAttributesDTO)
non_existing_attributes
Array of string
Example[ "custom_attribute_abc" ]
string
Example["custom_attribute_abc"]
inactive_attributes
Array of string
Example[ "custom_attribute_def" ]
string
Example["custom_attribute_def"]
invalid_data_type_attributes
object
Example{ "price": "price map value must be a number", "gtin": "gtin field must be 8-14 digits", "min_age": "min_age value must be a number" }
property*
string additionalProperties
Example{"price":"price map value must be a number","gtin":"gtin field must be 8-14 digits","min_age":"min_age value must be a number"}
400

Variant add was rejected during validation.

{
  "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": {}
}
Expand All
object
variant_id
string
ExampleV-1001
catalog_id
integer (int64)
Example123
status
string
Valid values[ "accepted", "failed" ]
Exampleaccepted
message
string
ExampleVariant add accepted for processing
event_id
string

Unique generated UUID assigned to the event and preserved throughout its whole lifecycle. The event_id is used in logs and is also sent back to the client with webhook events when webhooks are configured, so clients are advised to log/save it on their side.

Example550e8400-e29b-41d4-a716-446655440000
operation
string
Valid values[ "add", "upsert", "partial_update", "delete", "delete_attributes", "add_existing_only", "overwrite", "overwrite_existing_only", "update", "update_existing_only", "update_localized_attribute", "update_localized_attribute_existing_only", "clean" ]
Exampleadd
accepted_at
integer (int64)
Example1783502993000
accepted_attributes
object
Example{ "color": { "en-GB": "Navy Blue", "de-DE": "Marineblau", "fr-FR": "Bleu marine" }, "size": { "US": "S", "EU": "36" } }
property*
object additionalProperties
Example{ "color": { "en-GB": "Navy Blue", "de-DE": "Marineblau", "fr-FR": "Bleu marine" }, "size": { "US": "S", "EU": "36" } }
skipped_attributes
object (SkippedAttributesDTO)
non_existing_attributes
Array of string
Example[ "custom_attribute_abc" ]
string
Example["custom_attribute_abc"]
inactive_attributes
Array of string
Example[ "custom_attribute_def" ]
string
Example["custom_attribute_def"]
invalid_data_type_attributes
object
Example{ "price": "price map value must be a number", "gtin": "gtin field must be 8-14 digits", "min_age": "min_age value must be a number" }
property*
string additionalProperties
Example{"price":"price map value must be a number","gtin":"gtin field must be 8-14 digits","min_age":"min_age value must be a number"}
500

Variant add failed unexpectedly.

{
  "message": "Unexpected error while processing request",
  "httpStatus": 500,
  "errorCode": "500 Internal Server Error",
  "timestamp": "2026-07-08T12:00:00Z"
}
Expand All
OneOf
VariantOperationResponseDTO
object (VariantOperationResponseDTO)
variant_id
string
ExampleV-1001
catalog_id
integer (int64)
Example123
status
string
Valid values[ "accepted", "failed" ]
Exampleaccepted
message
string
ExampleVariant add accepted for processing
event_id
string

Unique generated UUID assigned to the event and preserved throughout its whole lifecycle. The event_id is used in logs and is also sent back to the client with webhook events when webhooks are configured, so clients are advised to log/save it on their side.

Example550e8400-e29b-41d4-a716-446655440000
operation
string
Valid values[ "add", "upsert", "partial_update", "delete", "delete_attributes", "add_existing_only", "overwrite", "overwrite_existing_only", "update", "update_existing_only", "update_localized_attribute", "update_localized_attribute_existing_only", "clean" ]
Exampleadd
accepted_at
integer (int64)
Example1783502993000
accepted_attributes
object
Example{ "color": { "en-GB": "Navy Blue", "de-DE": "Marineblau", "fr-FR": "Bleu marine" }, "size": { "US": "S", "EU": "36" } }
property*
object additionalProperties
Example{ "color": { "en-GB": "Navy Blue", "de-DE": "Marineblau", "fr-FR": "Bleu marine" }, "size": { "US": "S", "EU": "36" } }
skipped_attributes
object (SkippedAttributesDTO)
non_existing_attributes
Array of string
Example[ "custom_attribute_abc" ]
string
Example["custom_attribute_abc"]
inactive_attributes
Array of string
Example[ "custom_attribute_def" ]
string
Example["custom_attribute_def"]
invalid_data_type_attributes
object
Example{ "price": "price map value must be a number", "gtin": "gtin field must be 8-14 digits", "min_age": "min_age value must be a number" }
property*
string additionalProperties
Example{"price":"price map value must be a number","gtin":"gtin field must be 8-14 digits","min_age":"min_age value must be a number"}
ErrorResponse
object (ErrorResponse)
message
string
httpStatus
integer (int32)
errorCode
string
timestamp
string (date-time)