> For the complete documentation index, see [llms.txt](https://docs.digitalriver.com/commerce-api/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.digitalriver.com/commerce-api/admin-apis/product-management/manage-products-asynchronous-api/adding-or-updating-a-product-variation.md). # Adding or updating a product variation You can [add ](#adding-a-product-variation-to-a-base-product)or [update a product variation](#updating-a-specific-product-variation-for-a-base-product) 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`](https://docs.digitalriver.com/commerce-api-references/admin-apis/product-management/manage-products-asynchronous-api#v1-products-baseproductid-variations-variationid) request creates a product variation for an existing product. To add a product variation, you must provide either the base product's [`productId` ](https://docs.digitalriver.com/commerce-api-references/commerce-api-reference-guide/api-structure/product-identifier)or [`ERID`](https://docs.digitalriver.com/commerce-api-references/commerce-api-reference-guide/api-structure/product-external-reference-identifier-erid).[ ](https://app.gitbook.com/o/-LqC_Nsz4Z-JxICCsFw3/s/-LzlYMEYC0GeLSgnsft6/~/changes/1417/admin-apis/product-management/manage-products-asynchronous-api/adding-or-updating-a-product-variation) {% hint style="info" %} 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](/commerce-api/admin-apis/product-management/manage-products-asynchronous-api/creating-or-updating-a-product.md#adding-or-updating-a-products-locale) for instructions on changing the default locale. {% endhint %} {% tabs %} {% tab title="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. ```http curl --location --request POST 'https://api.digitalriver.com/v1/products/{baseProductId}/variations' \ --header 'Authorization: Bearer ' \ ... --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. ```http curl --location --request POST 'https://api.digitalriver.com/v1/products/{baseERID}/variations' \ --header 'Authorization: Bearer ' \ --header 'header x-erid-as-pid=true' \ ... --data-raw '{ "varyingAttributes": [ { "attributeName": "color", "attributeValue": "red" }, { "attributeName": "size", "attributeValue": "large" } ], "deploymentRequiredChanges": {}, "liveChanges": {}, "localizations": [] }' ``` {% endtab %} {% tab title="202 Accepted response" %} The request returns a task identifier (`taskId`) in the [asynchronous ](/commerce-api/admin-apis/product-management/getting-started.md#asynchronous-and-synchronous-calls)response. ```json { "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](/commerce-api/admin-apis/product-management/get-the-task-status-for-a-product-synchronous-api/getting-the-latest-information-on-a-product-task.md). You can also verify the successful completion of the task by [checking the product history](#product-history-attributes) in [Global Commerce](https://gc.digitalriver.com/gc/ent/login.do). Note that there may be a delay before these changes appear in Global Commerce. {% endtab %} {% endtabs %} {% hint style="info" %} You must [add an attribute to the base product](/commerce-api/admin-apis/product-management/manage-products-asynchronous-api/creating-or-updating-a-product.md) 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. {% endhint %} ## Updating a specific product variation The following [`POST /v1/products/{baseProductId or baseERID}/variations/{productVariationId or variationERID}`](https://docs.digitalriver.com/commerce-api-references/admin-apis/product-management/manage-products-asynchronous-api#v1-products-baseproductid-variations-variationid) request updates on any supported attribute, such as the [locale](/commerce-api/admin-apis/product-management/manage-products-asynchronous-api/creating-or-updating-a-product.md#adding-or-updating-a-products-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`). {% tabs %} {% tab title="cURL" %} The following example updates a specific product variation with a `productVariationId`. See the `variations` resource for a description of the attributes. ```http curl --location --request POST 'https://api.digitalriver.com/v1/products/{baseProductId}/variations/{productVariationId}' \ --header 'Authorization: Bearer ' \ ... --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. ```http curl --location --request POST 'https://api.digitalriver.com/v1/products/{baseERID}/variations/{variationERID}' \ --header 'Authorization: Bearer ' \ --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" } } ] } ] }' ``` {% endtab %} {% tab title="202 Accepted response" %} The request returns a task identifier (`taskId`) in the [asynchronous ](/commerce-api/admin-apis/product-management/getting-started.md#asynchronous-and-synchronous-calls)response. ```json { "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](/commerce-api/admin-apis/product-management/get-the-task-status-for-a-product-synchronous-api/getting-the-latest-information-on-a-product-task.md). You can also verify the successful completion of the task by [checking the product history](#product-history-attributes) in [Global Commerce](https://gc.digitalriver.com/gc/ent/login.do). Note that there may be a delay before these changes appear in Global Commerce. {% endtab %} {% endtabs %} Add the new attributes and replace existing attributes in the payload. For example, you can [add or replace locales for a product variation](/commerce-api/admin-apis/product-management/manage-products-asynchronous-api/adding-or-updating-a-product-variation.md#updating-a-specific-product-variation-for-a-base-product). {% hint style="info" %} You must [add an attribute to the base product](/commerce-api/admin-apis/product-management/manage-products-asynchronous-api/creating-or-updating-a-product.md) 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. {% endhint %} ## Updating a specific product variation for a base product The following [`POST /v1/products/{baseProductId or baseERID}/variations/{productVariationId or variationERID}`](https://docs.digitalriver.com/commerce-api-references/admin-apis/product-management/manage-products-asynchronous-api#v1-products-baseproductid-variations-variationid) request updates on any supported attribute, such as the [locale](/commerce-api/admin-apis/product-management/manage-products-asynchronous-api/creating-or-updating-a-product.md#adding-or-updating-a-products-locale), for a product variation associated with a particular base product ID. To update a specific product variation, you must provide either a [`productId` ](https://docs.digitalriver.com/commerce-api-references/commerce-api-reference-guide/api-structure/product-identifier)or [`ERID`](https://docs.digitalriver.com/commerce-api-references/commerce-api-reference-guide/api-structure/product-external-reference-identifier-erid). for both the base product and product variation. {% hint style="info" %} 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. {% endhint %} {% tabs %} {% tab title="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. ```http curl --location --request POST 'https://api.digitalriver.com/v1/products/{baseProductId}/variations/{productVariationId}' \ --header 'Authorization: Bearer ' \ ... --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. {% code overflow="wrap" %} ```http curl --location --request POST 'https://api.digitalriver.com/v1/products/{baseERID}/variations/{variationERID}' \ --header 'Authorization: Bearer ' \ --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" } } ] } ] }' ``` {% endcode %} {% endtab %} {% tab title="202 Accepted" %} The request returns a task identifier (`taskId`) in the [asynchronous ](/commerce-api/admin-apis/product-management/getting-started.md#asynchronous-and-synchronous-calls)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](/commerce-api/admin-apis/product-management/get-the-task-status-for-a-product-synchronous-api/getting-the-latest-information-on-a-product-task.md). You can also verify the successful completion of the task by [checking the product history](#product-history-attributes) in [Global Commerce](https://gc.digitalriver.com/gc/ent/login.do). Note that there may be a delay before these changes appear in Global Commerce. {% endtab %} {% endtabs %} Add the new attributes and replace existing attributes in the payload. For example, you can [add or replace locales for a product variation](/commerce-api/admin-apis/product-management/manage-products-asynchronous-api/adding-or-updating-a-product-variation.md#updating-a-specific-product-variation-for-a-base-product). {% hint style="info" %} You must [add an attribute to the base product](/commerce-api/admin-apis/product-management/manage-products-asynchronous-api/creating-or-updating-a-product.md) 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. {% endhint %}