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.

Bulk partial update variants

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

Catalog identifier containing the variants to update.

Body parameters

List of partial variant payloads. Only provided fields are changed for each variant.

Array of object
object

Flat request payload for bulk partially updating 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.
Only the provided fields will be updated. If the variant doesn't exist, no action is taken.

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.

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
variant_id
string Required

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

ExampleV-1001
Responses
202

Variant partial update accepted for processing

{
  "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": []
}
Expand All
object
operation_id
string
Example350e8400-dgwe-41d4-a716-546655440000
status
string
Valid values[ "accepted", "failed" ]
Exampleaccepted
catalog_id
integer (int64)
Example123
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
total_variants_success
integer (int32)
Example1
total_variants_failed
integer (int32)
Example1
message
string
ExampleVariant add accepted for processing"
accepted_at
string (date-time)
variant_events_success
Array of object (VariantEventResult)
object
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
variant_id
string
ExampleV-1001
status
string
Valid values[ "accepted", "failed" ]
Exampleaccepted
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"}
failure_reason
string

Filled in only when variant could not be processed.

Exampleprice mandatory field cannot be deleted
variant_events_failed
Array of object (VariantEventResult)
object
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
variant_id
string
ExampleV-1001
status
string
Valid values[ "accepted", "failed" ]
Exampleaccepted
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"}
failure_reason
string

Filled in only when variant could not be processed.

Exampleprice mandatory field cannot be deleted
400

Bulk partial update payload list is missing or null.

{
  "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": []
}
Expand All
object
operation_id
string
Example350e8400-dgwe-41d4-a716-546655440000
status
string
Valid values[ "accepted", "failed" ]
Exampleaccepted
catalog_id
integer (int64)
Example123
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
total_variants_success
integer (int32)
Example1
total_variants_failed
integer (int32)
Example1
message
string
ExampleVariant add accepted for processing"
accepted_at
string (date-time)
variant_events_success
Array of object (VariantEventResult)
object
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
variant_id
string
ExampleV-1001
status
string
Valid values[ "accepted", "failed" ]
Exampleaccepted
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"}
failure_reason
string

Filled in only when variant could not be processed.

Exampleprice mandatory field cannot be deleted
variant_events_failed
Array of object (VariantEventResult)
object
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
variant_id
string
ExampleV-1001
status
string
Valid values[ "accepted", "failed" ]
Exampleaccepted
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"}
failure_reason
string

Filled in only when variant could not be processed.

Exampleprice mandatory field cannot be deleted
422

Bulk partial update payload exceeds the maximum allowed size of 1000 variants.

{
  "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": []
}
Expand All
object
operation_id
string
Example350e8400-dgwe-41d4-a716-546655440000
status
string
Valid values[ "accepted", "failed" ]
Exampleaccepted
catalog_id
integer (int64)
Example123
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
total_variants_success
integer (int32)
Example1
total_variants_failed
integer (int32)
Example1
message
string
ExampleVariant add accepted for processing"
accepted_at
string (date-time)
variant_events_success
Array of object (VariantEventResult)
object
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
variant_id
string
ExampleV-1001
status
string
Valid values[ "accepted", "failed" ]
Exampleaccepted
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"}
failure_reason
string

Filled in only when variant could not be processed.

Exampleprice mandatory field cannot be deleted
variant_events_failed
Array of object (VariantEventResult)
object
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
variant_id
string
ExampleV-1001
status
string
Valid values[ "accepted", "failed" ]
Exampleaccepted
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"}
failure_reason
string

Filled in only when variant could not be processed.

Exampleprice mandatory field cannot be deleted
500

Unexpected error while processing bulk partial update.

{
  "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)