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 allows you to define the delivery method selected by customers at checkout-time. After you set shippingChoice, you can use the returned shipping tax amount to update the checkout totals you display to customers.In
POST/checkouts and POST/checkouts/{id} requests, you can send the following data in shippingChoice: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 isn'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"
}
]
}
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, then Digital River doesn't generate an identifier that gets returned in the response.You can use a checkout's
shippingChoice.amount to pass the estimated cost of a customer's shipping method selection. This value should be inclusive of 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"
}
]
}
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 .You can designate a checkout's
shippingChoice.shippingTerms as either DAP or DDP. The default value is DDP.If you pass
shippingTerms that are DAP, then duties and import taxes are not returned in checkouts.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 keep in mind that transactions which are 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.
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 in checkouts.This allows you to present customers with the full landed cost of a transaction, thereby eliminating "surprise" charges at the time of delivery.
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.Checkout
1
{
2
...
3
"totalShipping": 5.0,
4
"items": [
5
{
6
...
7
"shipping": {
8
"amount": 2.5,
9
"taxAmount": 0.2
10
}
11
},
12
{
13
...
14
"shipping": {
15
"amount": 2.5,
16
"taxAmount": 0.2
17
}
18
}
19
],
20
"shippingChoice": {
21
"amount": 5.0,
22
"description": "standard",
23
"serviceLevel": "SG",
24
"taxAmount": 0.4
25
},
26
...
27
}
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.Last modified 2mo ago