Managing SKUs
Learn how to manage SKUs and understand how their configuration affects downstream processes
Depending on how you send product data in create checkout or create checkout-session requests, SKUs can contain compliance and/or basic product data.
How you define SKUs influences numerous downstream processes. This includes whether a product is classified as physical or digital and who acts as its fulfillment coordinator.
Once defined, you have the option to either create or upsert a SKU. After that, a SKU can then be updated or deleted. We also provide you the ability to retrieve a SKU by its unique identifier or search for SKUs using optional filters.
- A SKU's export control classification number affects whether a product requires a U.S. export/re-export license.
- In Digital River coordinated fulfillments that use the orchestrated model, you need to set a SKU's
managedFulfillmentflag.
A product's identifier in your system should ideally match the SKU's
id in our system. This ensures that synchronization is possible and that SKUs work properly during checkouts and checkout-sessions. As a result, it's best practice to (1) specify your own SKU id and (2) ensure it matches your product's universally unique identifier.Some characters however are not allowed. If you submit a
POST/skus and id contains one or more whitespaces, a 400 Bad Request is returned.400 Bad Request
{
"type": "bad_request",
"errors": [
{
"code": "invalid_parameter",
"parameter": "id",
"message": "'UGG BB PUR 06' is not a valid SKU ID."
}
]
}
In the same request type, an
id that contains certain special characters (such as /, [ , ] , { , } , < , >, and ^) results in a 500 Internal Server Error. Therefore, we recommend restricting a SKU's id to the following character set:- Numbers from
0to9 - Upper case letters from
AtoZ - Lower case letters from
atoz - Hyphens:
- - Underscores:
_
A SKU's
countryOfOrigin is a two-letter Alpha-2 country code as described in the ISO 3166 international standard. It represents the country where a product was manufactured.Invalid country codes return a
400 Bad Request:{
"type": "bad_request",
"errors": [
{
"code": "invalid_parameter",
"parameter": "countryOfOrigin",
"message": "'KP' is not a valid Country of Origin."
}
]
}
A SKU's
eccn represents its Export Control Classification Number (ECCN). This value determines whether:- A product requires a U.S. export/re-export license
- A product contains any other license requirements/restrictions
- A product has an end use which is prohibited by applicable export control laws
Digital River's legal documentation lists ECCNs pre-approved for use in the Digital River 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, please contact [email protected]​
A SKU's
hsCode represents a Harmonized System code. By setting this parameter, you're flagging a physical product as eligible for cross-border shipping. When configuring the landed cost feature, setting a SKU's hsCode is one of the available options for sending HS code.The format of the code is
####.##.####, where # represents a numeric digit between 0 and 9. The first six digits are mandatory. Any code longer than six digits but less than ten digits is optional and based on the country's preference. The period is not included in the character count.Digital River only validates that the format of the Harmonized System code you provide is correct. We don't determine whether the code accurately classifies your product.
For example, the full ten-digit code for Jasmine rice in the United States is 1006.20.4025. If that's the value you specify, we don't check to make sure your product fits into that category.
Incorrectly formatted
hsCode values return a 400 Bad Request:JSON
{
"type": "bad_request",
"errors": [
{
"code": "invalid_parameter",
"parameter": "hsCode",
"message": "'1234.56.YW' is not a valid HS code."
}
]
}
The
skuGroupId uniquely identifies the SKU group associated with the SKU. For more information, refer to the Grouping SKUs page.A manufacturer part number (MPN) is a unique code issued by manufacturers to identify a part/product. This is represented by a SKU's
partNumber.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/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.
In Digital River coordinated fulfillments that use the orchestrated model, you'll need to meet our managed fulfillment requirements so that you can create and update SKU-inventory item pairs.
SKU attribute | Requirement | Sample error |
|---|---|---|
managedFulfillment | The specified value must be DRGlobalFulfillment. | 400 Bad Request{ "type": "bad_request","errors": [ {"code": "invalid_parameter", "parameter":"managedFulfillment", "message": "'DRGlobalFulfillment^&%^' is not a valid item type." }] } |
taxCode | 400 Bad Request{ "type": "bad_request","errors": [ {"code": "invalid_parameter", "parameter": "taxCode","message": "'4512.100' is not a valid parameter." }] } | |
partNumber | The value must be specified. | 400 Bad Request{ "type": "bad_request","errors": [ {"code": "invalid_parameter", "parameter": "partNumber", "message": "'null' is not a valid parameter." }] } |
manufacturerId | If you specify this value, then the partNumber must be valid. In other words, the combination of manufacturerId and partNumber must be correct. | 409 Conflict{ "type": "conflict","errors": [ {"code": "invalid_parameter", "parameter": "manufacturerId", "message": "Invalid manufacturer ID. The manufacturer ID and manufacturer part # combination could not be found." }] } |
When you create or upsert a SKU that meets our managed fulfillment requirements, Digital River synchronously creates an associated inventory item. These SKU-inventory item pairs have shared attributes with identical values.
POST/skus
SKU
GET/inventory-items/{id}
Inventory Item
curl --location --request POST 'https://api.digitalriver.com/skus' \
--header 'Authorization: Bearer <API_key>' \
--header 'Content-Type: application/json' \
...
--data-raw '{
"id": "sku_demo_1617140947939",
"eccn": "EAR99",
"countryOfOrigin": "DE",
"taxCode": "4323.310_A",
"partNumber": "DEMOPARTNUMBER2",
"name": "name_demo_1617140947939",
"weight": 8.88,
"weightUnit": "oz",
"metadata": {
"application": "iOS-LLL"
},
"managedFulfillment": "DRGlobalFulfillment"
}'
{
"id": "sku_demo_1617146803587",
"createdTime": "2021-03-30T23:26:43Z",
"name": "name_demo_1617146803587",
"eccn": "EAR99",
"partNumber": "DEMOPARTNUMBER2",
"taxCode": "4323.310_A",
"countryOfOrigin": "DE",
"metadata": {
"application": "iOS-LLL"
},
"weight": 8.88,
"weightUnit": "oz",
"fulfill": false,
"allowOversell": true,
"liveMode": false,
"managedFulfillment": "DRGlobalFulfillment",
"physical": true
}
curl --location --request GET 'https://api.digitalriver.com/inventory-items/sku_demo_1617146803587' \
--header 'Authorization: Bearer <API_key>' \
...
--data-raw ''
{
"id": "sku_demo_1617146803587",
"manufacturerId": "20013",
"partNumber": "DEMOPARTNUMBER2",
"allowOversell": true,
"createdTime": "2021-03-30T23:26:43Z",
"eccn": "EAR99",
"countryOfOrigin": "DE",
"liveMode": false
}
Since the SKU's
id and the inventory item's id are the same, you can use this value to describe items in checkouts, check inventory levels, request shipping quotes and make reservations.Every subsequent modification of a
managedFulfillment SKU (assuming the update SKU request satisfies our managed fulfillment requirements) synchronously updates the paired inventory item.POST/skus/{id}
SKU
GET/inventory-items/{id}
Inventory Item
curl --location --request POST 'https://api.digitalriver.com/skus/sku_demo2_1617153759250' \
--header 'Authorization: Bearer <API_key>' \
--header 'Content-Type: application/json' \
--data-raw '{
"countryOfOrigin": "US"
}'
{
"id": "sku_demo2_1617153759250",
"createdTime": "2021-03-31T01:22:39Z",
"name": "name_demo2_1617153759250",
"eccn": "EAR99",
"partNumber": "DEMOPARTNUMBER2",
"updatedTime": "2021-03-31T01:23:04Z",
"taxCode": "4323.310_A",
"countryOfOrigin": "US",
"metadata": {
"application": "iOS-LLL"
},
"weight": 8.88,
"weightUnit": "oz",
"fulfill": false,
"allowOversell": true,
"liveMode": false,
"managedFulfillment": "DRGlobalFulfillment",
"physical": true
}
curl --location --request GET 'https://api.digitalriver.com/inventory-items/sku_demo2_1617153759250' \
--header 'Authorization: Bearer <API_key>' \
...
--data-raw ''
{
"id": "sku_demo2_1617153759250",
"manufacturerId": "20013",
"partNumber": "DEMOPARTNUMBER2",
"allowOversell": true,
"createdTime": "2021-03-31T01:22:43Z",
"updatedTime": "2021-03-31T01:23:04Z",
"eccn": "EAR99",
"countryOfOrigin": "US",
"liveMode": false
}
So, if you have an existing SKU, and you want to make Digital River its fulfillment coordinator, you can set
managedFulfillment to DRGlobalFulfillment and then send this value (along with any other values that must be added or modified to satisfy our managed fulfillment requirements) in an update SKU request.Once Digital River internally creates an inventory item, do not directly update or delete it through the Inventory Items API. These operations modify and delete the inventory item but do not affect its paired SKU.
When you want to remove Digital River as a product's fulfillment coordinator, set
managedFulfillment to null in an update SKU request. This deletes the inventory item paired with the SKU. If you then attempt to retrieve the inventory item, you receive a 404 Not Found.POST/skus/{id}
SKU
GET/inventory-items/{id}
Inventory Item
curl --location --request POST 'https://api.digitalriver.com/skus/sku_demo_1617153057380' \
--header 'Authorization: Bearer <API_key>' \
--header 'Content-Type: application/json' \
...
--data-raw '{
"managedFulfillment": null
}'
{
"id": "sku_demo_1617153057380",
"createdTime": "2021-03-31T01:10:57Z",
"name": "name_demo_1617153057380",
"eccn": "EAR99",
"partNumber": "DEMOPARTNUMBER2",
"updatedTime": "2021-03-31T01:19:14Z",
"taxCode": "4323.310_A",
"countryOfOrigin": "DE",
"metadata": {
"application": "iOS-LLL"
},
"weight": 8.88,
"weightUnit": "oz",
"fulfill": false,
"allowOversell": true,
"liveMode": false,
"physical": true
}
curl --location --request GET 'https://api.digitalriver.com/inventory-items/sku_demo_1617153057380' \
--header 'Authorization: Bearer <API_key>' \
...
--data-raw ''
{
"type": "not_found",
"errors": [
{
"code": "not_found",
"parameter": "id",
"message": "InventoryItem 'sku_demo_1617153057380' not found."
}
]
}
A SKU's
name is required but description is optional.imageto 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.urlto specify the URL of a resource that contains the product's description.
In Drop-in Checkout, the
image of each SKU referenced in the checkout-sessions' items[] 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
image and 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.For physical SKUs, you can provide the product’s
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. As a result, without this data, we're unable to calculate landed costs.
If you send a create or update checkout request that contains a
shipTo.address.country from one of these nations, and any SKU referenced in the checkout's items[] array is 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 SKUs.In Digital River coordinated fulfillments, you may decide to build your integration such that customers can reserve out of stock items or pre-order items not yet in stock. To do this, you can use the SKU's
allowOversell flag.If you set the flag to
true, customers can reserve the item even when inventory is not available. When set to false, customers won't be able to place a hold on an item when its inventory levels are not sufficient.SKU's must contain a
taxCode. This value determines whether a product gets classified as physical or digital and ensures that the correct tax is applied to the product. You can modify a SKU's taxCode in either an upsert or update SKU request.The following table lists the tax codes currently supported by Digital River and whether they're associated with physical or digital products.
If you'd like to use a tax code not listed here, contact your account representative.
If a SKU's
taxCode is in the table's physical grouping, then it's physical attribute is true . Conversely, if a SKU's taxCode is in the digital grouping, then physical is false.Group | Type | Tax Code | Associated with physical or digital products? |
|---|---|---|---|
Downloadable Goods (Non-Software) | Digital Image | 4512.100 | Digital |
Downloadable Goods (Non-Software) | Virtual Goods | 55111509.12 | Digital |
Downloadable Goods (Non-Software) | Music | 55111512.100 | Digital |
Downloadable Goods (Non-Software) | Electronic Newspapers (Includes Subscriptions) | 55111507.120 | Digital |
Downloadable Goods (Non-Software) | Electronic Magazines (Includes Subscriptions) | 55111506.120 | Digital |
Downloadable Goods (Non-Software) | Educational / Vocational Texts | 55111513.120 | Digital |
Downloadable Goods (Non-Software) | eBooks | 55111502.120 | Digital |
Food, Beverage & Household | Non-Prescription Vitamins | 51191905 | Physical |
Food, Beverage & Household | Non-Prescription Drugs | 5124 | Physical |
Food, Beverage & Household | Miscellaneous Supplies | 47 | Physical |
Food, Beverage & Household | Food - General | 50 | Physical |
Physical Goods | Automatic Blood Pressure Monitors | 531316.150 | Physical |
Physical Goods | Energy Star - Stove | 52141545.100 | Physical |
Physical Goods | Energy Star - Dehumidifier | 4010.200 | Physical |
Physical Goods | Energy Star - Air Conditioner | 4010.100 | Physical |
Physical Goods | Energy Star - Ceiling Fan | 40101609.100 | Physical |
Physical Goods | Energy Star - Light Bulbs | 39101629.100 | Physical |
Physical Goods | Energy Star - Freezer | 52141506.100 | Physical |
Physical Goods | Energy Star - Refrigerator | 52141501.100 | Physical |
Physical Goods | Energy Star - Washer | 52141601.100 | Physical |
Physical Goods | Energy Star - Dryer | 52141602.100 | Physical |
Physical Goods | Energy Star - Dishwasher | 52141505.100 | Physical |
Physical Goods | Computer Supplies - Subscription | 4321_S | Physical |
Physical Goods | Mobile Devices | 43211509 | Physical |
Physical Goods | Medical Equipment | 42 | Physical |
Physical Goods | Consumer Electronics (Photographic, Filming, or Video Equipment) | 4512 | Physical |
Physical Goods | Consumer Electronics (T.V., Monitor, Display) - Size (>4"<15") | 52161500_C | Physical |
Physical Goods | Consumer Electronics (T.V., Monitor, Display) - Size (= or >35") | 52161500_B | Physical |
Physical Goods | Consumer Electronics (T.V., Monitor, Display) - Size (= or >15"<35") | 52161500_A | Physical |
Physical Goods | Video Game Consoles and Accessories | 601410 | Physical |
Physical Goods | Uniforms | 531027 | Physical |
Physical Goods | Sports and Recreation Equipment | 49 | Physical |
Physical Goods | School Supplies | 441216 | Physical |
Physical Goods | School Instructional Materials | 6010 | Physical |
Physical Goods | Safety Clothing (Not Suitable for Everyday Use) | 461815.100 | Physical |
Physical Goods | Printed Media (Non-Subscription) | 5510 | Physical |
Physical Goods | Newspapers (Includes Subscription) | 55101504.100 | Physical |
Physical Goods | Magazines (Includes Subscriptions) | 55101506.100 | Physical |
Physical Goods | General Merchandise | 601410 | Physical |
Physical Goods | Consumer Electronics (Non-Computer) | 5216 | Physical |
Physical Goods | Computers | 4321_A | Physical |
Physical Goods | Computer Supplies | 4321_C | Physical |
Physical Goods | Computer Peripheral Devices | 4321_B | Physical |
Physical Goods | Books - General Purpose | 55101510 | Physical |
Physical Goods | Books - Educational and Vocational Texts | 55101509 | Physical |
Physical Goods | Backpacks | 53121603 | Physical |
Physical Goods | Apparel & Footwear (Everyday Use) | 531029.100 | Physical |
Physical Goods | Apparel & Footwear (Athletic Use) | 531029.200 | Physical |
Services & Miscellaneous | Installation Service Charges Provided by the Seller of TPP | 70.360 | Digital |
Services & Miscellaneous | Mandatory Maintenance Agreements - Services and Upgrades, Only for Downloadable | 81112201.121 | Digital |
Services & Miscellaneous | Computer Services | 8111 | Digital |
Services & Miscellaneous | Consulting Services | 70.60 | Digital |
Services & Miscellaneous | General Services | 70.100 | Digital |
Services & Miscellaneous | Gift Cards | 70.120 | Digital |
Services & Miscellaneous | Mandatory Maintenance Agreements - Services and Upgrades, for Downloadable and Physical Products | 81112201.120 | Digital |
Services & Miscellaneous | Non-warranty Repairs | 70.150 | Digital |
Services & Miscellaneous | Online Data Storage | 811121 | Digital |
Services & Miscellaneous | Optional Maintenance Agreements - Services and Upgrades, for Downloadable Products | 81112201.420 | Digital |
Services & Miscellaneous | Optional Maintenance Agreements - Services and Upgrades, for Physical Products | 81112201.410 | Digital |
Services & Miscellaneous | Optional Maintenance Agreements - Services Only, for Downloadable and Physical Products | 81112201.200 | Digital |
Services & Miscellaneous | Seminar Classes | 70.300 | Digital |
Services & Miscellaneous | Software Training | 70.280 | Digital |
Services & Miscellaneous | Technical Support | 811118.100 | Digital |
Services & Miscellaneous | Virtual Currency | 70.120_A | Digital |
Services & Miscellaneous | Membership Dues - General | 70.220 | Digital |
Services & Miscellaneous | Membership Dues & Professional Organization | 70.222 | Digital |
Services & Miscellaneous | Web Hosting | 81112105 | Digital |
Software (Downloadable & Physical) | Backup Media (CD/DVD) - One Disc per Order | 4323.310_B | Physical |
Software (Downloadable & Physical) | Software as a Service | 81112106 | Digital |
Software (Downloadable & Physical) | Physical Software (Gaming Only) | 4323.310_E | Physical |
Software (Downloadable & Physical) | Physical Software (Non-Gaming) | 4323.310_A | Physical |
Software (Downloadable & Physical) | Physical Media Kits | 4323.310_D | Physical |
Software (Downloadable & Physical) | Backup Media (CD/DVD) - One Disc per Product | 4323.310_C | Physical |
Software (Downloadable & Physical) | Downloadable Media Kits | 4323.320_C | Digital |
Software (Downloadable & Physical) | Downloadable Software (Gaming Only) | 4323.320_D | Digital |
Software (Downloadable & Physical) | Downloadable Software (Non-Gaming, Includes Software Subscriptions) | 4323.320_A | Digital |
Software (Downloadable & Physical) | Extended Download Service | 4323.320_B | Digital |
Warranties | Optional Warranties - Purchased at Time of Sale of for Consumer Goods, Labor Only | 95.210 | Digital |
Warranties | Optional Warranties - NOT Purchased at Time of Sale of for Consumer Goods, Parts & Labor | 95.222 | Digital |
Warranties | Optional Warranties - NOT Purchased at Time of Sale of for Consumer Goods, Labor Only | 95.220 | Digital |
Warranties | Mandatory Warranties | 95.100 | Digital |
Warranties |