Adding or updating a product variation

Learn how to add or update a product variation

You can add or update a product variation for a base product. Both calls result in the same response when specifying the same productId. As long as you know the productId for the product variation, you only need to update that product variation.

When adding or updating a product variation, note that:

• The response returns an error if you add an attribute to a product variation that does not exist in the base product.

• The request automatically adds the locales object from the base product to each product variation. The response returns an error if the locales are inconsistent between the base product and the product variations. For example:

  • If en_GB and en_US exist in the base product and only en_US exists in the product variation, the request will copy en_GB to the product variation.

  • if en_GB and en_US exist in the base product and ja_JP exists in the product variation, the request will return an error in the response

Adding a product variation to a base product

The following POST /v1/products/{baseProductId or baseERID}/variations request creates a product variation for an existing product. To add a product variation, you must provide either the base product's productId or ERID.

Do not use this request to change the default locale in the payload. Changing the default locale in the payload of this request will result in an error. See Adding or updating a product's locale for instructions on changing the default locale.

cURL

The following example adds a product variation to a base product with a baseProductId. It also adds a product variation without setting any data. See the variations resource for a description of the attributes.

curl --location --request POST 'https://api.digitalriver.com/v1/products/{baseProductId}/variations' \
--header 'Authorization: Bearer <API_key>' \
...
--data-raw '{
  "varyingAttributes": [
    {
      "attributeName": "color",
      "attributeValue": "red"
    },
    {
      "attributeName": "size",
      "attributeValue": "large"
    }
  ],
  "deploymentRequiredChanges": {},
  "liveChanges": {},
  "localizations": []
}'

An ERID request requires the x-erid-as-pid=true header. It also adds a product variation without setting any data.

curl --location --request POST 'https://api.digitalriver.com/v1/products/{baseERID}/variations' \
--header 'Authorization: Bearer <API_key>' \
--header 'header x-erid-as-pid=true' \
...
--data-raw '{
  "varyingAttributes": [
    {
      "attributeName": "color",
      "attributeValue": "red"
    },
    {
      "attributeName": "size",
      "attributeValue": "large"
    }
  ],
  "deploymentRequiredChanges": {},
  "liveChanges": {},
  "localizations": []
}'

202 Accepted response

The request returns a task identifier (taskId) in the asynchronous response.

{
    "taskId": "eac67608-2fd6-4156-88f1-8ecb98aad9b0",
    "requestType": "UPDATE_VARIATION",
    "taskStatus": "PUBLISHED",
    "receivedTime": "2022-08-11T21:59:28.089Z"
}

Use the taskId in the response to verify the successful completion of the request. You can also verify the successful completion of the task by checking the product history in Global Commerce. Note that there may be a delay before these changes appear in Global Commerce.

You must add an attribute to the base product before you add the attribute to the product variation. An error occurs when the attributes don't match the locale data in the base product. Use the POST /v1/products/{baseProductId or baseERID}/variations request to add an attribute such as locale to a product variation.

Updating a specific product variation

The following POST /v1/products/{baseProductId or baseERID}/variations/{productVariationId or variationERID} request updates on any supported attribute, such as the locale, for a specific product variation. To update a specific product variation, you must provide either the product variation identifier (productVariationId) or the variation ERID (variationERID).

cURL

The following example updates a specific product variation with a productVariationId. See the variations resource for a description of the attributes.

curl --location --request POST 'https://api.digitalriver.com/v1/products/{baseProductId}/variations/{productVariationId}' \
--header 'Authorization: Bearer <API_key>' \
...
--data-raw '{
 "localizations": [
    {
      "locale": "en_US",
      "isDefault": "true",
      "groups": [
        {
          "groupId": "11",
          "groupName": "Software",
          "attributes": {
            "name": "UpdatedVariation_-{{uuid}}",
            "displayName": "UpdatedVariation_-display-{{uuid}}",
            "sku": "Variation_-sku-{{uuid}}",
            "manufacturer": "Variation_manufacturer-20220308-01",
            "mfrPartNumber": "Variation_mfrPartNumber-20220308-01",
            "returnMethod": "LOD",
            "productReturnMethod": "ByAgentAndSelfService",
            "taxableUnspscCode": "43210000",
            "taxableProductCode": "4321_C",
            "isViewable": true,
            "isOrderable": true,
            "nonSolr": true,
            "shortDescription": "Variation_shortDescription-{{uuid}}",
            "longDescription": "Variation_longDescription-{{uuid}}",
            "keywords": "Variation_keywords-{{uuid}}",
            "emailAddlInfoText": "emailAddlInfoText-{{uuid}}",
            "emailAddlInfo": "emailAddlInfo-{{uuid}}",
            "confirmAddlInfo": "confirmAddlInfo-{{uuid}}"
          }           
        },
        {
          "groupId": "16",
          "groupName": "Export Controls",
          "attributes": {
            "eccn": "3A992",
            "ccats": "display-name-1234test",
            "licenseException": "APP",
            "harmonizeCode": "hcode",
            "manufactureCountry": "US"
          }
        }   
      ]
    }
    ]   
}'

