Managing SKUs
Learn how to manage SKUs and understand how their configuration affects downstream processes.
How you define a SKU influences numerous downstream processes, including whether the product is classified as physical or digital and whether Digital River acts as its fulfillment coordinator. Once defined, you have the option to create or upsert a SKU. After that, the 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.
Once created, you use a SKU to describe the items in your checkout.

How products are classified as physical or digital

When you set the tax code, Digital River uses the specified value to classify a product as either physical or digital. This classification then determines the address requirements for any orders that contain this SKU. Whether the product is classified as physical or digital also determines the selling entity, which affects how taxes are calculated and whether landed costs are applicable.
The SKU resource contains a physical attribute that allows you to determine whether the SKU is classified as digital or physical without having to reference the tax code table. If the SKU's tax code is in the physical grouping, then physical is true . Conversely, if the SKU's tax code is in the digital grouping, then physical is false.

Defining a SKU

The following are the key attributes you can define in the SKUs resource. For a complete listing, and information on whether they are required or optional, refer to the SKUs API reference page.
The tax code you specify determines whether the SKU is classified as physical or digital. As part of configuring the landed cost feature, you'll need to set the harmonized system code. The export control classification number affects whether the SKU requires a U.S. export/re-export license. You should set the managed fulfillment flag when you're using the Digital River model to coordinate the fulfillment of a physical product.

Unique identifier

The id represents the unique identifier of a SKU. During SKU creation, you can specify your ownid. The only restriction we impose is on whitespace characters. If you submit a POST/skus or PUT/skus/{id} request, and id contains one or more blank spaces, a 400 Bad Request is returned.
400 Bad Request
1
{
2
"type": "bad_request",
3
"errors": [
4
{
5
"code": "invalid_parameter",
6
"parameter": "id",
7
"message": "'UGG BB PUR 06' is not a valid SKU ID."
8
}
9
]
10
}
Copied!

Country of origin

ECCN

The eccn represents a SKU's export control classification number.

Harmonized system code

The hsCode represents the Harmonized System code.

SKU group identifier

The skuGroupId uniquely identifies the SKU group to which this SKU belongs.

Manufacturer id and part number

For physical products, you use manufacturerId and partNumber to specify the manufacturer's identifier and part number.

Managed fulfillments

The managedFulfillment flag indicates whether Digital River coordinates a product's fulfillment. You should only set this parameter when you're using the Digital River fulfillment model to physically fulfill a product.

Managed fulfillment requirements

If you're using the Digital River fulfillment model to coordinate a product's physical fulfillment, then the SKU must meet the following requirements:
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
The specified value must be associated with a physical product.
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." }
] }

Creating and updating SKU-Inventory Item pairs

