# Using product details A `productDetails` object contains [basic product data](https://docs.digitalriver.com/digital-river-api/skus#basic-versus-compliance-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](#common-attributes-in-product-details-and-skus). ## Product details You'll most commonly use `productDetails` in [create checkout](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/checkouts#checkouts-1) and [create checkout session](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/drop-in-checkout-sessions#drop-in-checkout-sessions) requests to send Digital River the following [basic product data](https://docs.digitalriver.com/digital-river-api/skus#basic-versus-compliance-product-data): {% hint style="info" %} For complete specifications, refer to the [Checkouts API](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/checkouts) and [Checkout Sessions API](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/drop-in-checkout-sessions) reference documentation. {% endhint %} * [Unique identifier](#unique-identifier) * [Unique SKU group identifier](#unique-sku-group-identifier) * [Country of origin](#country-of-origin) * [Name and description](#name-and-description) * [Image and URL](#image-and-url) * [Weight and weight unit](#weight-and-weight-unit) * [Part number](#part-number) {% code title="POST /checkouts" %} ```javascript 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 } ] }' ``` {% endcode %} ### 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](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/sku-groups) that the product belongs to. You're required to provide this identifier because Digital River uses it to access this [product's compliance data](https://docs.digitalriver.com/digital-river-api/skus#basic-versus-compliance-product-data). For details, refer to [Grouping SKUs](https://docs.digitalriver.com/digital-river-api/product-management/setting-up-sku-groups). [Create checkout requests](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/checkouts#checkouts-1) throws the following errors if you send `productDetails` that doesn't contain a `skuGroupId`: {% code title="400 Bad Request" %} ```javascript { "type": "bad_request", "errors": [ { "code": "missing_parameter", "parameter": "skuGroupId", "message": "An item of type sku is missing a skuGroupId parameter." } ] } ``` {% endcode %} ### Country of origin The `countryOfOrigin` is a two-letter [Alpha-2 country code](https://www.iban.com/country-codes) as described in the [ISO 3166](https://www.iso.org/iso-3166-country-codes.html) international standard. This attribute represents the country where a product was manufactured. [Create checkout](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/checkouts#checkouts-1) requests throws the following errors if you send `productDetails`, and it doesn't contain `countryOfOrigin`: {% code title="400 Bad Request" %} ```javascript { "type": "bad_request", "errors": [ { "code": "missing_parameter", "parameter": "countryOfOrigin", "message": "must not be null" } ] } ``` {% endcode %} [Create checkout](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/checkouts#checkouts-1) requests throws the following errors if you send `productDetails`, and it contains an invalid `countryOfOrigin`: {% code title="400 Bad Request" %} ```javascript { "type": "bad_request", "errors": [ { "code": "invalid_parameter", "parameter": "countryOfOrigin", "message": "'KP' is not a valid Country of Origin." } ] } ``` {% endcode %} ### 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:
ResourceParameter name
CheckoutsitemBreadcrumb
Checkout-sessionscategories
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](https://docs.digitalriver.com/digital-river-api/using-our-services/item-classification), then all of your [physical products](https://docs.digitalriver.com/digital-river-api/skus#how-products-are-classified-as-physical-or-digital) must have an `itemBreadcrumb` / `categories`. {% hint style="success" %} Even if you're not currently making [cross-border](https://docs.digitalriver.com/digital-river-api/general-resources/glossary#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. {% endhint %} We recommend making your taxonomies as detailed as possible. This will increase the probability that the [tariff codes](https://docs.digitalriver.com/digital-river-api/general-resources/glossary#tariff-code) 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. {% hint style="success" %} In [low-code checkouts](https://docs.digitalriver.com/digital-river-api/integration-options/low-code-checkouts), `name` is displayed in the order summary section. {% endhint %} ### 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](https://docs.digitalriver.com/digital-river-api/payments/payment-integrations-1/digitalriver.js/payment-methods/klarna) then `productDetails` must contain an `image` and `url`. In [Prebuilt Checkout](https://docs.digitalriver.com/digital-river-api/integration-options/low-code-checkouts/drop-in-checkout), each `items[].productDetails.image` in a [checkout-session](https://www.digitalriver.com/docs/digital-river-api-reference/#tag/Drop-in-Checkout-Sessions) is displayed in the [checkout modal's](https://docs.digitalriver.com/digital-river-api/integration-options/low-code-checkouts/drop-in-checkout#drop-in-checkout-modal-window) order summary section. ### Weight and weight unit For [physical products](https://docs.digitalriver.com/digital-river-api/skus#how-products-are-classified-as-physical-or-digital), `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](https://docs.digitalriver.com/digital-river-api/general-resources/glossary#cross-border), then we recommend that you pass the `weight` and `weightUnit` of all of your catalog's [physical products](https://docs.digitalriver.com/digital-river-api/skus#how-products-are-classified-as-physical-or-digital). 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](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/creating-checkouts/landed-costs). If you send a [create ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/checkouts#checkouts-1)or [update checkout](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/checkouts#checkouts-id-1) request whose `shipTo.address.country` represents one of these nations, and any `productDetails` in the checkout's [`items[]`](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/creating-checkouts/describing-the-items) are missing `weight`, then the following error is thrown: {% tabs %} {% tab title="400 Bad Request" %} ```javascript { "type": "bad_request", "errors": [ { "code": "missing_parameter", "message": "The weight is missing.", "parameter": "weight" } ] } ``` {% endtab %} {% endtabs %} ### 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](https://docs.digitalriver.com/digital-river-api/skus#skus) and [`productDetails`](https://docs.digitalriver.com/digital-river-api/skus#product-details) 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](https://docs.digitalriver.com/digital-river-api/skus#basic-versus-compliance-product-data), they're contained in the referenced [SKU group](https://docs.digitalriver.com/digital-river-api/product-management/setting-up-sku-groups). For details, refer to [Grouping SKUs](https://docs.digitalriver.com/digital-river-api/product-management/setting-up-sku-groups). {% hint style="info" %} SKUs also have a [`manufacturerId`](https://docs.digitalriver.com/digital-river-api/creating-and-updating-skus#manufacturer-id-and-part-number) and this attribute is not in `productDetails`. In [Digital River coordinated fulfillments](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/handling-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. {% endhint %}