Describing line items
Understand how to describe a checkout's products or services
You use a checkout's
items[] array to pass data on products and/or services in a customer's cart. The elements of items[] allow you to:After you create a checkout, we return an
items[].id that uniquely identifies each of a checkout's line items. This identifier is needed to modify the line item in a update checkout requests.Since update checkout requests only allow you to modify subscription, ship from and meta data, your create checkout request must include a line item's product data, price, and quantity.
For more information, refer to the sending the create checkout request section on the Building checkouts page.
In create checkout requests, you must provide Digital River both basic and compliance data on the products in a customer's cart. You have three options for passing this data. You can:
In this option, prior to checking out customers, you must define and create a SKU for each of the product's in your catalog. Each SKU needs to contain both basic and compliance data on that product.
POST/checkouts
curl --location --request POST 'https://api.digitalriver.com/checkouts' \
...
--data-raw '{
...
"items": [
{
"skuId": "d0c6c536-1a5b-4c1d-be86-92e3363a1e1f",
"quantity": 2,
"price": 10
}
]
}'
Once you submit this request, Digital River retrieves all the product data that we need from the referenced SKU.
This option requires you to keep the product catalog in your system synchronized with your SKUs in our system.
In this option, prior to checking out customers, you must define and create a SKU for each of the product's in your catalog. The SKUs only need to contain basic product data.
Before creating checkouts, you must also associate a SKU group with each of your SKUs by setting the SKU's
skuGroupId. The SKU group holds the product's compliance data.For more information, refer to:
POST/checkouts
curl --location --request POST 'https://api.digitalriver.com/checkouts' \
...
--data-raw '{
...
"items": [
{
"skuId": "d0c6c536-1a5b-4c1d-be86-92e3363a1e1f",
"quantity": 2,
"price": 10
}
]
}'
Once you submit this request, Digital River retrieves basic product data from the referenced SKU and compliance product data from the SKU's SKU group.
This option requires that you keep the product catalog in your system synchronized with your SKUs in our system.
If you decide to use this option, you should be aware that the following attributes are common to both SKUs and SKU groups:
- Harmonized system code
- Export control classification number
- Tax code
In checkouts, a SKU group's data takes precedence over a SKU's data. If a common attribute is defined in a SKU, but not the SKU group it belongs to, then we use the SKU's data in the checkout.
Instead, you retrieve this data from your system and, for each
items[] in a POST/checkouts, use it to define productDetails . The
productDetails object must also contain a skuGroupId that references the SKU group that holds the product's compliance data.Digital River then accesses basic product data from
productDetails and compliance data from the referenced SKU group.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
}
]
}'
Since you're not persisting any basic product data in Digital River's system, you're not required to keep the product catalog in your system synchronized with SKUs in our system.
Prior to deployment however you do need to work with Digital River to define your SKU groups. Once defined, Digital River is responsible for managing the data in this resource.
If your integration currently uses SKUs, and you're considering a migration to this option, you should be aware that the attributes in SKUs and
productDetails are nearly identical.The key exceptions are
taxCode, eccn, and hsCode. These attributes exist in SKUs but not in productDetails. This is because all of these attributes contain compliance data which is saved in the associated SKU group.In Digital River coordinated fulfillments,
manufacturerId is used to set up products in warehouses. That process however is handled prior to deployment. So there's no need to set manufacturerId in checkouts.Whether you send
productDetails or skuId in POST/ checkouts, the 201 Created response always contains productDetails. If you pass
productDetails, we give you back that same data. But if your integration sends
skuId, Digital River retrieves basic product data from the referenced SKU (along with that object's identifier), and uses it to populate the checkout's productDetails. If you convert the checkout to an order, productDetails is also passed through to that object.POST/checkouts
Checkout
Order
curl --location --request POST 'https://api.digitalriver.com/checkouts' \
...
--data-raw '{
...
"items": [
{
"skuId": "b0fd7334-8f7d-424e-b535-308fae972461",
"quantity": 2,
"price": 10
}
],
...
}'
{
"id": "08720898-5998-4501-aee6-f35d58de5e0a",
...
"items": [
{
"id": "9f8bf171-8612-46c3-8d26-c37a4c710beb",
"skuId": "b0fd7334-8f7d-424e-b535-308fae972461",
"productDetails": {
"id": "b0fd7334-8f7d-424e-b535-308fae972461",
"name": "Widget",
"description": "A small gadget or mechanical device",
"countryOfOrigin": "US",
"weight": 10,
"weightUnit": "g",
"partNumber": "b0fd7334-8f7d-424e-b535-308fae972461"
},
...
}
],
...
}
{
"id": "231388420336",
...
"items": [
{
"id": "158140150336",
"skuId": "b0fd7334-8f7d-424e-b535-308fae972461",
"productDetails": {
"id": "b0fd7334-8f7d-424e-b535-308fae972461",
"name": "Widget",
"description": "A small gadget or mechanical device",
"countryOfOrigin": "US",
"weight": 10,
"weightUnit": "g",
"partNumber": "b0fd7334-8f7d-424e-b535-308fae972461"
},
...
}
],
...
"checkoutId": "08720898-5998-4501-aee6-f35d58de5e0a"
}
As a result, in both checkouts and orders, as well as their associated events, such as
checkout.updated, order.complete, and subscription.reminder, you can easily access product data without having to make another call to retrieve the SKU. This feature is especially useful if you employ a third-party service that sends emails and other notifications to customers. These services can configure a webhook to listen for events such as
order.fulfilled , order.cancelled, and order.complete, and then handle these events by retrieving data from productDetails and passing it in the notification. For each element in a checkout's
items[] array, you must specify quantity. This represents the number of items selected by the customer. If you don't specify quantity, then its value defaults to 1.You must also set the line item's
price or aggregatePrice.If a checkout's products are shipping from multiple locations, you can specify each location using
items[].shipFrom.For more information, refer to the ship from address section on the Providing address information page.
When updating products or services in a
POST/checkouts/{id} request, you need to provide the line item identifier returned in the checkout.For each line item in the update checkout request, you're restricted to updating subscription information, a product's ship from address, and
metadata.If you attempt to update any other line item data, you receive a
400 Bad Request:400 Bad Request
{
"type": "bad_request",
"errors": [
{
"code": "unknown_parameter",
"parameter": "price",
"message": "'price' is an unknown parameter."
}
]
}
Last modified 11mo ago