Links

Using shipping quotes

Learn how to provide your customers shipping options and process their selection
This page explains how to use the Shipping Quotes API in versions 2020-12-17, 2020-02-23, and 2021-03-23 as part of a Digital River coordinated fulfillment. In versions 2021-12-13 and higher, the /shipping-quotes endpoint has been repurposed for use in our Global logistics solution.
In Digital River coordinated fulfillments, you call the Shipping Quotes API during the checkout process to provide customers with shipping options.
In the response, we give you back an array of shipping quotes, each describing the quote's service level, shipping costs, signature requirements, estimated delivery times, inventory availability and ship from addresses.
These shipping quotes can then be displayed to the customer. Once the customer makes a selection, you can use a shipping quote's data to continue processing the checkout.
In third party coordinated fulfillments, the checkout's shipping information needs to be obtained from your logistics partner.

Requesting shipping quotes

In a POST/shipping-quotes request, you need to provide the currency used to pay for the shipping, the items to ship, as well as their destination and delivery type.
This call to the Shipping Quotes API typically occurs late in the checkout process, after customers have finalized their carts and you've collected their shipping address. So, much of the data you need to define the request can be retrieved from the checkout.
Checkout
POST/shipping-quotes
currency
currency
items[].skuId
items[].inventoryItemId
items[].amount
items[].price
items[].quantity
items[].quantity
shipTo.postalCode
shipTo.postalCode
shipTo.state
shipTo.state
shipTo.country
shipTo.country
POST/shipping-quotes
curl --location --request POST 'http://dispatch-test.digitalriver.com/shipping-quotes' \
--header 'Authorization: Bearer <API_key>' \
--header 'Content-Type: application/json' \
...
--data-raw '{
"currency": "USD",
"shipTo": {
"postalCode": "11111",
"state": "BU",
"country": "JP",
"type": "standard"
},
"items": [
{
"inventoryItemId": "78fd6209-91e7-4347-aadc-af73edb8b18b",
"price": 9.99,
"quantity": 1
}
]
}'

Items to ship

You must provide an array of products in your shipping quotes request. Each element of the items array represents a specific inventory item. For each inventory item, you're required to specify its unique identifier, price, and quantity.
In Digital River coordinated fulfillments, your SKUs and inventory items form synchronous pairs. So the checkout's items[].skuId can be used to set the shipping quotes'items[].inventoryItemId.

Shipping destination and type

In order for Digital River to return accurate shipping quotes, you need to specify the shipTo block's state, country, and postalCode.
You can also use shipTo to set type. This parameter represents the final step in the fulfillment process, actually delivering the products to a customer. The type options are standard(default), access_point, or cash_on_delivery. The delivery type affects the returned service levels.

Standard deliveries

A standard delivery type is the most common and consists of the shipping carrier bringing the goods directly to the customer's home or place of business.

Access point deliveries

With access_point deliveries, customers pick up their products at stand-alone lockers located in high traffic areas like shopping centers and train stations. Alternatively, the goods can be delivered to so called "parcel shops", such as convenience and grocery stores, where the customer picks them up.

Cash on delivery

When you specify cash_on_delivery, end customers must pay the shipping carrier for the goods at the time of delivery. This cash on delivery (COD) payment method is particularly popular in Japan, China, Mexico, Indonesia, Germany, Spain, Turkey, UAE, Russia and other countries.
If you set type to cash_on_delivery, once physical fulfillment is initiated, we send this data downstream to the fulfiller who, in turn, notifies the shipping carrier to collect COD.

Shipping quotes

A successful POST/shipping-quotes request returns a quotes array. Each object of that array represents a shipping quote. This object always contain a unique identifier associated with a shipping service level, as well as information on shipping costs, where the items are shipping from, and product availability.
Depending on your configuration, you may also get back data on signature requirements and estimated delivery times.

Unique identifier and service levels