An ERID request requires the x-erid-as-pid=true header.

curl --location --request POST 'https://api.digitalriver.com/v1/products/{baseERID}/variations/{variationERID}' \
--header 'Authorization: Bearer <API_key>' \
--header 'header x-erid-as-pid=true' \
...
--data-raw '{
 "localizations": [
    {
      "locale": "en_US",
      "isDefault": "true",
      "groups": [
        {
          "groupId": "11",
          "groupName": "Software",
          "attributes": {
            "name": "UpdatedVariation_-{{uuid}}",
            "displayName": "UpdatedVariation_-display-{{uuid}}",
            "sku": "Variation_-sku-{{uuid}}",
            "manufacturer": "Variation_manufacturer-20220308-01",
            "mfrPartNumber": "Variation_mfrPartNumber-20220308-01",
            "returnMethod": "LOD",
            "productReturnMethod": "ByAgentAndSelfService",
            "taxableUnspscCode": "43210000",
            "taxableProductCode": "4321_C",
            "isViewable": true,
            "isOrderable": true,
            "nonSolr": true,
            "shortDescription": "Variation_shortDescription-{{uuid}}",
            "longDescription": "Variation_longDescription-{{uuid}}",
            "keywords": "Variation_keywords-{{uuid}}",
            "emailAddlInfoText": "emailAddlInfoText-{{uuid}}",
            "emailAddlInfo": "emailAddlInfo-{{uuid}}",
            "confirmAddlInfo": "confirmAddlInfo-{{uuid}}"
          }           
        },
        {
          "groupId": "16",
          "groupName": "Export Controls",
          "attributes": {
            "eccn": "3A992",
            "ccats": "display-name-1234test",
            "licenseException": "APP",
            "harmonizeCode": "hcode",
            "manufactureCountry": "US"
          }
        }   
      ]
    }
    ]   
}'

202 Accepted response

The request returns a task identifier (taskId) in the asynchronous response.

{
    "taskId": "9e3dbe0e-98fc-4c88-8868-03fdde5fcdb6",
    "requestType": "UPDATE_VARIATION",
    "taskStatus": "PUBLISHED",
    "receivedTime": "2022-11-28T21:02:58.187Z"
}

Use the taskId in the response to verify the successful completion of the request. You can also verify the successful completion of the task by checking the product history in Global Commerce. Note that there may be a delay before these changes appear in Global Commerce.

Add the new attributes and replace existing attributes in the payload. For example, you can add or replace locales for a product variation.

You must add an attribute to the base product before you add the attribute to the product variation. An error occurs when the attributes don't match the locale data in the base product. Use the POST /v1/products/{baseProductId or baseERID}/variations request to add an attribute such as locale to a product variation.

Updating a specific product variation for a base product

The following POST /v1/products/{baseProductId or baseERID}/variations/{productVariationId or variationERID} request updates on any supported attribute, such as the locale, for a product variation associated with a particular base product ID. To update a specific product variation, you must provide either a unique productId or ERID for both the base product and product variation.

The base product and the variation must use the same product identifier type. For example, the base product and the variation both use productId. You cannot use productIds and ERIDs interchangeably when updating a product variation for a specific base product.

cURL

The following example updates a specific product variation with a productId for a base product. See the variations resource for a description of the attributes.