When you create or upsert a SKU that meets the managed fulfillment requirements, Digital River synchronously creates an associated Inventory Item. These SKU-Inventory Item pairs have common attributes with identical values.
POST/skus
SKU
GET/inventory-items/{id}
Inventory Item
1
curl --location --request POST 'https://api.digitalriver.com/skus' \
2
--header 'Authorization: Bearer <API_key>' \
3
--header 'Content-Type: application/json' \
4
...
5
--data-raw '{
6
"id": "sku_demo_1617140947939",
7
"eccn": "EAR99",
8
"countryOfOrigin": "DE",
9
"taxCode": "4323.310_A",
10
"partNumber": "DEMOPARTNUMBER2",
11
"name": "name_demo_1617140947939",
12
"weight": 8.88,
13
"weightUnit": "oz",
14
"metadata": {
15
"application": "iOS-LLL"
16
},
17
"managedFulfillment": "DRGlobalFulfillment"
18
}'
Copied!
1
{
2
"id": "sku_demo_1617146803587",
3
"createdTime": "2021-03-30T23:26:43Z",
4
"name": "name_demo_1617146803587",
5
"eccn": "EAR99",
6
"partNumber": "DEMOPARTNUMBER2",
7
"taxCode": "4323.310_A",
8
"countryOfOrigin": "DE",
9
"metadata": {
10
"application": "iOS-LLL"
11
},
12
"weight": 8.88,
13
"weightUnit": "oz",
14
"fulfill": false,
15
"allowOversell": true,
16
"liveMode": false,
17
"managedFulfillment": "DRGlobalFulfillment",
18
"physical": true
19
}
Copied!
1
curl --location --request GET 'https://api.digitalriver.com/inventory-items/sku_demo_1617146803587' \
2
--header 'Authorization: Bearer <API_key>' \
3
...
4
--data-raw ''
Copied!
1
{
2
"id": "sku_demo_1617146803587",
3
"manufacturerId": "20013",
4
"partNumber": "DEMOPARTNUMBER2",
5
"allowOversell": true,
6
"createdTime": "2021-03-30T23:26:43Z",
7
"eccn": "EAR99",
8
"countryOfOrigin": "DE",
9
"liveMode": false
10
}
Copied!
Since the id of the SKU and Inventory Item are the same, you can use this value to make downstream calls to the Inventory Levels API, Shipping Quotes API, and Reservations API.
Every subsequent modification of a managed fulfillment SKU (assuming the update SKU request satisfies the managed fulfillment requirements) synchronously updates the associated Inventory Item.
POST/skus/{id}
SKU
GET/inventory-items/{id}
Inventory Item
1
curl --location --request POST 'https://api.digitalriver.com/skus/sku_demo2_1617153759250' \
2
--header 'Authorization: Bearer <API_key>' \
3
--header 'Content-Type: application/json' \
4
--data-raw '{
5
"countryOfOrigin": "US"
6
}'
Copied!
1
{
2
"id": "sku_demo2_1617153759250",
3
"createdTime": "2021-03-31T01:22:39Z",
4
"name": "name_demo2_1617153759250",
5
"eccn": "EAR99",
6
"partNumber": "DEMOPARTNUMBER2",
7
"updatedTime": "2021-03-31T01:23:04Z",
8
"taxCode": "4323.310_A",
9
"countryOfOrigin": "US",
10
"metadata": {
11
"application": "iOS-LLL"
12
},
13
"weight": 8.88,
14
"weightUnit": "oz",
15
"fulfill": false,
16
"allowOversell": true,
17
"liveMode": false,
18
"managedFulfillment": "DRGlobalFulfillment",
19
"physical": true
20
}
Copied!
1
curl --location --request GET 'https://api.digitalriver.com/inventory-items/sku_demo2_1617153759250' \
2
--header 'Authorization: Bearer <API_key>' \
3
...
4
--data-raw ''
Copied!
1
{
2
"id": "sku_demo2_1617153759250",
3
"manufacturerId": "20013",
4
"partNumber": "DEMOPARTNUMBER2",
5
"allowOversell": true,
6
"createdTime": "2021-03-31T01:22:43Z",
7
"updatedTime": "2021-03-31T01:23:04Z",
8
"eccn": "EAR99",
9
"countryOfOrigin": "US",
10
"liveMode": false
11
}
Copied!
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 the managed fulfillment requirements) in an update SKU request.
Once Digital River internally creates an Inventory Item, you should not update or delete it through the Inventory Items API. These operations modify and delete the Inventory Item but do not affect its associated SKU.
When you want to remove Digital River as a product's fulfillment coordinator, set managedFulfillment to null in an update SKU request. This operation deletes the Inventory Item associated 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
1
curl --location --request POST 'https://api.digitalriver.com/skus/sku_demo_1617153057380' \
2
--header 'Authorization: Bearer <API_key>' \
3
--header 'Content-Type: application/json' \
4
...
5
--data-raw '{
6
"managedFulfillment": null
7
}'
Copied!
1
{
2
"id": "sku_demo_1617153057380",
3
"createdTime": "2021-03-31T01:10:57Z",
4
"name": "name_demo_1617153057380",
5
"eccn": "EAR99",
6
"partNumber": "DEMOPARTNUMBER2",
7
"updatedTime": "2021-03-31T01:19:14Z",
8
"taxCode": "4323.310_A",
9
"countryOfOrigin": "DE",
10
"metadata": {
11
"application": "iOS-LLL"
12
},
13
"weight": 8.88,
14
"weightUnit": "oz",
15
"fulfill": false,
16
"allowOversell": true,
17
"liveMode": false,
18
"physical": true
19
}
Copied!
1
curl --location --request GET 'https://api.digitalriver.com/inventory-items/sku_demo_1617153057380' \
2
--header 'Authorization: Bearer <API_key>' \
3
...
4
--data-raw ''
Copied!
1
{
2
"type": "not_found",
3
"errors": [
4
{
5
"code": "not_found",
6
"parameter": "id",
7
"message": "InventoryItem 'sku_demo_1617153057380' not found."
8
}
9
]
10
}
Copied!

Deleting SKU-Inventory Item pairs

A delete SKU request deletes both the SKU and its associated Inventory Item.

Name and description

When creating a SKU, you're required to provide its name but specifying a description is optional.

Image and url

The image attribute allows you to display an image of the product to a customer. The url is the product url. These two values are only needed when the customer is using either ApplePay or GooglePay to pay for the purchase.

Weight and weight unit

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 generate a landed cost calculation.
If you attempt to create or update a checkout using a ship to country from one of these nations, and any of the SKU's in the checkout's items array are missing weight, then the following 400 Bad Request is thrown:
400 Bad Request
1
{
2
"type": "bad_request",
3
"errors": [
4
{
5
"code": "missing_parameter",
6
"message": "The weight is missing.",
7
"parameter": "weight"
8
}
9
]
10
}
Copied!
So, if your site intends on selling physical products across international borders, we recommend that you define weight and weightUnit for all physical SKUs in your catalog.

Allow oversell