Every shipping quote contains a unique id which is associated with a shipping method. This shipping method is designated by serviceLevel. That service level is, in turn, associated with the delivery type you specify in the request.
Shipping quotes
{
"shipTo": {
...
"type": "standard"
},
"quotes": [
{
"id": "IC",
...
"serviceLevel": "InternationalStandard",
...
"total": 10.0,
...
},
{
"id": "IS",
...
"serviceLevel": "InternationalExpress",
...
"total": 20.0,
...
}
],
...
}
The following table lists these enumerated shipping quote identifiers, their associated service levels, and the delivery type they support.
As an example, if you specify a shipTo.type of access_point in the POST/shipping-quotes request, you'll get back a maximum of two shipping quotes. That is the number of service levels this delivery type supports.
Identifier
Shipping service level
Supported delivery type
A1
accessPointExpress
access_point
AG
accessPointStandard
access_point
D1
expressNextDay
standard
D2
expressSecondDay
standard
IH
inHome
standard
IC
internationalExpress
standard
IS
internationalStandard
standard
SG
standard
standard
COD
standardCOD
cash_on_delivery

Shipping costs

A shipping quote provides you order-level and item-level shipping and handling costs. We aggregate these amounts into both an item total and an order total.
We also give you information on any fees incurred for non-standard services that may have been applied to the order.

Signature requirements

A shipping quote's signatureRequiredType indicates whether a signature is needed upon delivery, and, if it is, what type of signature is required. It's commonly used to prevent the theft of high-dollar items from a customer's doorstep after the goods have been delivered.
The value indicates whether the shipping carrier requires an adult to sign for delivery or a standard signer of any age is acceptable.
If signatureRequiredType is not contained in the response, it means that no delivery confirmation is needed for any of the products in the shipping quote.
Shipping carriers typically charge for performing this signature collection service. If you decide to pass this cost on to customers, then the amount the carrier charged is reflected in handling.
On orders with split shipments, meaning items are going to different addresses or arriving at the same address at different times , handling indicates the total signature collection cost for all the different shipments.
The order shipped notification you send customers should indicate whether they are required to provide a signature upon delivery.

Enabling the signature required feature

You'll need to contact your account manager to configure and enable the signature required feature.
The configuration process involves several steps. First, specific products within your channel's catalog need to be flagged. When these flagged products are included in an order, they trigger the signature required feature.
You can also set item-level and order-level amount thresholds. These tell us when to activate the feature. Let's say you have a product that is not flagged for signature collection. But a customer places an order for enough of these products to exceed your pre-defined amount threshold, thereby triggering a mandatory signature collection.
And finally, you'll need to tell us whether you or the customer will pay the cost the shipping carrier charges for providing this service.

Estimated delivery times

The estimatedMinimumDeliveryTime and estimatedMaximumDeliveryTime represent estimated minimum and maximum delivery times (in minutes) for this shipping method.

Inventory item identifier and availability

For each item in a shipping quote, we provide you its inventoryItemId as well as its quantity, availableQuantity, and availableTime.
You can also retrieve this same data by making a GET/inventory-levels request.

Ship from addresses

In a shipping quote, each element of the items array provides you a shipFrom address. This indicates the location of the warehouse where that specific product is shipped from. This allows you to build checkouts with products that ship from different addresses in different countries.
Shipping quotes
{
...
"quotes": [
{
"id": "SG",
...
"items": [
{
"inventoryItemId": "f785a6ac-d37b-46ca-92ed-2bea6f9dd14a",
...
"shipFrom": {
"address": {
"line1": "27081 Aliso Creek Rd",
"city": "Aliso Viejo",
"postalCode": "92656",
"state": "CA",
"country": "US"
}
},
...
}
]
},
...
],
"liveMode": false
}

Using a shipping quote

Once the customer selects a specific shipping quote, retrieve its data and send it in a create or update checkout request. This associates the shipping quote with the checkout.
Specifically, you should retrieve the shipping quote's id and total and use these values to set the checkout's shippingChoice.serviceLevel and shippingChoice.amount.
If all of a shipping quote's ship from values are identical, you can use this one address to specify the checkout's shipFrom. However, when describing a checkout's items, you have the ability to set shipFrom at the line-item level. So, if the shipping quote contains items with different ship from addresses, pass each of these unique values to the checkout's corresponding line item.
Shipping quote
Text
POST/checkouts/{id}
quotes[].id
shippingChoice.serviceLevel
quotes[].total
shippingChoice.amount
quotes[].items[].shipFrom
shipFrom or items[].shipFrom