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.

Create or fully replace a variant

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

Catalog identifier where the variant should be created or replaced.

variantId
stringRequired

Variant identifier to create or fully replace.

Body parameters

Complete variant payload that will replace existing variant data.

{
  "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 creating or fully replacing 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.
If the variant doesn't exist, it will be created. If it exists, all data will be completely replaced with the provided payload.

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"]
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 upsert accepted for processing

{
  "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"
  }
}
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 upsert was rejected during validation.

{
  "variant_id": "V-1001",
  "catalog_id": 123,
  "status": "failed",
  "message": "Variant upsert failed: missingMandatoryFields=[price]",
  "operation": "upsert",
  "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 upsert 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)