# Landed cost

[Digital River's landed cost feature](#digital-rivers-landed-cost-feature) allows you to present customers with a transaction's [landed cost](#what-is-landed-cost) during checkout.

Once you [set up the landed cost feature](#pre-deployment-configurations), it's triggered when the [necessary preconditions](#triggering-the-landed-cost-feature) are met. After the feature is activated, Digital River's [landed cost service generates a calculation](#how-landed-costs-are-calculated), which we return to the [checkouts](#how-landed-cost-is-represented) so you can display it to customers.

## What is landed cost?

Landed cost represents the total amount your customer must pay to purchase a product from one country and have it shipped to another country. Landed cost consists of:

* The value of goods in a customer's cart
* Shipping costs
* Import duties
* Taxes

## Landed cost payment options

Customers have two options to pay a transaction's full [landed cost](#what-is-landed-cost):

{% hint style="info" %}
For more information, refer to the [shipping terms](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/shipping-choice#shipping-terms) section on the [Handling shipping choice](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/creating-checkouts/shipping-choice) page.
{% endhint %}

### **Delivered duty paid (DDP)**

Delivered Duty Paid (DDP) is a shipping agreement where the seller assumes responsibility for all costs and risks associated with transporting goods until they reach the buyer's location. This includes paying for shipping, import duties, taxes, and any other fees. Under DDP, customers pay the full landed cost during checkout, ensuring no additional charges upon delivery.

### **Delivered at place (DAP)**

In this option, customers do *not* pay the full [landed cost](#what-is-landed-cost) during [checkout](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/creating-checkouts). Instead, they pay product and shipping costs during checkouts, and then, upon an order's delivery, they're responsible for paying duties, fees, and import taxes.

## Digital River’s landed cost feature <a href="#digital-rivers-landed-cost-feature" id="digital-rivers-landed-cost-feature"></a>

Digital River offers a [landed cost](#what-is-landed-cost) feature that helps provide your customers with an estimated total cost of their order, including all applicable duties, fees, and import taxes. This estimate helps customers better understand the full cost of their purchase upfront. However, if the actual import costs assessed by the destination country's customs agency exceed the estimate, your company is responsible for covering the difference. The feature streamlines the process, as the fulfillment logistics provider coordinates with the shipper to handle customs documentation and pay the necessary duties, fees, and import taxes on behalf of the customer, billing the seller afterward.

### Setting up the landed cost feature

The [landed cost](#what-is-landed-cost) feature is available to anyone who integrates with the Digital River APIs. It's not dependent on the version you're using, how you [send product data in checkouts](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/describing-the-items#sending-product-data), or who acts as your [fulfillment coordinator](https://docs.digitalriver.com/digital-river-api/order-management/fulfillments).

Prior to using this feature, you need to complete the following steps:

**Step one**: Verify your fulfiller ships products outside of their country (not all fulfillers provide this service).

**Step two**: Determine whether your shipper is willing and able to prepay landed costs on behalf of the customer and invoice you for these costs.

**Step three**: Define your [cross-border](https://docs.digitalriver.com/digital-river-api/general-resources/glossary#cross-border) patterns (in other words, where your products ship from and where they ship to).

{% hint style="danger" %}
The ship-to countries must be supported by Digital River and cannot include embargoed nations. For more information, refer to our [Country Guide](https://www.digitalriver.com/country-guide/).
{% endhint %}

**Step four**: Provide samples of completed customs forms, such as commercial invoices, to Digital River's compliance team for approval.

**Step five**: Sign an addendum in your Digital River contract to enable the landed cost feature (unless already specified in the order form).

**Step six**: Associate a [Harmonized System (HS) code](https://www.trade.gov/harmonized-system-hs-codes) with each of your [physical products](https://docs.digitalriver.com/digital-river-api/product-management/skus#how-products-are-classified-as-physical-or-digital). To do this, you can (1) set [`hsCode`](https://docs.digitalriver.com/digital-river-api/product-management/creating-and-updating-skus#harmonized-system-code) on the [SKU ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/skus)(2) associate a [SKU group](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/sku-groups) with the [SKU ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/skus)or (3) reference a [SKU group](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/sku-groups) in [`productDetails`](https://docs.digitalriver.com/digital-river-api/product-management/using-product-details).

{% hint style="info" %}
For more information, refer to:

* [Sending product data in checkouts](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/describing-the-items#sending-product-data) on the [Describing line items](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/describing-the-items#sending-product-data) page
* The [Grouping SKUs](https://docs.digitalriver.com/digital-river-api/product-management/setting-up-sku-groups) page
  {% endhint %}

In this step, we recommend selecting option two or three. These options allow you to:

* Simplify the process of assigning and managing your products' HS codes.
* Use country-specific HS tariff codes tailored to each transaction, which improves the accuracy of the [landed cost calculation](#how-landed-costs-are-calculated).

## Triggering the landed cost feature <a href="#triggering-the-landed-cost-feature" id="triggering-the-landed-cost-feature"></a>

Once you perform the [pre-deployment configurations](#pre-deployment-configurations), the landed cost is calculated during [checkout](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/creating-checkouts). To successfully [receive a landed cost calculation](#how-landed-cost-is-represented) at run-time, the following preconditions must exist:

* The [checkout](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/checkouts) contains [physical products](https://docs.digitalriver.com/digital-river-api/product-management/skus#how-products-are-classified-as-physical-or-digital)
* The checkout's [physical products](https://docs.digitalriver.com/digital-river-api/product-management/skus#how-products-are-classified-as-physical-or-digital) are associated with a [Harmonized System code](https://www.trade.gov/harmonized-system-hs-codes).
* The checkout's [`taxInclusive`](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/creating-checkouts/configuring-taxes) flag must be `false`.
* The checkout contains a [`shippingChoice.amount`](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/shipping-choice#shipping-amount) and its value is inclusive of any [applied discounts](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/creating-checkouts/applying-a-discount)
* The checkout's [`shippingChoice.shippingTerms`](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/shipping-choice#shipping-terms) must be [`DDP`](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/shipping-choice#delivered-duty-paid-ddp).
* The checkout's [`shipTo.address.country`](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/providing-address-information#ship-to-address) is on the approved list
* The checkout's [`shipFrom.address.country`](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/providing-address-information#ship-from-address) and `shipTo.address.country` are specified, and the values are different. Since shipments between EU countries are exempt from duties, a checkout's ship from country and ship to country can't *both* be EU nations.

## How landed cost is calculated <a href="#how-landed-costs-are-calculated" id="how-landed-costs-are-calculated"></a>

To calculate [landed cost](#what-is-landed-cost) in [applicable checkouts](#triggering-the-landed-cost-feature), Digital River sends an API request to a third-party service. Based on the data provided in the request, this service calculates taxes, duties, fees, and import taxes.

We use the values returned by this service to build a [checkout's](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/checkouts) `totalAmount`. When you [convert a 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), this is what the customer is ultimately charged

#### Calculation failures

If a customer attempts to ship a product to an embargoed country, then the checkout fails:

{% tabs %}
{% tab title="409 Conflict" %}

```
{
    "type": "conflict",
    "errors": [
        {
            "code": "country_unsupported",
            "parameter": "country",
            "message": "Country 'KP' is not supported."
        }
    ]
}
```

{% endtab %}
{% endtabs %}

Additionally, on rare occasions, the third-party landed cost service may be unavailable or unable to generate a calculation. In these cases, no [landed cost values](#how-landed-cost-is-represented) are returned in the [checkout](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/checkouts).

## How landed cost is represented in checkouts <a href="#how-landed-cost-is-represented" id="how-landed-cost-is-represented"></a>

{% hint style="warning" %}
In versions `2020-09-30` and earlier, landed cost is represented by `totalDuty` and `importerOfRecordTax`.
{% endhint %}

In [checkouts that trigger the landed cost feature](#triggering-the-landed-cost-feature), we provide you with an itemized breakdown of taxes, duties, fees, and import taxes. Since your customers ultimately pay these costs, you should display them during [checkout](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/creating-checkouts).

Numerous attributes at [checkout](#order-level-attributes) and the [line item levels](#item-level-attributes) contain the [full landed cost](#what-is-landed-cost). You can use this data to determine import duties and distinguish between taxes Digital River remits and those the shipper remits.

### Checkout level attributes <a href="#order-level-attributes" id="order-level-attributes"></a>

A [checkout's ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/checkouts)`totalAmount` is ultimately what the customer is charged when you [convert a 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).

The `totalAmount` however may not represent the [full landed cost](#what-is-landed-cost) of a transaction. That depends on how you configure a checkout's [`shippingChoice.shippingTerms`](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/shipping-choice#shipping-terms).

If a [checkout triggers the landed cost feature](#triggering-the-landed-cost-feature-1), then `importerOfRecordTax` returns `true`. In these cases, `totalImporterTax` indicates the tax amount that the importer of record remits to the government and `totalDuty` are duties levied on the products by the importing country.

{% hint style="warning" %}
Sometimes products in a [cross-border](https://docs.digitalriver.com/digital-river-api/general-resources/glossary#cross-border) transaction don't incur any duties. As a result, in [checkouts that trigger the landed cost feature](#triggering-the-landed-cost-feature), `totalDuty` is not always greater than zero.
{% endhint %}

A [checkout's ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/checkouts)`totalTax` represents taxes that Digital River remits to the government. Its value does not include `totalImporterTax`. Those taxes are remitted to the government by your shipper.

This means that a [checkout's ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/checkouts)`subtotal` includes `totalImporterTax` but doesn't include `totalTax`.

### Line item level attributes <a href="#item-level-attributes" id="item-level-attributes"></a>

In [checkouts that trigger the landed cost feature](#triggering-the-landed-cost-feature), each element in [`items[]`](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/creating-checkouts/describing-the-items) contains three landed cost-related attributes:

#### Importer tax amount

The `importerTax.amount` indicates the amount of taxes that the importer of record pays on all the products in this line item.

#### Duties amount

The `duties.amount` indicates the amount of duty levied by an importing country on all the products in this line item.

#### Tariff code

A `tariffCode` represents a product's country-specific [Harmonized System code](https://www.trade.gov/harmonized-system-hs-codes). This value is only returned if you're using [SKU groups](https://docs.digitalriver.com/digital-river-api/product-management/setting-up-sku-groups).

Landed cost calculations are based on this `tariffCode`Consequently, it's often useful for troubleshooting purposes. For example, if [cross-border](https://docs.digitalriver.com/digital-river-api/general-resources/glossary#cross-border) duties presented to the customer during checkouts are later determined inaccurate, you can verify whether the correct code was applied to the product.

## European Union cross-border threshold

In the European Union, a de minimis threshold, currently set at 150 EUR, determines whether (1) duties are collected on imported goods and (2) the buyer or seller is responsible for remittances.

In [checkouts ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/checkouts)where goods are being shipped [cross-border](https://docs.digitalriver.com/digital-river-api/general-resources/glossary#cross-border) into the EU, Digital River’s tax service determines whether the aggregated, intrinsic `price` of its [physical](https://docs.digitalriver.com/digital-river-api/product-management/skus#how-products-are-classified-as-physical-or-digital) `items[]`, excluding `shippingChoice.amount`, is (A) [less than or equal to](#less-than-or-equal-to-the-threshold) or (B) [greater than](#greater-than-the-threshold) this threshold.

### Less than or equal to the threshold

If it’s less than or equal to the 150 EUR threshold, then:

* `totalDuty` is `0`, because duties aren’t collected on what the EU considers to be low-value imports.
* `Digital River Ireland Ltd.`, the [`sellingEntity.name`](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/creating-checkouts/selling-entities) assigned to the transaction, is responsible for the remittance of value-added tax.
* `totalTax` contains the amount that this selling entity must remit, which is added to the `totalAmount` that the buyer pays.
* Each `items[]` is assigned a `sellerTaxIdentifier`, which represents Digital River’s [Import One-Stop Shop](https://en.wikipedia.org/wiki/Import_One-Stop_Shop) registration number. After the [checkout ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/checkouts)is converted to an [order](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/orders), this value should be added to the [commercial invoice](https://en.wikipedia.org/wiki/Commercial_invoice) to ensure that buyers aren’t assessed taxes again by customs (i.e., double-charged).

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

```
curl --location 'https://api.digitalriver.com/checkouts' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <Your secret API key>' \
....
--data-raw '{
    "currency": "EUR",
    ...
    "taxInclusive": false,
    "shipTo": {
        ...
        "address": {
            "line1": "Deinsesteenweg 108B",
            "city": "Drongen",
            "postalCode": "9031",
            "state": "Oost-Vlaanderen",
            "country": "BE"
        }
    },
    "shipFrom": {
        "address": {
            "line1": "5215 4th Ave S",
            "city": "Minneapolis",
            "postalCode": "55104",
            "state": "MN",
            "country": "US"
        }
    },
    "items": [
        {
            "skuId": "sku_7d8c3133-342a-4c8e-90b2-ac541fcccd13",
            "price": 75,
            "quantity": 1
        },
        {
            "skuId": "sku_00af8f73-4aa6-4b08-b904-78b42869da73",
            "price": 75,
            "quantity": 1
        }
    ]
}'
```

{% endtab %}

{% tab title="201 Created" %}

```json
{
    "id": "b83bb92f-f5b5-40d0-9d6d-59a9968d5d83",
    ...
    "currency": "EUR",
    ...
    "shipTo": {
        "address": {
            "line1": "Deinsesteenweg 108B",
            "city": "Drongen",
            "postalCode": "9031",
            "state": "Oost-Vlaanderen",
            "country": "BE"
        },
        ...
    },
    "shipFrom": {
        "address": {
            "line1": "5215 4th Ave S",
            "city": "Minneapolis",
            "postalCode": "55104",
            "state": "MN",
            "country": "US"
        }
    },
    "totalAmount": 181.5,
    "subtotal": 150.0,
    ...
    "totalTax": 31.5,
    "totalImporterTax": 0.0,
    "totalDuty": 0.0,
    ...
    "items": [
        {
            "id": "21a44c0f-a50b-43bf-91a6-ebb8d63fbe03",
            "skuId": "sku_7d8c3133-342a-4c8e-90b2-ac541fcccd13",
            ...
            "amount": 75.0,
            "quantity": 1,
            "tax": {
                "rate": 0.21,
                "amount": 15.75
            },
            "importerTax": {},
            "duties": {},
            ...
            "sellerTaxIdentifier": "IM3720000202",
            ...
        },
        {
            "id": "0d99a3a7-2601-4980-8fa9-af5cf1d9f3e0",
            "skuId": "sku_00af8f73-4aa6-4b08-b904-78b42869da73",
            ...
            "amount": 75.0,
            "quantity": 1,
            "tax": {
                "rate": 0.21,
                "amount": 15.75
            },
            "importerTax": {},
            "duties": {},
            ...
            "sellerTaxIdentifier": "IM3720000202",
            ...
        }
    ],
    ...
    "sellingEntity": {
        "id": "DR_IRELAND-ENTITY",
        "name": "Digital River Ireland Ltd."
    },
    ...
}
```

{% endtab %}
{% endtabs %}

### Greater than the threshold

If the aggregated value of the imported goods is greater than the 150 EUR threshold, then:

* Buyers are responsible for the remittance of tax and duty.
* Assuming your account has the [landed cost feature](#digital-rivers-landed-cost-feature) enabled and you don’t set the [checkout’s ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/checkouts)`shippingChoice.shippingTerms` to `DAP`, the amount that the buyer must remit is assigned to `totalImporterTax` and `totalDuty`.
* `totalImporterTax` and `totalDuty` are added to `totalAmount`, which means `Digital River Ireland Ltd.`, the [`sellingEntity.name`](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/creating-checkouts/selling-entities) assigned to the transaction is collecting these costs in advance, on behalf of the buyer, and then remitting them later.

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

```
curl --location 'https://api.digitalriver.com/checkouts' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <Your secret API key>' \
....
--data-raw '{
    "currency": "EUR",
    ...
    "taxInclusive": false,
    "shipTo": {
        ...
        "address": {
            "line1": "Deinsesteenweg 108B",
            "city": "Drongen",
            "postalCode": "9031",
            "state": "Oost-Vlaanderen",
            "country": "BE"
        }
    },
    "shipFrom": {
        "address": {
            "line1": "5215 4th Ave S",
            "city": "Minneapolis",
            "postalCode": "55104",
            "state": "MN",
            "country": "US"
        }
    },
    "items": [
        {
            "skuId": "sku_7d8c3133-342a-4c8e-90b2-ac541fcccd13",
            "price": 75,
            "quantity": 1
        },
        {
            "skuId": "sku_00af8f73-4aa6-4b08-b904-78b42869da73",
            "price": 76,
            "quantity": 1
        }
    ]
}'
```

{% endtab %}

{% tab title="201 Created" %}

```json
{
    "id": "8365ecbc-0e28-4ba4-bcc7-75ae8c6a93f4",
    ...
    "currency": "EUR",
    ...
    "shipTo": {
        "address": {
            "line1": "Deinsesteenweg 108B",
            "city": "Drongen",
            "postalCode": "9031",
            "state": "Oost-Vlaanderen",
            "country": "BE"
        },
        ...
    },
    "shipFrom": {
        "address": {
            "line1": "5215 4th Ave S",
            "city": "Minneapolis",
            "postalCode": "55104",
            "state": "MN",
            "country": "US"
        }
    },
    "totalAmount": 213.77,
    "subtotal": 213.77,
    ...
    "totalTax": 0.0,
    "totalImporterTax": 37.1,
    "importerOfRecordTax": true,
    "totalDuty": 25.67,
    ...
    "items": [
        {
            "id": "b8408be2-9abf-42dd-b4ff-1e36e1d776a4",
            "skuId": "sku_7d8c3133-342a-4c8e-90b2-ac541fcccd13",
            ...
            "amount": 75.0,
            "quantity": 1,
            "tax": {
                "rate": 0.38,
                "amount": 0.0
            },
            "importerTax": {
                "amount": 18.43
            },
            "duties": {
                "amount": 12.75
            },
            ...
        },
        {
            "id": "8b6c522a-2751-44bb-af07-a68147746b72",
            "skuId": "sku_00af8f73-4aa6-4b08-b904-78b42869da73",
            ...
            "amount": 76.0,
            "quantity": 1,
            "tax": {
                "rate": 0.38,
                "amount": 0.0
            },
            "importerTax": {
                "amount": 18.67
            },
            "duties": {
                "amount": 12.92
            },
            ...
        }
    ],
    ...
    "sellingEntity": {
        "id": "DR_IRELAND-ENTITY",
        "name": "Digital River Ireland Ltd."
    },
    ...
}
```

{% endtab %}
{% endtabs %}