Using product details

Understand how to use the productDetails object

A productDetails object contains basic product data.

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 know 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 Checkout Sessions API reference documentation.

• Unique identifier

• Unique SKU group identifier

• Country of origin

• Name and description

• Image and URL

• Weight and weight unit

• Part number

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 id in productDetails should represent the unique identifier of the product in your system.

Unique SKU group identifier

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.

For details, refer to Grouping SKUs.

Create checkout requests throws the following errors if you send productDetails that doesn't contain a skuGroupId:

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.

Create checkout requests throws the following errors if you send productDetails, and it doesn't contain countryOfOrigin:

400 Bad Request

{
    "type": "bad_request",
    "errors": [
        {
            "code": "missing_parameter",
            "parameter": "countryOfOrigin",
            "message": "must not be null"
        }
    ]
}

Create checkout requests throws the following errors if you send productDetails, and it contains an invalid countryOfOrigin:

400 Bad Request

{
    "type": "bad_request",
    "errors": [
        {
            "code": "invalid_parameter",
            "parameter": "countryOfOrigin",
            "message": "'KP' is not a valid Country of Origin."
        }
    ]
}

Item breadcrumb and categories

In productDetails, you can define a parameter representing a hierarchical classification system that organizes and categorizes your products based on their attributes, characteristics, and relationships.

The parameter's name depends on the resource you're creating:

Resource	Parameter name
Checkouts	itemBreadcrumb
Checkout-sessions	categories

You'll typically structure itemBreadcrumb / categories by defining a broad top-level category and getting more specific at each subsequent level as you move down the hierarchy.

You might have built similar data structures that inventory your products and make it easier for customers to find what they want. 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. This will 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. The classification service will disregard this data point if its value is in a different language.

Name and description

For productDetails, the name should represent the product's brand name and description should provide more details about the product.

A name is required but description is optional. If you assign a string to description, then we recommend limiting its length to 1000 characters or less.

In low-code checkouts, name is displayed in the order summary section.

Image and URL

For productDetails, you can use:

• image to 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 review your store's products.

• url to specify the address of a resource that contains the product's description.

If your integration gives customers the option to use Klarna then productDetails must contain an image and url.

In Prebuilt Checkout, each items[].productDetails.image in a checkout-session is displayed in the checkout modal's order summary section.

Weight and weight unit

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 to sell 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, like Switzerland, customs officials use a product's weight when calculating import duties. Without this data, Digital River is unable to calculate landed costs.

If you send a create or update checkout request whose shipTo.address.country represents one of these nations, and any productDetails in the checkout's items[] are missing weight, then the following error is thrown:

400 Bad Request

{
    "type": "bad_request",
    "errors": [
        {
            "code": "missing_parameter",
            "message": "The weight is missing.",
            "parameter": "weight"
        }
    ]
}

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, each must have its own MPN. Due to the numerous parts in these complex products, these identifiers are especially relevant for automotive and consumer electronics.

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 details, 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. But since that process is handled before deployment, sending the manufacturerId at checkout-time is unecessary.