Refer to the Allow oversell section on the Common Attributes page.

Tax code

When you create a SKU, the request must include a taxCode. This value determines whether we classify the product as physical or digital and ensures we apply the correct tax. You can later modify a SKU's tax code in either an upsert or update SKU request.

Supported tax codes

The following table lists the tax codes currently supported by Digital River and whether they are associated with physical or digital products.
If you'd like to use a tax code not listed here, contact your account representative.
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
Optional Warranties - Purchased at Time of Sale of for Consumer Goods, Parts & Labor
95.212
Digital

Using a SKU

When describing items in a POST/checkouts or POST/invoices request, you must specify one or more SKU identifiers.

SKUs API operations

You can use the SKUs API to create and update, upsert, retrieve, search for, and delete SKUs.

Creating and updating a SKU

Creating and updating SKUs are nearly identical processes. The main difference is that in a create SKU request you're allowed to specify the unique identifier, but in an update SKU request you must pass in its unique identifier as a path parameter.
Additionally, when creating a SKU, you're required to specify the export control classification number, tax code, a product name, and country of origin.
The following POST/skus request creates a physical SKU because the taxCode parameter references physical software:
cURL
1
curl --location --request POST 'https://api.digitalriver.com/skus' \
2
--header 'Authorization: Bearer <API_key>' \
3
--header 'Content-Type: text/plain' \
4
--data-raw '{
5
"id": "3170de75-68f8-4d54-9176-211f0e680136",
6
"eccn": "EAR99",
7
"countryOfOrigin": "US",
8
"taxCode": "4323.310_A",
9
"partNumber": "100-440-0.750-3434-A",
10
"name": "Test Product"
11
}'
Copied!
A 201 Created response returns a SKU object:
SKU
1
{
2
"id": "3170de75-68f8-4d54-9176-211f0e680136",
3
"createdTime": "2021-04-05T16:23:38Z",
4
"name": "Test Product",
5
"eccn": "EAR99",
6
"partNumber": "100-440-0.750-3434-A",
7
"taxCode": "4323.310_A",
8
"countryOfOrigin": "US",
9
"fulfill": false,
10
"allowOversell": true,
11
"liveMode": false,
12
"physical": true
13
}
Copied!

Upserting a SKU

The upsert request uses a PUT method to either create or update a SKU object. If the specified SKU doesn't exist, the operation creates one. Otherwise, if the SKU already exists, then the parameters specified in the request body update the SKU's corresponding attributes. The upsert operation is basically a create and update request rolled into one.
For example, if you'd like to update the tax code or ECCN of a product, but you can't determine whether the SKU has already been created, then an upsert request is appropriate.
Since the SKU might not exist when you make the PUT request, the same parameters as a create request are required.

Upsert request

Let's say your Tax department informs you that an existing software product now falls into a new tax category. As a result, you need to update the taxCode value of the SKU. The following example shows how to do this using an upsert request.
When submitting the request, you need to pass in the SKU identifier as a path parameter. You also need to provide the eccn, taxCode, name, and countryOfOrigin.
cURL
1
curl https://api.digitalriver.com/skus/sku_5823595932 \
2
-u <API_key>: \
3
-d eccn="EAR99" \
4
-d taxCode="81112106" \
5
-d name="Wiser Word Editor" \
6
-d countryOfOrigin="US"
Copied!

Upsert response

If your request is successful, you'll receive either a 200 OK or a 201 Created response, depending on whether the SKU already exists or was created by the request.
A 200 OK response indicates the SKU was created prior to the request and is now updated. In the following example, note that the createdTime is earlier than the updatedTime.
SKU
1
{
2
"createdTime": "2020-01-11T20:48:03Z",
3
"id": "sku_5823595932",
4
"eccn": "EAR99",
5
"taxCode": "81112106",
6
"name": "Wiser Word Editor",
7
"description": "Wiser Word Editor",
8
"image": "https://imageurl.com",
9
"url": "https://producturl.com",
10
"countryOfOrigin": "US",
11
"physical": false,
12
"liveMode": false,
13
"metadata": {
14
"coupon": "iOS"
15
},
16
"updatedTime": "2020-04-14T18:28:09Z"
17
}
Copied!
A 201 Created response indicates that the SKU did not exist at the time of the request but has now been created. In the following example, the createdTime is identical to the updatedTime.
SKU
1
{
2
"createdTime": "2020-04-14T18:28:09Z",
3
"id": "sku_5823595932",
4
"eccn": "EAR99",
5
"taxCode": "81112106",
6
"name": "Wiser Word Editor",
7
"countryOfOrigin": "US",
8
"physical": false,
9
"updatedTime": "2020-04-14T18:28:09Z"
10
}
Copied!

Deleting a SKU

To delete a SKU, pass its unique identifier as a path parameter in a DELETE/skus/{id} request. This also deletes any Fee objects associated with the SKU.
Last modified 1mo ago