Links

Using product details

Understand how to use the product details object
A productDetails object contains basic product data. You most commonly send productDetails in create checkout and create checkout session requests. If you decide to use this object, you'll need to retrieve product data from your system at run-time and then define the object with this retrieved data. Since you're not persisting productDetails in Digital River's system, this object reduces your catalog management requirements.
If your integration currently uses SKUs and you're considering a migration, you should be aware of the common attributes in product details and SKUs.

Product details

You'll most commonly use productDetails in create checkout and create checkout session requests to send Digital River the following basic product data:
For complete specifications, refer to the Checkouts API and Drop-in Checkout Sessions API reference documentation.
POST/checkouts
curl --location --request POST 'https://api.digitalriver.com/checkouts' \
...
--data-raw '{
...
"items": [
{
"productDetails": {
"id": "2837a981-9e41-408b-a1b2-ffa3223bc505",
"skuGroupId": "wireless-keyboards",
"name": "Basic wireless keyboard",
"description": "A simple, basic wireless keyboard",
"url": "https://www.company.com/basic-wireless-keyboard",
"countryOfOrigin": "US",
"image": "https://www.company.com/basic-wireless-keyboard/image",
"weight": 1,
"weightUnit": "kg",
"partNumber": "ce1fd95d-b211-47e8-a9b7-9941a4ce9d7a"
},
"quantity": 2,
"price": 10
}
]
}'

Unique identifier

The unique id in productDetails should represent the identifier of the product in your system.

Unique SKU group identifier

In productDetails, a skuGroupId uniquely identifies the SKU group that holds this product's compliance data. You're required to provide skuGroupId because Digital River uses it to access the product's compliance data.
For more information, refer to Grouping SKUs.
In create checkout requests, if you send productDetails, and it doesn't contain a skuGroupId, then the following error is thrown:
400 Bad Request
{
"type": "bad_request",
"errors": [
{
"code": "missing_parameter",
"parameter": "skuGroupId",
"message": "An item of type sku is missing a skuGroupId parameter."
}
]
}

Country of origin

The countryOfOrigin is a two-letter Alpha-2 country code as described in the ISO 3166 international standard. This attribute represents the country where a product was manufactured.
In create checkout requests, if you send productDetails, and it doesn't contain countryOfOrigin, then the following error is thrown:
400 Bad Request
{
"type": "bad_request",
"errors": [
{
"code": "missing_parameter",
"parameter": "countryOfOrigin",
"message": "must not be null"
}
]
}
In create checkout requests, if you send productDetails, and it contains an invalid countryOfOrigin, then the following error is thrown:
400 Bad Request
{
"type": "bad_request",
"errors": [
{
"code": "invalid_parameter",
"parameter": "countryOfOrigin",
"message": "'KP' is not a valid Country of Origin."
}
]
}

Name and description

In productDetails, the name should represent the product's brand name and description should provide more details about the product.
In create checkout requests, if you send productDetails, and it doesn't contain name, then the following error is thrown:
400 Bad Request
{
"type": "bad_request",
"errors": [
{
"code": "missing_parameter",
"parameter": "name",
"message": "must not be null"
}
]
}

Image and url

You can use:
  • productDetails.image to specify the URL of a resource that contains the product's image. This resource should be similar to the image(s) you display to customers while they are reviewing products and adding them to their cart.
  • productDetails.url to specify the URL of a resource that contains the product's description.
In Drop-in Checkout, each checkout-sessions' items[].productDetails.image is displayed in the order summary section of the checkout modal window.
In the Global logistics solution, depending on your logistics partner's setup, both productDetails.image and productDetails.url are often transferred to the transaction's customs documentation. This allows customs officials to obtain information about the product during the pre-clearance phase of an importation.
If your integration gives customers the option to use ApplePay, GooglePay, or Klarna then productDetails must contain an image and url.

Weight and weight unit

For physical products, productDetails can be used to send a weight measured by a weightUnit. The enumerated weightUnit values are oz, lb, g, and kg.
If you provide a weight but not a weightUnit, then the value defaults to oz.
In some countries, such as Switzerland, custom officials use a product's weight when calculating import duties. Without this data we're unable to calculate landed costs.
If you attempt to create or update a checkout that contains a ship to country from one of these nations, and any productDetails in the checkout's items[] array are missing weight, then the following 400 Bad Request is thrown:
400 Bad Request
{
"type": "bad_request",
"errors": [
{
"code": "missing_parameter",
"message": "The weight is missing.",
"parameter": "weight"
}
]
}
So, if your site intends on selling physical products across international borders, we recommend that you define both weight and weightUnit for all of your catalog's physical products.

Part number

A productDetails can contain a partNumber. It represents a unique manufacturer part number (MPN) issued by manufacturers to identify a part or product.
MPNs are meant to be static identifiers of a part/product, universal to all distributors, wholesalers, and resellers. They allow customers to accurately identify exact parts and protect themselves from counterfeits.
If two parts or products originate from two different manufacturers, then each must have its own MPN. These identifiers are especially relevant for automotive and consumer electronics, due to the numerous parts in these complex products.

Common attributes in product details and SKUs

The attributes in SKUs and productDetails are nearly identical. The key exceptions are taxCode, eccn, and hsCode, which exist in SKUs but not in productDetails.
However, since these attributes hold compliance data, they're contained in the referenced SKU group.
For more information, refer to Grouping SKUs.
SKUs also have a manufacturerId and this attribute is not in productDetails.
In Digital River coordinated fulfillments, manufacturerId is used to set up products in warehouses. That process however is handled prior to deployment. So there's no need to send manufacturerId in checkouts.