Using product details
Understand how to use the productDetails object
If you decide to use
productDetails, you'll need to retrieve product data from your system at checkout-time and then use it to define the object. Since you don't persist 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.
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 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
}
]
}'
The
id in productDetails should represent the unique identifier of the product in your system.In
productDetails, a skuGroupId identifies the SKU group that the product belongs to. You're required to provide this identifier because Digital River uses it to access this product's compliance data.In create checkout requests, if you send
productDetails that 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."
}
]
}
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."
}
]
}
In
productDetails, you can define a parameter that represents a hierarchical classification system which organizes and categorize your products based on their attributes, characteristics, and relationships.The parameter's name depends on the resource you're creating:
Resource | Parameter name |
|---|---|
itemBreadcrumb | |
categories |
You'll typically structure
itemBreadcrumb / categories by defining a broad top-level category and, as you move down the hierarchy, getting more specific at each subsequent level.You might have built similar data structures that inventory your products and make it easier for customers to find what they're looking for. In that case, we recommend using this same data.
If you're engaging the item classification service, then all of your physical products must have an
itemBreadcrumb / categories. Even if you're not currently making cross-border sales, it's best practice to define this parameter so that, in the event you do start selling internationally, you're better positioned to get started.
We recommend making your taxonomies as detailed as possible. By doing so, you increase the probability that the tariff codes returned by the service are accurate.
For example,
Clothing > Women’s Jeans is an acceptable value but Clothing > Women’s Clothing > Jeans > Bootcut Jeans will likely result in more accurate classifications. You can provide multiple hierarchies, just make sure to separate each with a ; (semi-colon). Although not technically required, it's highly recommended that you define
itemBreadcrumb in English. If its value is in a different language, then the classification service will disregard this data point.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"
}
]
}
In
productDetails, you can use:imageto specify the URL of a resource that contains the product's image. It should be similar to the image(s) you display to customers while they are reviewing products in your store.urlto specify the address of a resource that contains the product's description.
In Prebuilt Checkout, each
items[].productDetails.image in a checkout-session is displayed in the checkout modal's order summary section. In Global logistics, depending on your logistics partner's setup, both
image and url are often added to the transaction's customs documentation, thereby allowing officials to obtain information about the product during the pre-clearance phase of an importation.For physical products,
productDetails can be used to send a weight denoted by 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.If your site intends on selling physical products cross-border, then we recommend that you pass the
weight and weightUnit of all of your catalog's physical products.In some countries, such as Switzerland, custom officials use a product's weight when calculating import duties. As a result, without this data, Digital River is unable to calculate landed costs.
400 Bad Request
{
"type": "bad_request",
"errors": [
{
"code": "missing_parameter",
"message": "The weight is missing.",
"parameter": "weight"
}
]
}
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.
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.
In Digital River coordinated fulfillments,
manufacturerId is used to set up products in warehouses. But since that process is handled prior to deployment there's no need to send manufacturerId at checkout-time.Last modified 4h ago