# Handling shipping choice

[Checkouts](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/checkouts) with [physical products](https://docs.digitalriver.com/digital-river-api/product-management/skus#how-products-are-classified-as-physical-or-digital) must contain a `shippingChoice`. This data structure lets you define the delivery method customers select at checkout time. After you [set the `shippingChoice`](#setting-shipping-choice), you can [use the returned shipping tax amount](#using-shipping-choice) to update the checkout totals you display to customers.

## Setting shipping choice

In [`POST /checkouts`](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/checkouts#checkouts-1) and [`POST /checkouts/{id}`](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/checkouts#checkouts-id-1) requests, you can send the following data in `shippingChoice`:

* [A unique shipping identifier](#unique-shipping-identifier)
* [A shipping amount](#shipping-amount)
* [A shipping method's description and service level](#shipping-description-and-service-level)
* [The duty payment terms of the selected shipping method](#shipping-terms)

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

```javascript
curl --location --request POST 'https://api.digitalriver.com/checkouts/04ea45eb-2bb8-4ea9-a772-37e5fbd5d1fe' \
...
--data-raw '{
    "shipFrom": {
        "address": {
            "country": "US"
        }
    },
    "shippingChoice": {
        "id": "123",
        "amount": 5,
        "description": "standard",
        "serviceLevel": "SG",
        "shippingTerms": "DDP"
    }
}'
```

{% endcode %}

You're not required to send `shippingChoice` in either [create](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/checkouts#checkouts-1) or [update checkout requests](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/checkouts#checkouts-id-1). But if any of a checkout's [`items[]`](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/creating-checkouts/describing-the-items) contain a [physical product](https://docs.digitalriver.com/digital-river-api/product-management/skus#how-products-are-classified-as-physical-or-digital) and `shippingChoice` aren't set when 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), you receive a `400 Bad Request`.

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

```javascript
{
    "type": "bad_request",
    "errors": [
        {
            "code": "invalid_shipping_choice",
            "parameter": "shippingChoice",
            "message": "Could not get Shipping Options for order"
        }
    ]
}
```

{% endtab %}
{% endtabs %}

### Unique shipping identifier

A [checkout's](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/checkouts) `shippingChoice.id` is typically a pass-through value from your fulfillment or logistics provider. You're not required to provide this identifier.

If you don't send `shippingChoice.id` in the request, Digital River doesn't generate an identifier that gets returned in the response.

### Shipping amount

You can use a [checkout's](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/checkouts) `shippingChoice.amount` to pass the estimated cost of a customer's shipping method selection. This value should include handling and fees.

{% hint style="info" %}
Whether Digital River adds taxes to or extracts taxes from `shippingChoice.amount` is dependent on how you set the checkout's `taxInclusive` flag. For details, refer to the [Configuring taxes](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/creating-checkouts/configuring-taxes) page.
{% endhint %}

When [creating ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/checkouts#checkouts-1)or [updating checkouts](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/checkouts#checkouts-id-1) that contain [physical products](https://docs.digitalriver.com/digital-river-api/product-management/skus#how-products-are-classified-as-physical-or-digital), if you send `shippingChoice` but fail to send `shippingChoice.amount`, then a `400 Bad Request` is returned.

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

```javascript
{
    "type": "bad_request",
    "errors": [
        {
            "code": "internal_error",
            "message": "Client must provide shipping Cost"
        }
    ]
}
```

{% endtab %}
{% endtabs %}

### Shipping description and service level

In a [checkout's](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/checkouts) `shippingChoice`, you can use `serviceLevel` and `description` to describe the shipping method selected by the customer.

In [third-party coordinated fulfillments](https://docs.digitalriver.com/digital-river-api/order-management/fulfillments#third-party-coordinated-fulfillments), you're not required to pass either of these values, but they can be useful for reporting purposes. Additionally, since it helps Digital River better detect fraud, we highly recommend that you send `serviceLevel` .

### Shipping terms

You can designate a [checkout's ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/checkouts)`shippingChoice.shippingTerms` as either [`DAP`](#delivered-at-place-dap) or [`DDP`](#delivered-duty-paid-ddp). The default value is `DDP`.

#### Delivered at place (DAP)

If you pass `shippingTerms` that are `DAP`, then duties and import taxes are not returned in checkouts.

For more information, refer to [triggering the landed cost feature](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/landed-costs#triggering-the-landed-cost-feature) on the [Landed cost](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/creating-checkouts/landed-costs) page.

This means that when the products are delivered, customers may be presented with a bill for any outstanding importation costs. Customers typically must pay these costs before the carrier transfers ownership.

In [checkouts ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/checkouts)with `DAP` duty payment terms, you should inform customers that import charges are collected upon delivery.

You should also remember that transactions not paid in full at the point of sale have higher rejection and return rates. This is because customers may be unaware of the outstanding balance or the outstanding balance is higher than they anticipated and, in response, they either refuse the delivery altogether or accept the products and then request a return.

#### Delivered duty paid (DDP)

If you pass `shippingTerms` that are `DDP`, and the [necessary preconditions](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/landed-costs#triggering-the-landed-cost-feature) exist to activate the [landed cost feature](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/landed-costs#digital-rivers-landed-cost-feature), then estimated duties and import taxes are returned at checkouts.

This allows you to present customers with the [full landed cost](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/landed-costs#what-is-landed-cost) of a transaction, thereby eliminating "surprise" charges at the time of delivery.

For more information, refer to the following sections on the [Landed cost](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/creating-checkouts/landed-costs) page:

* [Triggering the landed cost feature](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/landed-costs#triggering-the-landed-cost-feature)
* [How landed cost is represented in checkouts](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/landed-costs#how-landed-cost-is-represented)
* [The guaranteed landed cost feature](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/landed-costs#guaranteed-landed-cost-feature)

## Using shipping costs <a href="#using-shipping-choice" id="using-shipping-choice"></a>

Once you collect a customer's shipping method choice and add `shippingChoice.amount` to the [checkout](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/checkouts), Digital River makes a tax computation and returns that value in `shippingChoice.taxAmount`. For each of a [checkout's](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/checkouts) `items[]`, Digital River also returns a `shipping` object that contains an `amount` and a `taxAmount`.

{% hint style="info" %}
All of a [checkout's](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/checkouts) taxes, including `shippingChoice.taxAmount`, are aggregated into `totalTax`.
{% endhint %}

{% code title="Checkout" lineNumbers="true" %}

```json
{
    ...
    "totalShipping": 5.0,
    "items": [
        {
            ...
            "shipping": {
                "amount": 2.5,
                "taxAmount": 0.2
            }
        },
        {
            ...
            "shipping": {
                "amount": 2.5,
                "taxAmount": 0.2
            }
        }
    ],
    "shippingChoice": {
        "amount": 5.0,
        "description": "standard",
        "serviceLevel": "SG",
        "taxAmount": 0.4
    },
    ...
}
```

{% endcode %}

Each time you update the [checkout](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/checkouts), we recommend that you retrieve `shippingChoice.amount` or `totalShipping` and display this value to customers in the transaction details section of your UI. To provide customers more granularity on shipping costs, you might also decide to display each line item's `shipping.amount` and `shipping.taxAmount`.