Creating or updating a product

Learn how to programmatically create or update a product using product identifiers (productId).

When creating or updating a product through our API or Global Commerce system, it's essential to understand the proper procedures and guidelines to ensure a smooth process and avoid potential errors. This guide will walk you through the necessary steps and provide important details, such as product variations, locale management, and correctly grouping attribute values. Following these guidelines will help you effectively manage your products and avoid common pitfalls.

Do not send multiple simultaneous requests to create or update a product via API and Global Commerce or Bulk Product Upload (BPU). Simultaneous changes to a product can lead to errors in the database.

When managing a product or a product's locale, note that:

  • Adding the variations object to the payload allows you to create a base product with variations. When you create a product without the variations object, it is an individual product. You cannot transfer an individual product to a base product programmatically. However, you can transfer an individual product to a base product from Global Commerce.

  • The request automatically adds the locales object from the base product to each product variation. An error appears in the response if the locales are inconsistent between the base product and the product variations.

    • If en_GB and en_US exist in the base product and only en_US exists in the product variation, this request copies 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 response returns an error.

  • The request updates the correct attribute value even if the attribute value is in the wrong group. For example, if you put the eccn attribute for export control in the storefront setting group, the request will update the eccn attribute as long as the value is correct. However, the response will put the attribute in the export control group where it belongs.

Product payload example

Here is an example payload for creating or updating a product, including a base product with variations. This example demonstrates the necessary structure and key attributes you need to provide for a base product with variations:

The following payload example contains data attributes for a base product with variations. See the products resource for a description of the attributes.

{
  "deploymentRequiredChanges": {
    "fulfillmentTypes": [
      "Download"
    ],
    "otherFulfillmentIntegration": {
      "fulfillerIds": [
        "digitalRiver"
      ]
    },
    "transferProduct": "2234567800",
    "upgradeProducts": [
      "3234567800"
    ],
    "downgradeProducts": [
      "4234567800"
    ]
  },
  "liveChanges": {
    "externalReferenceId": "sku-1234-5678-xyz",
    "catalogs": [
      {
        "catalogId": "123456000",
        "categories": [
          {
            "categoryId": "19000000"
          }
        ],
        "prices": [
          {
            "type": "listPrice",
            "prices": [
              {
                "currency": "USD",
                "locale": "en_US",
                "configuredPrice": 15.99
              }
            ]
          }
        ]
      }
    ]
  },
  "localizations": [
    {
      "locale": "en_US",
      "isDefault": true,
      "groups": [
        {
          "attributes": {
            "property1": "string",
            "property2": "string"
          }
        }
      ]
    }
  ],
  "variations": [
    {
      "varyingAttributes": [
        {
          "attributeName": "fulfillmentType",
          "attributeValue": "Download"
        }
      ],
      "deploymentRequiredChanges": {
        "fulfillmentTypes": [
          "Download"
        ],
        "otherFulfillmentIntegration": {
          "fulfillerIds": [
            "digitalRiver"
          ]
        },
        "transferProduct": "2234567800",
        "upgradeProducts": [
          "3234567800"
        ],
        "downgradeProducts": [
          "4234567800"
        ]
      },
      "liveChanges": {
        "externalReferenceId": "sku-1234-5678-xyz",
        "catalogs": [
          {
            "catalogId": "123456000",
            "categories": [
              {
                "categoryId": "19000000"
              }
            ],
            "prices": [
              {
                "type": "listPrice",
                "prices": [
                  {}
                ]
              }
            ]
          }
        ]
      },
      "localizations": [
        {
          "locale": "en_US",
          "isDefault": true,
          "groups": [
            {
              "attributes": {
                "property1": "string",
                "property2": "string"
              }
            }
          ]
        }
      ]
    }
  ]
}

When implementing this payload structure in your requests, you must modify the example values according to your specific product data.

When creating a product, you need to provide the following objects in the payload:

Creating an individual or base product

You can create the base product and its variations using one call. When doing so, the request copies the base product attributes to each product variation. You can update the attributes for a product variation by including the modified attributes in the product variation request payload.

The following POST /v1/products request creates a base product with product variations.

When creating an individual or base product, you do not need to provide a productId. The productId will be provided when you create the product. If you want to use an ERID, provide the ERID in the payload. Global Commerce will associate the created product with the given ERID. After associating the ERID with the product, you can continue to use the ERID in the call request when updating the product.

You can add the variations object to the payload to create a base product with variations. When you create a product without the variations object, it is an individual product.

To add a locale to a product, add the locale data in the payload using the POST /v1/products/{productid} request.

The following example creates a new base product with a productId and product variations using a variationProductId. See the products resource for a description of the attributes.

curl --location --request POST 'https://api.digitalriver.com/v1/products' \
--header 'Authorization: Basic <API_key>' \
...
--data-raw '{
    "liveChanges": {  },  
    "variations": [    
        {          
            "varyingAttributes": [        
                {          
                    "attributeName": "Color",          
                    "attributeValue": "Black"        
                },        
                {          
                    "attributeName": "fulfillmentType",          
                    "attributeValue": "Download"        
                }      
            ],      
            "liveChanges": {  }    
        },    
        {      
            "varyingAttributes": [        
                {          
                    "attributeName": "Color",          
                    "attributeValue": "Blue"        
                },        
                {          
                    "attributeName": "fulfillmentType",          
                    "attributeValue": "Download"        
                }      
            ],      
            "liveChanges": {  }    
        }  
    ] 
}'

