Partially update an existing variant

Updated

6 minute(s) read

Prev Next

Patch

/api/product-catalog/v1/catalogs/{catalogId}/variants/{variantId}

Security

HTTP

Type bearer

Path parameters

catalogId

integer (int64) Required

Catalog identifier containing the variant to update.

variantId

stringRequired

Variant identifier to partially update.

Body parameters

Variant attributes to update. Only provided fields are changed.

{
  "status": 2,
  "price": {
    "US": 39.99,
    "GB": 34.99
  }
}

Expand All

object

Flat request payload for 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

Responses

202

Variant partial update accepted for processing

{
  "variant_id": "V-1001",
  "catalog_id": 123,
  "status": "accepted",
  "message": "Variant partial update accepted for processing",
  "event_id": "550e8400-e29b-41d4-a716-446655440000",
  "operation": "partial_update",
  "accepted_at": 1783502993000,
  "accepted_attributes": {
    "variant_id": "V-1001",
    "status": "discontinued",
    "price": {
      "US": 39.99,
      "GB": 34.99
    }
  }
}

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 partial update was rejected during validation.

{
  "variant_id": "V-1001",
  "catalog_id": 123,
  "status": "failed",
  "message": "Variant partial update failed: status value 'archived' is not a valid VariantStatus",
  "operation": "partial_update",
  "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

Example550e8400-e29b-41d4-a716-446655440000

operation

string

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 partial update 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

Example550e8400-e29b-41d4-a716-446655440000

operation

string

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)

Was this article helpful?

Documentation Index

Partially update an existing variant