curl --location --request POST 'https://api.digitalriver.com/v1/products/{baseProductId}/variations/{productVariationId}' \
--header 'Authorization: Bearer <API_key>' \
...
--data-raw '{
 "localizations": [
    {
      "locale": "en_US",
      "isDefault": "true",
      "groups": [
        {
          "groupId": "11",
          "groupName": "Software",
          "attributes": {
            "name": "UpdatedVariation_-{{uuid}}",
            "displayName": "UpdatedVariation_-display-{{uuid}}",
            "sku": "Variation_-sku-{{uuid}}",
            "manufacturer": "Variation_manufacturer-20220308-01",
            "mfrPartNumber": "Variation_mfrPartNumber-20220308-01",
            "returnMethod": "LOD",
            "productReturnMethod": "ByAgentAndSelfService",
            "taxableUnspscCode": "43210000",
            "taxableProductCode": "4321_C",
            "isViewable": true,
            "isOrderable": true,
            "nonSolr": true,
            "shortDescription": "Variation_shortDescription-{{uuid}}",
            "longDescription": "Variation_longDescription-{{uuid}}",
            "keywords": "Variation_keywords-{{uuid}}",
            "emailAddlInfoText": "emailAddlInfoText-{{uuid}}",
            "emailAddlInfo": "emailAddlInfo-{{uuid}}",
            "confirmAddlInfo": "confirmAddlInfo-{{uuid}}"
          }           
        },
        {
          "groupId": "16",
          "groupName": "Export Controls",
          "attributes": {
            "eccn": "3A992",
            "ccats": "display-name-1234test",
            "licenseException": "APP",
            "harmonizeCode": "hcode",
            "manufactureCountry": "US"
          }
        }   
      ]
    }
    ]   
}'

An ERID request requires the x-erid-as-pid=true header.

curl --location --request POST 'https://api.digitalriver.com/v1/products/{baseERID}/variations/{variationERID}' \
--header 'Authorization: Bearer <API_key>' \
--header 'header x-erid-as-pid=true' \
...
--data-raw '{
 "localizations": [
    {
      "locale": "en_US",
      "isDefault": "true",
      "groups": [
        {
          "groupId": "11",
          "groupName": "Software",
          "attributes": {
            "name": "UpdatedVariation_-{{uuid}}",
            "displayName": "UpdatedVariation_-display-{{uuid}}",
            "sku": "Variation_-sku-{{uuid}}",
            "manufacturer": "Variation_manufacturer-20220308-01",
            "mfrPartNumber": "Variation_mfrPartNumber-20220308-01",
            "returnMethod": "LOD",
            "productReturnMethod": "ByAgentAndSelfService",
            "taxableUnspscCode": "43210000",
            "taxableProductCode": "4321_C",
            "isViewable": true,
            "isOrderable": true,
            "nonSolr": true,
            "shortDescription": "Variation_shortDescription-{{uuid}}",
            "longDescription": "Variation_longDescription-{{uuid}}",
            "keywords": "Variation_keywords-{{uuid}}",
            "emailAddlInfoText": "emailAddlInfoText-{{uuid}}",
            "emailAddlInfo": "emailAddlInfo-{{uuid}}",
            "confirmAddlInfo": "confirmAddlInfo-{{uuid}}"
          }           
        },
        {
          "groupId": "16",
          "groupName": "Export Controls",
          "attributes": {
            "eccn": "3A992",
            "ccats": "display-name-1234test",
            "licenseException": "APP",
            "harmonizeCode": "hcode",
            "manufactureCountry": "US"
          }
        }   
      ]
    }
    ]   
}'

202 Accepted

The request returns a task identifier (taskId) in the asynchronous response.

{
    "taskId": "9e3dbe0e-98fc-4c88-8868-03fdde5fcdb6",
    "requestType": "UPDATE_VARIATION",
    "taskStatus": "PUBLISHED",
    "receivedTime": "2022-11-28T21:02:58.187Z"
}

Use the taskId in the response to verify the successful completion of the request. You can also verify the successful completion of the task by checking the product history in Global Commerce. Note that there may be a delay before these changes appear in Global Commerce.

Add the new attributes and replace existing attributes in the payload. For example, you can add or replace locales for a product variation.

You must add an attribute to the base product before you add the attribute to the product variation. An error occurs when the attributes don't match the locale data in the base product. Use the POST /v1/products/{baseProductId}/variations request to add an attribute such as locale to a product variation.