An ERID request requires the x-erid-as-pid=true header. The following example creates a new base product with an ERID and product variations using an variationERID. See the products resource for a description of the attributes.

curl --location --request POST 'https://api.digitalriver.com/v1/products/{ERID}' \
--header 'Authorization: Basic <API_key>' \
--header 'header x-erid-as-pid=true' \
...
--data-raw '{
    "productType": "BASE",  
    "companyId": "ace",  
    "liveChanges": 
        {  
            "externalReferenceId": "ERID_BASE"
        },  
    "variations": [    
        { 
            "productType": "VARIATION",      
            "companyId": "cast",      
            "varyingAttributes": [        
                {          
                    "attributeName": "Color",          
                    "attributeValue": "Black"        
                },        
                {          
                    "attributeName": "fulfillmentType",          
                    "attributeValue": "Download"        
                }      
            ],      
            "liveChanges": 
                { 
                    "externalReferenceId": "ERID_VARIATION_1"     
                }    
        },    
        {           
            "varyingAttributes": [        
                {          
                    "attributeName": "Color",          
                    "attributeValue": "Blue"        
                },        
                {          
                    "attributeName": "fulfillmentType",          
                    "attributeValue": "Download"        
                }      
            ],      
            "liveChanges":   
                { 
                    "externalReferenceId": "ERID_VARIATION_2"     
                }   
        }  
    ] 
}'

Creating a digital product

The following example creates a digital product. See the products resource for a description of the attributes.

curl --location --request POST 'https://api.digitalriver.com/v1/products' \
--header 'Authorization: Basic <API_key>' \
...
--data-raw '{
    "companyId":"acme",
    "deploymentRequiredChanges": {
        "fulfillmentTypes": ["Download"]
    },
    "liveChanges": {
        "externalReferenceId": "external-reference-id-{{uuid}}",
        "catalogs" : [ {
            "catalogId" : "4783669800",
            "pricing" : [ {
                "type": "listPrice",
                "prices": [{
                    "currency": "USD",
                    "locale": "en_US",
                    "configuredPrice": 10
                }]
            }]
        }]
        
    },
    "localizations": [
    {
      "locale": "en_US",
      "isDefault": "true",
      "groups": [
        {
          "groupId": "11",
          "groupName": "Software",
          "attributes": {
            "name": "demo-name-{{uuid}}",
            "displayName": "demo-display-name-{{uuid}}",
            "sku": "demo-sku-{{uuid}}",
            "returnMethod": "LOD",
            "productReturnMethod": "ByAgentAndSelfService",
            "taxableUnspscCode": "43230000",
            "taxableProductCode": "4323.320_D",
            "privateStoreOnly": false,
            "isViewable": true,
            "isOrderable": true,
            "nonSolr": true,
            "shortDescription": "shortDescription-{{uuid}}",
            "longDescription": "longDescription-{{uuid}}",
            "keywords": "keywords-{{uuid}}",
            "emailAddlInfoText": "emailAddlInfoText-{{uuid}}",
            "emailAddlInfo": "emailAddlInfo-{{uuid}}",
            "confirmAddlInfo": "confirmAddlInfo-{{uuid}}",
            "eccn": "3A992",
            "manufactureCountry": "US"
          }
        },
        {
          "groupId": "5678",
          "groupName": "subscription",
          "attributes": {
            "autoRenewalDateBasis": "PurchaseDate",
            "combinedRenewalPeriod": 1,
            "duration": "TWO_MONTH",
            "freeExtension": "2_WEEK",
            "freeTrialPeriod": 45,
            "gracePeriod": "1_WEEK",
            "includeRenewalProductInUpgradeList": true,
            "isAutomatic": true,
            "isChangeProductAsRenewal": false,
            "isCombinedRenewal": true,
            "isDistinctScheduleTurnedOn": false,
            "isFreeTrial": true,
            "numOfDaysPriorExpirationForRenewal": 4,
            "numOfDaysPriorExpirationForRenewalFirst": 15,
            "numOfDaysPriorExpirationForRenewalPreFirst": 30,
            "paymentSchedule": "matchRecurrence",
            "postExpirationBillingAttemptIntervalInDays": 7,
            "suppressDRMInQuantityIncrease": false,
            "suppressDRMInRenewal": false,
            "suppressDRMInTrialConversion": false,
            "suppressDRMInUpgradeDowngrade": false,
            "suppressOFIInQuantityIncrease": false,
            "suppressOFIInRenewal": true,
            "suppressOFIInTrialConversion": true,
            "suppressOFIInUpgradeDowngrade": false,
            "timeIntervalForCCExpirationReminderNotifications": ["30","15","7"],
            "timeIntervalForManualReminderNotifications": ["90","30","15","7"],
            "timeIntervalForReminderNotifications": ["90","30","15","7"],
            "timeIntervalForReminderNotificationsPostExpiration": ["7","15","30","90"],
            "timeIntervalForTrialManualReminderNotifications": ["30","15","7","2"],
            "timeIntervalForTrialReminderNotifications": ["30","15","7","2"],
            "timeIntervalForUpgradeReminderNotificationsPostCreation": ["7","15","30","90"],
            "timeIntervalForUpgradeReminderNotificationsPostExpiration": ["97","37","22","14"],
            "timeIntervalForUpgradeReminderNotificationsPreExpiration": ["97","37","22","14"],
            "trialGracePeriod": "1_MONTH",
            "trialPostExpirationBillingAttemptIntervalInDays": 7
          }
        }
      ]
    }
  ]
}'

