Products
Understand the basics of products.
Last updated
Understand the basics of products.
Last updated
A product (a stock keeping unit or SKU) is a sellable item or service. Products in your Digital River catalog contain all required attributes to complete an end-consumer transaction (payments, tax, and fulfillment). You can generally configure the product in one of two ways:
An individual product (single sellable SKU)
A base product with product variations (base product with multiple sellable SKU variants)
You can retrieve the catalog product information, including applicable discounted prices, by leveraging the available product endpoints.
An individual product is a single item, such as a downloadable song, or a collection of items, such as a box set. Use the POST /v1/products request to create an individual product and the POST /products/{productId} request to update an individual product. There are no product variations associated with it.
An individual product is a single sellable stock keeping unit (SKU). The following image shows an example of a SKU:
If a product comes in different colors, sizes, or versions, it is easier to maintain a base product with product variations than a handful of nearly identical products.
You can create a base product (parent) that contains the common attributes for all product variations (children) of that product. All product variations inherit common attributes. For example, if two variations of a base product require the same product images, add those images to the base product before creating your variations.
Note: A shopper cannot add a base product to a cart. They can only add the product variation to the cart. For example, a shopper can go to the Digital River-hosted storefront and choose a product variation from an interstitial page. The store template automates and controls this behavior.
Use the POST /v1/products request to create a base product and the POST /v1/products/{productId} request to update a base product.
Product variations are different versions of a base product that a shopper can purchase, such as different versions, sizes, or capacities. When you add a product variation, the request copies the common attributes from the base product to the variation. You must change the appropriate attributes and settings to make that variation unique. Each product variation contains attributes and settings that are unique to that product variation.
You must change at least one common attribute to make the product variation unique. Only change those settings or attributes that are unique to the variation to reduce operational maintenance.
The following image shows an example of a product variant on a store's website:
You can choose to either:
Create the base product first and include the common attributes. If you choose not to define some of the common attributes, those attributes will not be available when you add a product variation.
Define as many common attributes as possible for the base product before you create a product variation.
You can add the product variations to that base product later.
You can create a base product and all its product variations using one call by adding the variations object to the payload. The request copies the common attributes from the base product to each product variation. You modify the attributes for each product variation in the payload when you update the product variation.
The following example adds or updates a base product and its product variations.
The following example verifies the successful completion of the request shown above.
Use the Admin API fulfillment types (fulfillmentTypes) to define how to deliver products to shoppers. The options are empty (""), physical or download. When the value is empty, the product is neither physical nor download. The empty value reflects the Other setting in Global Commerce for service, warranty, entitlement, etc. Digital River supports two types of digital products: subscription and download.
In this topic, you'll find information on some of the products attributes used when creating or updating a product. For a complete list, refer to Create a new individual or base product with variations in the Admin APIs reference documentation
Any changed attributes in the deploymentRequiredChanges object will not go live until you deploy the product. This object includes the following attributes:
A fulfillmentType defines how products are delivered to shoppers. The options are empty (""), physical or download. When the value is empty, the fulfillment type is neither a physical nor a download product. The empty value reflects the Other setting in Global Commerce for service, warranty, entitlement, etc. Digital River supports two types of digital products: subscription and download.
The otherFulfillmentIntegration setting allows you to provide a unique fulfillment for your products. Contact your Store Operations team if you have special fulfillment needs that could benefit from Other Fulfillment Requirements and integrations.
fulfillerIds: The fulfiller's identifier.
The transferProduct is the upgraded product identifier. This is a subscription product term. You can use the product identifier (productID) or the external reference identifier (ERID) The base product cannot be a transfer product.
The upgradeProducts is the upgraded product identifier for a subscription product. You can use the product identifier (productID) or the external reference identifier (ERID). You cannot upgrade a base product.
The downgradeProducts is the downgrade product identifier for a subscription product. You can use the product identifier (productID) or the external reference identifier (ERID). You cannot downgrade a base product.
This localizations object defines the locales supported by the product.
The product's supported locale.
When isDefault is set to true, the locale is the default locale.
The groups is an array of grouped attributes associated with the locale.
groupId: The group identifier for the attributes (for example, 1100). This field is read-only. You do not need to provide this attribute in the request. The request will ignore this attribute when creating or updating the product.
groupName: The group name for the attributes. This field is read-only. You do not need to provide this attribute in the request. The request will ignore this attribute when creating or updating the product.
attributes: An array of properties associated with the group.
The possible attributes are as follows:
Name: The name of a product as it appears in reports, offers, and other places within Global Commerce. Shoppers will not see this name in your store. For example: Maverick Sneakers
displayName: The public-facing product name as it appears in your store. Shoppers can see this name when they browse your store or use it when searching for it. For example: F-18 Hornet Fighter Jet
sku: The stock keeping unit (SKU) or product name. For example: f18
shortDescription: A brief description of the product. For example: The Boeing F/A-18E and F/A-18F Super Hornet are twin-engine, carrier-capable, multirole fighter aircraft...
eccn: A SKU's eccn represents its Export Control Classification Number (ECCN). For example: EAR990
This value determines whether:
A product requires a US export/re-export license
A product contains any other license requirements/restrictions
A product has an end-use that is prohibited by applicable export control laws
Digital River's legal documentation lists ECCNs pre-approved for use in the Admin APIs. In the table's description field, you may find additional requirements and restrictions that further limit the use of the ECCN.
Digital River can only resell products with these listed ECCNs. If you have a product with an ECCN that you'd like to be considered for addition to the list, e contact Legal-compliance@digitalriver.com.
downloadFulfillment: The download fulfillment type. This attribute is required when you are creating a digital product. The valid values are digitalRiver or thirdParty. If you don't provide this attribute when you create or update a product, the default value is digitalRiver.
The productId is the product identifier.
This variations object defines the variation of a base product. This attribute is available when you create a base product. It's only required when you want to create variations of a base product.
These attributes for the varyingAttributes object distinguish the product variation from the base product.
attributeName: The name of the attribute, such as size.
attributeValue: The attribute's value, such as small, medium, or large.
You can specify one or more query parameters separated by an ampersand (&) to return a filtered list of products. The following topics describe the available query parameters for the products request. For more information on how to use query parameters, see Fields and query parameters.
The version string gets the specific version of the product by state. The enums are DEPLOYED and RETIRED. If you do not specify the version query parameter, the response will contain the latest version. For example, if the product history is as follows:
Version 1 is retired: This product version is retired. Shoppers can no longer see or purchase this product in the store.
Version 2 is deployed: This product version is available in the store. Shoppers can see and purchase this product from your store.
Version 3 is in design: This new product version is not yet available in the store. You are planning to deploy this new version eventually. Shoppers cannot see or purchase this product from your store.
Use the following calls can get the different versions:
If you want to get the retired version (version 1), use the following call:
GET /v1/products/{productId}?version=retired
If you want to get the deployed version (version 2), use the following call:
GET /v1/products/{productId}?version=deployed
If you want to get the latest unreleased version, use the following call:
GET /v1/products/{productId}
See Getting the deployed version of a product for more information.
The following details describe the key attributes when adding or updating a product variation. Refer to the Update a product variation in the Admin APIs Reference document for a complete list.
These attributes distinguish the product variation from the base product.
attributeName: The name of the attribute, such as size.
attributeValue: The attribute's value, such as small, medium, or large.
Any changed attributes in the deploymentRequiredChanges object will not go live until you deploy the product. This object includes the following attributes:
A fulfillmentType defines how products are delivered to shoppers. The options are empty (""), physical or download. When the value is empty, the product is neither a physical nor a download. The empty value reflects the Other setting in Global Commerce for service, warranty, entitlement, etc. Digital River supports two types of digital products: subscription and download.
The otherFulfillmentIntegration setting allows you to provide a unique fulfillment for your products. If you have special fulfillment needs that could benefit from Other Fulfillment Requirements and integrationsContact your Store Operations team if.
fulfillerIds: The fulfiller's identifier.
The transferProduct is the upgraded product identifier. This is a subscription product term. You can use the product identifier (productID) or the external reference identifier (ERID) The base product cannot be a transfer product.
The upgradeProducts is the upgraded product identifier for a subscription product. You can use the product identifier (productID) or the external reference identifier (ERID). You cannot upgrade a base product.
The downgradeProducts is the downgrade product identifier for a subscription product. You can use the product identifier (productID) or the external reference identifier (ERID). You cannot downgrade a base product.
The changed attributes under the liveChanges object will go live immediately. You do not need to deploy these changes. You can use the following attributes to insert live changes when creating a product. After creating the product, the fields are read-only. You can apply live changes by using the POST /v1/products/{productId}/live-changes API. This object is available when you update a product. This object includes the following attributes:
The externalReferenceId is the product's external reference identifier. It's your company's unique identifier for the product.
A catalog is a collection of products for sale on your site. A catalog contains categories to organize your products.
cattlogId: The catalog identifier. The variation catalog and category are inherited from the base product. The information will be provided in the product variation but ignored if you insert that information in a product variation request.
categories: Use categories to organize products within a catalog, often appearing in the store to help shoppers navigate the store or site to locate products
categoryId: The category identifier.
pricing: The price of a product by currency and locale.
type: The price list type. Used to classify the prices in a price list. A price list type may also indicate how the price list or pricing will be used. For example, you can create an MSRP list, a subscription renewal price list, etc.
prices: The prices of a product.
currency: A three-letter ISO 4217 currency code.
locale: Optional. If your store supports multiple locales, your price list will contain the currency for each of the supported locales. When you enter a price for a product by currency, any locale that uses that currency will use the price you provided.
configuredPrice: The configured price for the product.
This localizations object defines the locales supported by the product.
The product's supported locale.
When isDefault is set to true, the locale is the default locale.
The groups is an array of grouped attributes associated with the locale.
groupId: The group identifier for the attributes (for example, 1100). This field is read-only. You do not need to provide this attribute in the request. The request will ignore this attribute when creating or updating the product.
groupName: The group name for the attributes. This field is read-only. You do not need to provide this attribute in the request. The request will ignore this attribute when creating or updating the product.
attributes: An array of properties associated with the group.
The possible attributes are as follows:
Name: The name of a product as it appears in reports, offers, and other places within Global Commerce. Shoppers will not see this name in your store. For example: sys-acme-test-name-{{defaultLocale}}
displayName: The public-facing product name as it appears in your store. Shoppers can see this name when they browse your store or use it when searching it. For example: display-name-{{defaultLocale}}
sku: The stock keeping unit (SKU) or product name. For example: sku-test-{{defaultLocale}}
shortDescription: A brief description of the product. For example: shortDescription-{{defaultLocale}}
eccn: SKU's eccn represents its Export Control Classification Number (ECCN). For example: EAR990. This value determines whether:
A product requires a US export/re-export license.
A product contains any other license requirements/restrictions.
A product has an end-use that is prohibited by applicable export control laws.
Digital River's legal documentation lists ECCNs pre-approved for use in the Admin APIs. In the table's description field, you may find additional requirements and restrictions that further limit the use of the ECCN.
Digital River can only resell products with these listed ECCNs. If you have a product with an ECCN that you'd like to be considered for addition to the list, contact Legal-compliance@digitalriver.com.
downloadFulfillment: The download fulfillment type. This attribute is required when you are creating a digital product. The valid values are digitalRiver or thirdParty. If you don't provide this attribute when you create or update a product, the default value is digitalRiver.
