Managing SKUs
Gain a better understanding of a SKU's attributes and how they affect downstream processes
Depending on how you send product data in create checkout or create checkout-session requests, your SKUs might contain compliance and/or basic product data.
Once you define a SKU's attributes, you can perform a create or upsert operation. After that, the resource can be updated or deleted. You can also retrieve a SKU by its unique identifier or search for SKUs using various query parameters.
A SKU's
physical
attribute indicates whether Digital River has classified the product as physical or digital. For details, refer to how products are classified as physical or digital on the Product basics page.
A product's identifier in your system should ideally match the SKU's
id
in ours. This ensures that synchronization is possible and that SKUs work properly throughout an order's lifecycle. Therefore, we recommend that you specify your own id
and ensure it matches your product's universally unique identifier.If you don't specify
id
in the body of a create SKU request, then Digital River generates and returns a unique value.- Digits from
0
to9
- Upper case letters from
A
toZ
- Lower case letters from
a
toz
- Dots/points:
.
- Hyphens:
-
- Underscores:
_
If
id
contains any other character, then a 400 Bad Request
is returned:{
"type": "bad_request",
"errors": [
{
"code": "invalid_parameter",
"parameter": "id",
"message": "'89&56' is not a valid SKU ID."
}
]
}
A SKU's
itemBreadcrumb
represents a hierarchical classification system that organizes and categorizes your products based on their attributes, characteristics, and relationships. You'll typically structure itemBreadcrumb
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 SKUs must have an
itemBreadcrumb
. 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 this 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 also define 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. 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.If you submit an invalid country code, then Digital River returns a
400 Bad Request
:{
"type": "bad_request",
"errors": [
{
"code": "invalid_parameter",
"parameter": "countryOfOrigin",
"message": "'KP' is not a valid Country of Origin."
}
]
}
This value determines whether a product:
- Requires a U.S. export/re-export license
- Contains any other license requirements/restrictions
- Has an end use which is prohibited by applicable export control laws
Digital River's legal documentation lists ECCNs 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]
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 validates a Harmonized System code's format. We don't however determine whether
hsCode
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, then we don't check to make sure your product belongs in that category.
If you submit an incorrectly formatted
hsCode
, then Digital River returns a 400 Bad Request
:Error
{
"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 details, refer to Grouping SKUs.The
manufacturerId
represents the unique identifier of a part/product's manufacturer.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 before 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
GET /inventory-items/{id}
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 request satisfies our managed fulfillment requirements) synchronously updates the paired inventory item.POST /skus/{id}
GET /inventory-items/{id}
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
}
Once Digital River 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}
GET /inventory-items/{id}
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."
}
]
}
image
to specify the URL of a resource that holds the product's image. This resource should be similar to the image(s) you display to customers while they are reviewing products in your store.url
to specify the address of a resource that contains the product's description.
In Prebuilt Checkout, the
image
of each SKU referenced in the checkout-sessions' items[]
is displayed in the order summary section of the checkout modal.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 SKUs, you should provide a product’s
weight
denoted in a weightUnit
. The enumerated weightUnit
values are oz
, lb
, g
, and kg
. If you provide 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 SKUs.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.
If you send a create or update checkout request whose
shipTo.address.country
represents one of these nations, and any SKU referenced in the checkout's items[]
is 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"
}
]
}
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.A SKU's
taxCode
determines whether Digital River classifies a product as physical or digital and ensures that taxes on it are properly assessed. The following table lists the
taxCode
values currently supported by Digital River and whether each is associated with a physical or digital product.If you'd like to use a
taxCode
not listed here, contact your account representative.Group | Description | taxCode |
---|---|---|
Digital | Computer Software: Electronically Downloaded | DC020500 |
Digital | Games: Electronically Downloaded | DG010300 |
Digital | Dues/Membership Fees | OD020000 |
Digital | Online Skill Assessments | ST080010 |
Digital | Cloud Services: SaaS - License Agreement/Business Use | SW053003 |
Digital | Cloud Services: SaaS - Service Agreement | SW054000 |
Digital | Optional Maintenance Agreement, Warranties (On-Site) | SM020200 |
Digital | Computer Software (Prewritten/Canned) Electronically Downloaded (Business-To-Business) | DC010500 |
Digital | Cloud/Remote Storage | DC070000 |
Digital | Other Digital Goods -- No Physical Media | DO010000 |
Digital | Computer Software Implementation-Associated with The Sale of Software-Prewritten Software-Electronically Downloaded | SC070101 |
Digital | Computer Software Maintenance (Prewritten Software)-Optional (Electronically Downloaded)-Services Only (Remote Support) | SC100101 |
Digital | Computer Software Maintenance (Prewritten Software)-Optional (Electronically Downloaded)-Downloaded Updates, Etc. & Services | SC100102 |
Digital | Computer Software Maintenance (Prewritten Software)-Mandatory (Electronically Downloaded)-Downloaded Updates, Etc. & Services | SC100202 |
Digital | Training and Seminar: On-Site | ST080000 |
Digital | Training and Seminar: Online Live | ST087634 |
Digital | Transcription Services/Recorded Speech | ST158020 |
Digital | Implementation Services - Hosted Software, Server Not in The State, Performed On-Site - For Business Use (On-Site) | SW052021 |
Physical | General Merchandise (Tangible Personal Property) | P0000000 |
Physical | Consumer Electronics (Non-Computer) | PB0010000 |
Physical | Consumer Electronics (Photographic, Filming Equipment) | PB0010300 |
Physical | Video Game Consoles, Portable Electronics | PB0010504 |
Physical | General Clothing (Adult) | PC040100 |
Physical | Hats and Caps | PC040129 |
Physical | Handbags and Backpacks | PC040204 |
Physical | Computer Peripheral Devices | PC080500 |
Physical | Computer Supplies | PC080601 |
Physical | Laptop | PC080110 |
Physical | Mobile Phone | PC098213 |
Physical | Health Care Products-Over the Counter-Medicinal Group 1-Blood Pressure Testing Apparatus | PH050639 |
Physical | Video Games - Physical | DG010100 |
Physical | Bathing Suits and Caps (Adult) | PC040106 |
Physical | Bibs (Snow pants/Salopettes) | PC040109 |
Physical | Boots (Above Age 11) | PC040110 |
Physical | Coats and Jackets (Adult) | PC040111 |
Physical | Gloves (Leather) | PC040123 |
Physical | Scarves & Gaiters | PC040143 |
Physical | Adult Shoes | PC040144 |
Physical | Socks (Adult) | PC040148 |
Physical | Sunglasses | PC040207 |
Physical | Athletic Helmets | PC040306 |
Physical | Bicycle Helmets | PC040307 |
Physical | Goggles | PC040404 |
Physical | Children’s Clothing (Below Age 11) | PC040501 |
Physical | Children’s Clothing (Age 11-14) | PC040502 |
Physical | Children's Shoes | PC040503 |
Physical | Gift Cards | PG050000 |
Physical | Reusable Face Masks | PH402898 |
Physical | First Aid Kits | PH050676 |
Physical | Lanterns/Lamps | PO200108 |
Physical | Sleeping Bags | PO200114 |