Handling shipping choice

Learn how to set and use a customer's shipping choice in checkouts

Checkouts with physical products must contain a shippingChoice. This data structure lets you define the delivery method customers select at checkout time. After you set the shippingChoice, you can use the returned shipping tax amount to update the checkout totals you display to customers.

Setting shipping choice

In POST /checkouts and POST /checkouts/{id} requests, you can send the following data in shippingChoice:

• A unique shipping identifier

• A shipping amount

• A shipping method's description and service level

• The duty payment terms of the selected shipping method

POST/checkouts/{id}

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"
    }
}'

You're not required to send shippingChoice in either create or update checkout requests. But if any of a checkout's items[] contain a physical product and shippingChoice aren't set when you convert the checkout to an order, you receive a 400 Bad Request.

400 Bad Request

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

Unique shipping identifier

A checkout's 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 shippingChoice.amount to pass the estimated cost of a customer's shipping method selection. This value should include handling and fees.

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 page.

When creating or updating checkouts that contain physical products, if you send shippingChoice but fail to send shippingChoice.amount, then a 400 Bad Request is returned.

400 Bad Request

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

Shipping description and service level

In a checkout's shippingChoice, you can use serviceLevel and description to describe the shipping method selected by the customer.

In 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 shippingChoice.shippingTerms as either DAP or 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 on the Landed cost 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 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 exist to activate the landed cost feature, then estimated duties and import taxes are returned at checkouts.

This allows you to present customers with the full 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 page:

• Triggering the landed cost feature

• How landed cost is represented in checkouts

• The guaranteed landed cost feature

Using shipping costs

Once you collect a customer's shipping method choice and add shippingChoice.amount to the checkout, Digital River makes a tax computation and returns that value in shippingChoice.taxAmount. For each of a checkout's items[], Digital River also returns a shipping object that contains an amount and a taxAmount.

All of a checkout's taxes, including shippingChoice.taxAmount, are aggregated into totalTax.

Checkout

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

Each time you update the checkout, 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.