Product history attributes

  • To Date: The beginning of the search date range.

  • From Date: The end of the search date range.

  • Change Type: A brief description of the change applied to the product. Some of the possible change type values are as follows:

    • Copied: This indicates a user copied the current product from another product. When a user copies an existing product, the Product History page shows the product ID and the name of the original product on which the new product is based.

    • Revert: This indicates a user reverted the product to a previous version (and shows the previous version). For more about reverting a product, see Reverting changes to products.

    • Save or Save (Including Live Change): This indicates you or another user saved a change to the product. Save means you must deploy the product before shoppers can see the change in your store. Save (Live Change) indicates the system automatically applied the change to your store, and you do not need to deploy the product. You can click the plus (+) sign next to a save event to see additional information for that event. One or more of the following columns appear with every save event:

      • Locale: Indicates the locales where the change occurred.

      • Area: Indicates the general area in the editor where the change occurred. Example: If you change the name, the area lists "Storefront Settings" as the area where you can find the name.

      • Field: Displays the changed field. Example: You can use this field name and the content displayed in the Area column to locate the attribute in Global Commerce.

      • Old Value: Displays the old value. If a value is not present, no content appears in this column.

      • New Value: Displays the new value. Note: Save does not always mean the item changed. If you view the item and click the Save button without applying any changes, the system logs that change.

    • Status Changed to Deployed: Indicates the state of the product changed to the Live state. The changes now appear in your store.

    • Status Changed to Design: The product status changed to the Design state.

    • Status Changed to New: When you create a product, the product status changes to the New state.

    • Took Ownership: Indicates that a new user can edit a product. The name of the new user appears in the Modified By column. Ownership indicates the last person to edit the product. Another user cannot edit the product until they own it. Ownership prevents two users from editing the product at the same time.

    • Variation Added: A user added a variation to the product. The variation ID, as well as the varying attributes, also appear in the Change Type column.

    • Variation Deleted: A user deleted product variation. The variation ID, as well as the varying attributes, also appear in the Change Type column.

  • Product/Variation ID: Displays the product identifier or variation for the product.

    • If this is an individual product, only the product ID appears. If this is a base product, (Base) appears after the ID.

    • If this is a product variation, the name of the variation and the varying attributes (in parentheses) appear after the ID.

  • Modified By: The name of the person or application that last modified the product. API indicates the Admin API. For example, jdoe or API (ZDIOODJi***), where jdoe is the Global Commerce username and ZDIOODJi*** is the first eight digits of the API key for an Admin API request.

  • Modified On: The date and time when the product was last modified.

Adding or replacing a product's locale

You can localize your products so shoppers can see product information in their native language, date format, time format, and currency. You can also localize themes and styles to create a look and feel for a specific locale or region.

A locale is a designator that combines the two-letter ISO 639-1 language code with the ISO 3166-1 alpha-2 country code (such as en_US). For example, the en_GB language code represents the English language and the country of Great Britain.

When you create or update a product, you can configure the product to use those locales and enter localized content for that product. When choosing locales, note the following:

  • When you enter text for the product in the default locale, the same text appears for all supported locales until you either "override" or "specify" the default in a specific locale folder. You can override the default locales by adding a product variation after creating a base product. You can also specify the default locales when creating a base product and its variations simultaneously. Changing the product's default locale does not affect your store's global default locale settings.

  • You can provide localized content for a product. A localizations object appears for each supported locale where you can enter the localized information. You do not have to enter localized content for all supported locales.

The following example payload adds or replaces a product's locale. See the products resource for a description of the attributes.

{
  "localizations": [
    {
      "locale": "en_US",
      "isDefault": true,
      "groups": [
        {
          "attributes": {
            "property1": "string",
            "property2": "string"
          }
        }
      ]
    }
  ]
}

  • By default, shoppers can purchase products in any locale (within defined export controls). You should restrict the purchasing products to only supported areas. See Limiting purchases to supported locales for more information.

Ideally, you should localize a product when you first create it. However, you can localize a product after you create and deploy it to your store. If you turn off the fields and options on a locale in Global Commerce, the supported locale uses the default locale setting. See Overriding the default locale for more information.

The following POST /v1/products/{productid} request updates for an existing product by replacing attributes. You must provide either a productId or ERID.

PreviousManage products (asynchronous API)NextAdding or updating a product variation

Last updated