# Using shipping quotes {% hint style="warning" %} This page explains how to use the [Shipping Quotes API](https://app.gitbook.com/s/ScJM6Hp95yBCPfU1nBSB/shipping-quotes) in [versions ](https://app.gitbook.com/s/ZrhMyLX5esFYS64lNWVW/digital-river-api-reference-guide/versioning)`2020-12-17`, `2020-02-23`, and `2021-03-23` as part of a [Digital River coordinated fulfillment](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/handling-digital-river-coordinated-fulfillments). {% endhint %} In [Digital River coordinated fulfillments](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/handling-digital-river-coordinated-fulfillments), you call the [Shipping Quotes API](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/shipping-quotes) during [checkout](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/creating-checkouts) to provide customers with shipping options. In a [shipping quote request](#requesting-shipping-quotes), you must [describe the items](#items-to-ship) you'd like to ship and [where those items are going](#shipping-destination-and-type). In the response, we give you an array of [shipping quotes](#shipping-quotes), each describing the quote's [service level](#unique-identifier-and-service-levels), [shipping costs](#shipping-costs), [signature requirements](#signature-requirements), [estimated delivery times](#estimated-delivery-times), [inventory availability](#inventory-item-identifier-and-availability), and ship-from[ addresses](#ship-from-addresses). These shipping quotes can then be displayed to the customer. Once the customer selects, you can [use the data from a shipping quote to continue processing the checkout](#using-a-shipping-quote). {% hint style="info" %} Your logistics partner must obtain the checkout's [shipping information](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/creating-checkouts/shipping-choice) in [third-party coordinated fulfillments](https://docs.digitalriver.com/digital-river-api/order-management/fulfillments#third-party-coordinated-fulfillments). {% endhint %} ## Requesting shipping quotes In a [`POST /shipping-quotes`](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/shipping-quotes#shipping-quotes) request, you need to provide the `currency` used to pay for the shipping, the [items to ship](#items-to-ship), and their [destination and delivery type](#shipping-destination-and-type). This call to the [Shipping Quotes API](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/shipping-quotes) typically occurs late in the [checkout process](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/creating-checkouts), 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](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/checkouts). | `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` | {% tabs %} {% tab title="POST/shipping-quotes" %} ``` curl --location --request POST 'http://api.digitalriver.com/shipping-quotes' \ --header 'Authorization: Bearer ' \ --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 } ] }' ``` {% endtab %} {% endtabs %} ### Items to ship You must provide an array of products in your shipping quote request. Each element of the `items` array represents a specific [inventory item](https://docs.digitalriver.com/digital-river-api/product-management/skus#inventory-items). For each inventory item, you're required to specify its unique identifier, `price`, and `quantity`. {% hint style="warning" %} In [Digital River coordinated fulfillments](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/handling-digital-river-coordinated-fulfillments), your [SKUs and inventory items](https://docs.digitalriver.com/digital-river-api/product-management/common-attributes) form synchronous pairs. So the [checkout's ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/checkouts)`items[].skuId` can be used to set the [shipping quotes'](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/shipping-quotes)`items[].inventoryItemId`. {% endhint %} ### Shipping destination and type 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`](#standard-deliveries)(*default*), [`access_point`](#access-point-deliveries), or [`cash_on_delivery`](#cash-on-delivery). The delivery `type` affects [the returned service levels](#unique-identifier-and-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](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/handling-digital-river-coordinated-fulfillments/global-fulfillments) 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`](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/shipping-quotes) request returns a `quotes` array. Each object of that array represents a [shipping quote](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/shipping-quotes). This object always contains a [unique identifier associated with a shipping service level](#unique-identifier-and-service-levels), information on [shipping costs](#shipping-costs), where the [items are shipping from](#ship-from-addresses), and [product availability](#inventory-item-identifier-and-availability). Depending on your configuration, you may also get back data on [signature requirements](#signature-requirements) and [estimated delivery times](#estimated-delivery-times). ### Unique identifier and service levels Every [shipping quote](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/shipping-quotes) 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](#shipping-destination-and-type) you specify in the request. {% tabs %} {% tab title="Shipping quotes" %} ```javascript { "shipTo": { ... "type": "standard" }, "quotes": [ { "id": "IC", ... "serviceLevel": "InternationalStandard", ... "total": 10.0, ... }, { "id": "IS", ... "serviceLevel": "InternationalExpress", ... "total": 20.0, ... } ], ... } ``` {% endtab %} {% endtabs %} 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`](#shipping-destination-and-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](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/shipping-quotes) provides you with order-level and item-level `shipping` and `handling` costs. We aggregate these amounts into both an item `total` and an order `total`. We will 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](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/shipping-quotes) `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 must provide a signature upon delivery. #### Enabling the signature required feature You must 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 orders enough of these products to exceed your pre-defined amount threshold, 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`. {% hint style="warning" %} You can also retrieve this same data by making a [`GET /inventory-levels`](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/inventory-levels#inventory-levels) request. {% endhint %} ### Ship from addresses In a [shipping quote](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/shipping-quotes), each element of the `items` array provides you with a `shipFrom` address. This indicates the warehouse location from which that specific product is shipped. This allows you to [build checkouts with products that ship from different addresses in different countries](https://docs.digitalriver.com/digital-river-api/integration-options/creating-checkouts/providing-address-information#ship-from-address). {% tabs %} {% tab title="Shipping quotes" %} ```javascript { ... "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 } ``` {% endtab %} {% endtabs %} ## Using a shipping quote In [Digital River coordinated fulfillments](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/handling-digital-river-coordinated-fulfillments) that use either the [distributed model](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/handling-digital-river-coordinated-fulfillments/..#distributed-model) or [orchestrated model](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/handling-digital-river-coordinated-fulfillments/..#orchestrated-model)**,** after you [receive an array of shipping quotes](#shipping-quotes), present them to the customer. Once the customer selects a specific shipping quote, retrieve its data and send it in a [create ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/checkouts#checkouts-1)or [update checkout](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/checkouts#checkouts-id-1) request. This associates the shipping quote with the [checkout](#requesting-shipping-quotes). 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](#ship-from-addresses) are identical, you can use this one address to specify [the checkout's `shipFrom`](https://docs.digitalriver.com/digital-river-api/integration-options/creating-checkouts/providing-address-information#specifying-ship-from-at-the-checkout-level). However, when [describing a checkout's items](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/creating-checkouts/describing-the-items), you have the ability to [set `shipFrom` at the line-item level](https://docs.digitalriver.com/digital-river-api/integration-options/creating-checkouts/providing-address-information#specifying-ship-from-at-the-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 | | POST/checkouts/{id} | | :-------------------------: | :-: | :------------------------------: | | `quotes[].id` | ➔ | `shippingChoice.serviceLevel` | | `quotes[].total` | ➔ | `shippingChoice.amount` | | `quotes[].items[].shipFrom` | ➔ | `shipFrom` or `items[].shipFrom` |