# Describing line items

You use a [checkout's](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/checkouts) `items[]` array to pass data on [products and/or services](https://docs.digitalriver.com/digital-river-api/product-management/skus) in a customer's cart. The elements of `items[]` allow you to:

* [Send product data](#sending-product-data)
* [Set a product's price and quantity](#setting-price-and-quantity)
* [Provide a product's subscription details](#providing-subscription-information)
* [Discount a product](#discounting-a-product)
* [Identify a product's ship from location](#setting-a-ship-from-location)

After you [create a checkout](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/checkouts#checkouts-1), we return an [`items[].id`](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/creating-checkouts/..#item-information) that uniquely identifies each of a checkout's line items. This identifier is needed to [modify the line item](#updating-items) in an [update checkout request](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/checkouts#checkouts-id-1).

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](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/creating-checkouts/..#sending-the-create-checkout-request) section on the [Building checkouts](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/creating-checkouts) page.

## Sending product data in checkouts <a href="#sending-product-data" id="sending-product-data"></a>

In a [create checkout request](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/checkouts#checkouts-1), you must provide Digital River with [basic and compliance data](https://docs.digitalriver.com/digital-river-api/product-management/skus#basic-versus-compliance-product-data) on the products in a customer's cart. You have three options for passing this data. You can:

* [Send basic and compliance data in SKUs](#send-basic-and-compliance-data-in-skus)
* [Send basic data in SKUs and compliance data in SKU groups](#send-basic-data-in-skus-and-compliance-data-in-sku-groups)
* [Send basic data in `productDetails` and compliance data in SKU groups](#send-basic-data-in-product-details-and-compliance-data-in-sku-groups)

Whichever option you select, [Digital River always returns `productDetails`](#how-digital-river-returns-product-data).

{% hint style="info" %}
Digital River also assigns each of a checkout's `items[]` a unique `id`.
{% endhint %}

### Send basic and compliance data in SKUs

In this option, before [checking out customers](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/creating-checkouts), you must define and create a [SKU ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/skus)for each of the product's in your catalog. Each SKU needs to contain both [basic and compliance data](https://docs.digitalriver.com/digital-river-api/product-management/skus#basic-versus-compliance-product-data) on that product.

For more information, refer to the [Product basics](https://docs.digitalriver.com/digital-river-api/product-management/skus) and [Managing SKUs](https://docs.digitalriver.com/digital-river-api/product-management/creating-and-updating-skus) pages.

In this option, each `items[]` in a [`POST /checkouts`](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/checkouts#checkouts-1) must contain a `skuId`.

{% code title="POST/checkouts" %}

```javascript
curl --location --request POST 'https://api.digitalriver.com/checkouts' \
...
--data-raw '{
    ...
    "items": [
        {
            "skuId": "d0c6c536-1a5b-4c1d-be86-92e3363a1e1f",
            "quantity": 2,
            "price": 10
        }
    ]
}'
```

{% endcode %}

Once you submit this request, Digital River retrieves all the product data 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.

### Send basic data in SKUs and compliance data in SKU groups

In this option, before [checking out customers](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/creating-checkouts), you must define and create a [SKU ](https://app.gitbook.com/s/ScJM6Hp95yBCPfU1nBSB/sku)for each product in your catalog. The SKUs only need to contain [basic product data](https://docs.digitalriver.com/digital-river-api/product-management/skus#basic-versus-compliance-product-data).

Before [creating checkouts](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/checkouts#checkouts-1), you must also [associate a SKU group with each of your SKUs](https://docs.digitalriver.com/digital-river-api/product-management/setting-up-sku-groups#using-sku-groups-in-transactions) by setting the [SKU's](https://www.digitalriver.com/docs/digital-river-api-reference/#tag/SKUs) `skuGroupId`. The [SKU group](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/sku-groups) holds the [product's compliance data](https://docs.digitalriver.com/digital-river-api/product-management/skus#basic-versus-compliance-product-data).

For more information, refer to:

* [Product basics](https://docs.digitalriver.com/digital-river-api/product-management/skus)
* [Managing SKUs](https://docs.digitalriver.com/digital-river-api/product-management/creating-and-updating-skus)
* [Grouping SKUs](https://docs.digitalriver.com/digital-river-api/product-management/setting-up-sku-groups)

In this option, each `items[]` in a [`POST /checkouts`](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/checkouts#checkouts-1) must contain a `skuId`.

{% code title="POST/checkouts" %}

```javascript
curl --location --request POST 'https://api.digitalriver.com/checkouts' \
...
--data-raw '{
    ...
    "items": [
        {
            "skuId": "d0c6c536-1a5b-4c1d-be86-92e3363a1e1f",
            "quantity": 2,
            "price": 10
        }
    ]
}'
```

{% endcode %}

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.

#### Common attributes and data priority in SKUs and SKU groups

If you decide to use this option, you should be aware that the following attributes are common to both [SKUs ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/skus)and [SKU groups](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/sku-groups):

* Harmonized system code
* Export control classification number
* Tax code

In [checkouts](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/checkouts), a SKU group's data precedes 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.

For more details, refer to [Migrating to SKU groups](https://docs.digitalriver.com/digital-river-api/product-management/setting-up-sku-groups#migrating-to-sku-groups) on the [Grouping SKUs](https://docs.digitalriver.com/digital-river-api/product-management/setting-up-sku-groups) page.

### Send basic data in product details and compliance data in SKU groups

In this option, you don't store [basic product data](https://docs.digitalriver.com/digital-river-api/product-management/skus#basic-versus-compliance-product-data) in Digital River's system.

Instead, you retrieve this data from your system and, for each `items[]` in a [`POST /checkouts`](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/checkouts#checkouts-1), use it to define [`productDetails`](https://docs.digitalriver.com/digital-river-api/product-management/using-product-details) .

{% hint style="success" %}
The [`id`](https://docs.digitalriver.com/digital-river-api/product-management/using-product-details#unique-identifier) in `productDetails` should be the same as the identifier of the product in your system.
{% endhint %}

The [`productDetails`](https://docs.digitalriver.com/digital-river-api/product-management/using-product-details) object must also contain a `skuGroupId` that references the [SKU group](https://docs.digitalriver.com/digital-river-api/product-management/setting-up-sku-groups) that holds the [product's compliance data](https://docs.digitalriver.com/digital-river-api/product-management/skus#basic-versus-compliance-product-data).

Digital River then accesses basic product data from `productDetails` and compliance data from the referenced SKU group.

{% 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 %}

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 ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/skus)in our system.

However, prior to deployment, you need to work with Digital River to [define your SKU groups](https://docs.digitalriver.com/digital-river-api/product-management/setting-up-sku-groups#defining-and-managing-sku-groups). Once defined, Digital River is responsible for managing the data in this resource.

For more information, refer to the [Grouping SKUs](https://docs.digitalriver.com/digital-river-api/product-management/setting-up-sku-groups) page.

#### Common attributes in `productDetails` and SKUs

If your integration currently uses [SKUs](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/skus), and you're considering a migration to this option, you should be aware that the attributes in SKUs and [`productDetails`](https://docs.digitalriver.com/digital-river-api/product-management/using-product-details) 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](https://docs.digitalriver.com/digital-river-api/product-management/skus#basic-versus-compliance-product-data) saved in the associated [SKU group](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/product-management/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/order-management/fulfillments#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.
{% endhint %}

### How Digital River returns product data

Whether you send `productDetails` or `skuId` in [`POST /checkouts`](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/checkouts#checkouts-1), 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](https://docs.digitalriver.com/digital-river-api/product-management/skus#basic-versus-compliance-product-data) from the referenced [SKU](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/skus) (along with that object's identifier) and uses it to populate the [checkout's ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/checkouts)`productDetails`. If you [convert the checkout to an order](https://docs.digitalriver.com/digital-river-api/order-management/creating-and-updating-an-order#creating-an-order-with-the-checkout-identifier), `productDetails` is also passed through to that object.

{% tabs %}
{% tab title="POST/checkouts" %}

```javascript
curl --location --request POST 'https://api.digitalriver.com/checkouts' \
...
--data-raw '{
    ...
    "items": [
        {
            "skuId": "b0fd7334-8f7d-424e-b535-308fae972461",
            "quantity": 2,
            "price": 10
        }
    ],
    ...
}'
```

{% endtab %}

{% tab title="Checkout" %}

```javascript
{
    "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"
            },
            ...
        }
    ],
    ...
}
```

{% endtab %}

{% tab title="Order" %}

```javascript
{
    "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"
}
```

{% endtab %}
{% endtabs %}

As a result, in both [checkouts ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/checkouts)and [orders](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/orders), as well as their associated [events](https://docs.digitalriver.com/digital-river-api/order-management/events-and-webhooks-1/events-1), such as `checkout.updated`, [`order.complete`](https://docs.digitalriver.com/digital-river-api/order-management/informing-digital-river-of-a-fulfillment#handling-the-order-complete-event), and [`subscription.reminder`](https://docs.digitalriver.com/digital-river-api/integration-options/subscriptions/digital-river-coordinated-subscriptions#sending-a-reminder), you can easily access product data without making another [call to retrieve the SKU](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/skus#skus-id).

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](https://docs.digitalriver.com/digital-river-api/order-management/events-and-webhooks-1/webhooks/creating-a-webhook#step-3.-create-webhooks) to listen for [events](https://docs.digitalriver.com/digital-river-api/order-management/events-and-webhooks-1/events-1) such as [`order.fulfilled`](https://docs.digitalriver.com/digital-river-api/order-management/informing-digital-river-of-a-fulfillment#the-order-fulfilled-event) , [`order.cancelled`](https://docs.digitalriver.com/digital-river-api/order-management/creating-and-updating-an-order#the-order-cancelled-event), and [`order.complete`](https://docs.digitalriver.com/digital-river-api/order-management/informing-digital-river-of-a-fulfillment#handling-the-order-complete-event), and then handle these events by retrieving data from `productDetails` and passing it in the notification.

## Setting price and quantity

For each element in a [checkout's ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/checkouts)`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`.

For more information on how to do this, refer to the [Setting the price of an item](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/creating-checkouts/describing-the-items/price-of-an-item) page.

## Providing subscription information

In [checkouts](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/checkouts), you set `subscriptionInfo` at the line-item level. For more information, refer to:

* [Subscription information](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/subscriptions/subscription-information-1)
* [Digital River's subscription service](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/subscriptions/digital-river-coordinated-subscriptions)
* [Third-party subscription services](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/subscriptions/third-party-coordinated-subscriptions)

## Discounting a product

For each element in a [checkout's ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/checkouts)`items[]` array, you can set a product-level `discount`.

For more information, refer to the [product discounts](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/applying-a-discount#product-discounts) section on the [Applying a discount](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/creating-checkouts/applying-a-discount) page.

## Setting a ship from location

If a [checkout's](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/checkouts) products are shipping from multiple locations, you can specify each location using `items[].shipFrom`.

For more information, refer to the [ship from address](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/providing-address-information#ship-from-address) section on the [Providing address information](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/creating-checkouts/providing-address-information) page.

## Updating items

When updating products or services in a [`POST /checkouts/{id}`](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/checkouts#checkouts-id-1) request, you must provide the [line item identifier](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/creating-checkouts/..#item-information) returned in the [checkout](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/checkouts).

For each line item in the update checkout request, you're restricted to updating [subscription information](https://docs.digitalriver.com/digital-river-api/integration-options/subscriptions/subscription-information-1#setting-subscription-information), a product's [ship from address](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/providing-address-information#ship-from-address), and `metadata`.

If you attempt to update any other line item data, you receive a `400 Bad Request`:

{% tabs %}
{% tab title="400 Bad Request" %}

```javascript
{
    "type": "bad_request",
    "errors": [
        {
            "code": "unknown_parameter",
            "parameter": "price",
            "message": "'price' is an unknown parameter."
        }
    ]
}
```

{% endtab %}
{% endtabs %}