Global Logistics
Learn how Global Logistics works and how to use the solution
Global Logistics (GL) is an end-to-end cross-border delivery management solution that can provide a guaranteed landed cost to both you and your customers.
In the pre-launch phase, you work closely with Digital River and one of our global logistics providers (GLPs) to build an integration that can accept and process international orders.
During checkouts, GL allows you to present customers with a menu of shipping quotes. Once the customer places an order and the goods are picked and packed at the warehouse, your third-party logistics provider can use GL to print shipping labels.
When an order ships, you can also use GL to track its progress.
On this page, you'll find information on how GL works as well as Digital River's guaranteed landed cost feature and our GLPs. You can also learn how to:

How Global Logistics works

During checkouts, Global Logistics (GL) gives you the capability to request international shipping quotes. Digital River routes your request to the appropriate global logistics provider (GLP) and then, based on their response, provides you a menu of shipping quotes that you can display to customers.
Once customers select a shipping quote, you can apply their choice to the checkout, and then, assuming they selected a quote with delivered duty paid (DDP) terms, use the duty, fee, and import tax amounts returned by Digital River to present customers with a transaction's full landed cost.
For more information, refer to the Guaranteed landed cost section.
After submitting the order, you must send a ship request to your third-party logistics (3PL) provider so that they can pick and pack the goods at the warehouse. When your 3PL is ready to print a shipping label, they send a request to Digital River, which we route to the appropriate GLP.
Upon receipt of this request, the GLP generates one or more shipping labels, sends those labels back to Digital River and we relay them to your 3PL.
The shipping label request also prompts the GLP to prepare an order's international shipping documentation. The GLP bundles this documentation in a pre-clearance request that gets sent to the destination country's customs agency.
Once the shipping labels are generated, a carrier retrieves the goods from the warehouse. In the hub and spoke logistics model, the carrier delivers the products to a distribution hub before they are moved to an export gateway and then shipped to the end customer's address. In the hubless model, the carrier delivers the goods directly to an export gateway, where they are shipped to the final destination.
After the goods arrive in the destination country, the GLP ensures that they clear customs, moves them to a distribution site and coordinates with local carriers to deliver them the "final mile" to the end customer.
Once the shipping labels are generated, you can also use GL to track an order's shipments. For each shipment, we provide you information on its products and status, as well as events that occur at specific locations along a delivery's route.

Guaranteed landed cost

In the Global Logistics solution, both you and your customers can receive a guaranteed landed cost.
With this feature, Digital River guarantees that you won't be charged any additional duties, fees, or import taxes beyond those contained in the order. This is true even when the actual importation costs assessed by a country's customs agency are higher than those returned by our landed cost calculator in checkouts.
We also guarantee that customers who select a shipping quote with delivered duty paid terms won't be required to pay any additional costs at the time of delivery. In other words, customers will have no surprise fees. Whatever they pay during the checkout process is the final amount.
Shipping is not part of a guaranteed landed cost. During checkouts, if customers select a shipping quote whose totalAmount is less than the actual, carrier assessed shipping costs, then Digital River is not responsible for the difference.
For more information, refer to:

Global logistics providers

In the Global Logistics solution, you partner with one or more of Digital River's global logistics providers (GLPs).
Digital River's GLPs specialize in shipping physical goods across national borders and are considered international logistics experts. They are well-versed in country-specific regulatory requirements, understand how to prepare the commercial invoices which act as the basis for all other international shipping documents, and have the capability to electronically submit pre-clearance requests to most countries' customs agencies.
Digital River's GLPs also have proprietary international shipping lanes, various export gateways, numerous final mile delivery options, and multiple logistics model offerings.

Pre-deployment

In the pre-deployment phase, you collaborate with Digital River and one of our global logistics providers (GLPs) to define your international trading patterns, configure product data, and set up your logistics.
The following sections describe the major areas of work that need to occur prior to deployment:
For more specific information about the pre-deployment process, refer to the Global Logistics implementation guide (see Accessing the learning tools for instructions).

Defining trading patterns

In the pre-deployment phase, Digital River and your GLP work with you to understand and define your trading patterns. These consist of what products you're selling, where your products ship from, and where they ship to.
Once defined, your trading patterns determine how the remainder of the pre-deployment process unfolds. They affect what basic and compliance data must be assigned to your products, how you configure your packaging, what countries are on your approved list, what your available shipping methods are, and how your logistics are set up.

Defining basic product data

Prior to launch, you must assign basic data to each cross-border eligible product in your catalog. This mainly consists of defining a product's name, weight, URL, image, and country of origin.
Where you store this basic product data and how you pass it in checkouts, depends on whether you're using SKUs or product details. For more information, refer to:

Name

Before deploying, make sure all of your products are assigned a name. This is true regardless of how you send product data in checkouts.

Weight

For each of your cross-border eligible products, you should determine its weight in grams, kilograms, ounces, or pounds and then store this value. In the Global Logistics (GL) solution, we highly recommend that you send a product's exact weight in POST/checkouts and POST/shipping-quotes requests. A product's weight:
  • Helps ensure that the shipping quotes returned in the checkout process are as accurate as possible. If you fail to send a product's weight in a shipping quotes request or pass a value that's less than its true weight, the shipping costs paid by the customer will likely be lower than the actual, carrier assessed costs. After an order is submitted, carriers compare a package's gross weight to its dimensions and then use dimensional weight pricing to calculate shipping costs. These carrier computed costs are what you ultimately pay.
  • Must be listed in the customs documentation for certain countries. This means that when customers want to ship a product to one of these countries, Digital River needs its weight to return a landed cost in checkouts, and customs officials need its weight to calculate duties and import taxes after the order is submitted.
A product's weight should be exclusive of its packaging but inclusive of its dunnage. In other words, don't include the weight of the product's box but do include the weight of the protective and supporting materials that go inside the box.
For more information, refer to:

Image and URL

A product's image and URL are typically added to the customs documentation.
Customs officials use this documentation to make a pre-clearance determination. While performing this process, these officials can use the URL to access a description of the product, and the image to see what the product looks like.
For more information, refer to:

Country of origin

A product's country of origin represents where a product was manufactured. The country value you pass to Digital River must be the same as what is listed on the product's certificate of origin.
For more information, refer to:

Defining compliance product data

Each cross-border eligible product in your catalog must be associated with compliance data.
Prior to deployment, Digital River and your GLP work with you to define this data. Once defined, a product's compliance data is stored in an associated SKU group.
For more information on the purpose of SKU groups, how they're set up, and how they're used, refer to the Grouping SKUs page.
The following describes some of the compliance data that must be defined during the prelaunch process:

Tax code

Each product must be associated with a tax code. It determines whether the product is classified as physical or digital. To ensure that the correct product taxes are assessed, the code should be as accurate as possible.
You'll need to provide Digital River with sufficient details about your products so that we can determine their tax codes and add this data to the relevant SKU group.

Export control classification number

A product must have a Digital River approved Export Control Classification Number (ECCN). This value determines whether the product:
  • Requires a U.S. export/re-export license
  • Contains any other license requirements/restrictions
  • Has an end use which is prohibited by applicable export control laws
Before launching, we work with you to identify your product's ECCNs and then store them in the relevant SKU groups.
For more information, refer to the ECCN section on the Managing SKUs page.

Harmonized system codes

You need to provide Digital River with sufficient details about your products so that we can classify their harmonized system (HS) codes. This includes the six-digit universal HS code used to classify product groups at the international level as well as country-specific HS codes.
These country-specific codes almost always have more digits than the universal code. Customs officials around the world use them to identify the duty and import tax rates that should be applied to different product groups. They are also needed by Digital River to generate a landed cost calculation.

Dangerous goods classifications

Certain products are classified as dangerous goods. They're considered to be any substance or material that poses unreasonable health, safety, or property risk when transported.
For example, some products, such as lithium batteries and (in)flammable perfumes, are susceptible to static electricity as well as temperature and pressure variations. These forces can cause them to leak, emit toxic fumes, ignite, or even explode. This is especially true when they are transported by air. As a result, these categories of products require special packaging, handling, and modes of transportation.
In the pre-launch phase, the GLP reviews your product labels to determine what products in your catalog may contain ingredients that necessitate a dangerous goods classification.
Once the GLP completes their review, they provide us a list of these products, along with their classification values. We then add this compliance data to the relevant SKU groups. Once that's done, you must associate the SKU group with the product.
For more information, refer to associating SKU groups with products on the Grouping SKUs page.
When you send a shipping quotes request, Digital River determines whether any products in that request are flagged as dangerous goods. If this is the case, we pass this information to the GLP and they add the appropriate surcharges.
For more information, refer to the Shipping quotes response section.
After an order is submitted, and its products have been picked and packed at the warehouse, the 3PL sends a shipping label request that gets transformed by Digital River and routed to the appropriate GLP. The GLP uses the data in this transformed request to determine whether the shipment contains any dangerous goods. If it does, they flag the entire shipment for special packaging and/or handling and encode that information in the shipping labels data that gets returned to the 3PL.
For more information, refer to the Managing shipping labels section.

Signature requirements

In the pre-deployment process, you should also determine what signature requirements your products may have. In other words, which products require customers to sign for them at the time of delivery.
These are often high-value items that you don't want to be left on the customer's "doorstep" by the delivery person. Putting a signature requirement in place helps prevent their theft.
For each product in your catalog that requires a signature, you must associate the appropriate SKU group with that product. Prior to this association process, Digital River will have added a signature required flag to those SKU groups.
For more information, refer to the Grouping SKUs page.
When you send a shipping quotes request, Digital River determines whether any products in that request require a signature. If this is the case, we pass this information to the GLP and they add the appropriate surcharges.
For more information, refer to the Shipping quotes response section.
After an order is submitted, and its products are picked and packed at the warehouse, the 3PL sends a shipping label request that gets transformed by Digital River and routed to the appropriate GLP. The GLP uses the data in the transformed request to determine whether the shipment contains any signature required goods. If it does, they flag the entire shipment as needing a signature and encode that data in the shipping labels that get returned to the 3PL. This data informs the final mile carrier that a signature is required.
For more information, refer to the Managing shipping labels section.

Configuring packaging

In the pre-launch phase, you have the ability to define a default box. Also, depending on the sophistication of the warehouse management software (WMS) you access, you may also decide to employ packing algorithms.

Default box

Our GL solution allows you to define a default box. In other words, a box configured with a default weight, height, width, and length. Digital River then associates these values with your site.
If you configure a default box, and you don't send packaging data in your shipping quotes request or shipping labels request, then we send these saved measurements to the GLP.
We recommend that you set a default box when you know that the vast majority of your products are going to be shipped in packages with uniform dimensions and a standardized weight. You can work with your WMS provider to identify your most frequently used box size.

Packing algorithms

Inefficient packing can result in higher shipping costs. This is because carriers often use dimensional weight pricing. This means that even if you’re shipping something relatively light, you could be charged for the amount of space the parcels occupy. This pricing strategy incentivizes efficient packing methods.
If your WMS uses bin packing algorithms, you can use them to potentially lower your shipping costs. These algorithms attempt to solve the problem of how to most efficiently pack multiple items of various sizes into a finite number of boxes. Based on the dimensions of a shipment's products, they return the recommended number of boxes and the optimal dimensions of each.
If you have access to such algorithms, work with your WMS provider to build an integration that allows you to request suggested box counts and dimensions during checkout. You can then pass the returned data in your shipping quotes request.

Configuring shipping methods

Pre-launch, the GLP reviews your warehouse locations, anticipated shipping volumes, and trading patterns. The GLP then identifies potential carriers and gets their applicable shipping methods and rates.
Once compiled, the GLP stores this data in their system. During the checkout process, when you make a shipping quotes request, the GLP accesses this saved data and uses it to construct a list of order-specific shipping quotes. You receive a simplified version of this list in the shipping quotes response.

Establishing a list of approved ship to countries

For each GLP that you are associated with, Digital River maintains a list of approved ship to countries. We then combine these GLP-specific lists into one, common list that represents the countries you can ship products to in the GL solution.
The process of building this single list takes into account your desired trading patterns. It also involves incorporating any (1) product-country restrictions identified by the GLP and (2) Digital River's default list of prohibited ship to countries.

Product-country restrictions

Some countries limit or block the importation of certain products. For example, one country might prohibit the introduction of specific cosmetics deemed to be culturally inappropriate. Another country may limit, per order, the quantity of imported electronics equipment.
In the pre-launch phase, the GLP reviews your catalog and identifies any such products. Once their review is complete, they generate a list of these product-country restrictions. This GLP generated list can then be used to help define the approved ship to countries that are stored in Digital River's system.

Digital River country restrictions

The Digital River APIs also have a list of prohibited ship to countries. Any create or update checkout request that passes one of these countries throws an error. As a result, none of them can be added to your GL list of approved ship to countries.

Logistics model designation

Prior to deployment, the GLP analyzes your warehouse locations, trading patterns, applicable carriers and expected ship volumes. Based on the results of this analysis, the GLP makes a logistics model determination.
More specifically, the GLP informs you whether (1) a hub and spoke logistics model or (2) a hubless logistics model best suits your needs. In both models, the GLP acts as the cross-border shipment manager.

Hub and spoke logistics model

In the hub and spoke model, the products are picked and packed at your 3PL's warehouse.
The 3PL then requests and prints a shipping label whose designated ship to address is one of the GLP's domestic, in-country hubs.
The products are then moved from the 3PL's warehouse to the specified hub.
Once the products arrive at the hub, the GLP prints another shipping label whose designated ship to address is the final destination of the goods, moves the goods to an export gateway, and then ships them to the destination country.

Hubless logistics model

In the hubless model, the products are picked and packed at your 3PL's warehouse.
The 3PL then requests and prints a shipping label whose designated ship to address is the final destination of the goods.
The GLP then dispatches a carrier to retrieve the products from the 3PL's warehouse, moves the goods to an export gateway, and ships them to the destination country.

GLP's responsibilities

Whichever logistics model is employed, in addition to the duties described above, the GLP also:
  • Prepares the import-export documentation
  • Submits pre-clearance requests to the importation country's custom agency
  • Ensures that the goods clear customs
  • Resolves any issues should the goods get "stuck in customs"
  • Coordinates with local carriers to ensure that the products are transported the "final mile" to the customer's designated ship to address

Building a cart

During the early stages of an ecommerce transaction, customers land on your storefront, review products, build a cart, confirm the cart's details, and initiate checkout. This cart-building process is roughly the same for both domestic and international transactions.
Digital River is usually not involved during these early pre-checkout interactions.
Some of your products however could have country restrictions applied to them. In other words, products prohibited from being exported to one or more specific countries.
For more information, refer to Establishing a list of approved ship to countries section.
To handle these prohibitions, you might want to block customers from adding restricted products to their carts. This helps avoid issues at customs as well as unanticipated return costs.
Plug-ins and extensions exist that geo-locate a customer's country. These add-ons then hide products from customers who are located in restricted countries. Some of these extensions also allow you to disable the add-to-cart button for prohibited product-country combinations.

Checking out customers

Once you initiate the checkout process, you should obtain the customer's name, email, shipping address, and billing address.
For more information, refer to sequencing the checkout process on the Building checkouts page.

Handling country and product restrictions

In your shipping address form, we suggest mounting a drop-down list (or some similar graphical control element) that restricts available ship to countries to those on your approved list.
For more information, refer to the Establishing a list of approved ship to countries section.
Once the customer selects a ship to country from your pre-defined list, determine whether any products in the customer's cart can't be exported to the selected country. If this is the case, inform customers of the prohibition and ask them whether they want to continue checking out.
If they respond in the affirmative, remove restricted products from the customer's cart before proceeding.

Creating the checkout

At this point, you can use the customer's shipping and billing information, along with product data retrieved from the customer's cart, to submit a create checkout request.
For more information, refer to sending the create checkout request on the Building checkouts page.

Managing shipping quotes

After you create a checkout, you need to send a shipping quotes request to Digital River. We transform your request and route it to the appropriate global logistics provider (GLP). The quality of the data you provide in this request determines the accuracy of the returned shipping quotes.
Upon receiving the shipping quote response, you may decide you want to handle the response by applying a filter before displaying the quotes to customers. Once the customer makes a selection, handle that selection by retrieving data from the selected quote and sending it in an update checkout request.

Defining and sending the shipping quote request

A POST/shipping-quotes request must pass the checkout's currency, ship to address, and physical product data. The request also needs to specify a ship from country. In addition, unless you want to use a stored default box, we recommend that you send package weight and dimensions.
POST/shipping-quotes
1
curl --location --request POST 'https: //api.digitalriver.com/shipping-quotes' \
2
...
3
--data-raw '{
4
"currency": "CAD",
5
"shipFrom": {
6
"address": {
7
"country": "US"
8
}
9
},
10
"shipTo": {
11
"address": {
12
"line1": "10-123 1/2 MAIN STREET NW",
13
"city": "MONTREAL",
14
"postalCode": "H3Z 2Y7",
15
"state": "QC",
16
"country": "CA"
17
},
18
"name": "JOHN JONES",
19
"phone": "367-222-4321",
20
"email": "[email protected]",
21
"organization": "Digital River"
22
},
23
"items": [
24
{
25
"productDetails": {
26
"skuGroupId": "group_1639749011",
27
"name": "PhysicalSku_1639749025",
28
"countryOfOrigin": "US"
29
},
30
"amount": 850,
31
"quantity": 1
32
},
33
{
34
"productDetails": {
35
"skuGroupId": "group_1639749016",
36
"name": "PhysicalSku_1639749033",
37
"countryOfOrigin": "US"
38
},
39
"amount": 1000,
40
"quantity": 1
41
}
42
],
43
"packages": [
44
{
45
"weight": 1.3,
46
"weightUnit": "kg",
47
"height": 8,
48
"width": 15,
49
"length": 20
50
}
51
]
52
}'
Copied!

Currency

You should retrieve the checkout's currency and use this value to define currency in the shipping quote request.

Ship to

In a shipping quotes request, you're only required to provide shipTo.address.country.
Earlier in the checkout process, you required customers to select a ship to country from a pre-defined list.
For more information, refer to Handling country and product restrictions.
You also obtained the customer's ship to street address, city, state/region, and postal code and then used this data to set the checkout's shipTo.
When configuring the shipping quotes request, you should retrieve these same values and use them to set shipTo. This helps make the returned shipping quotes as accurate as possible.
If you pass a shipTo.address.country in a shipping quotes request that is not supported by your defined trading patterns, then the following error is thrown:
400 Bad Request
1
{
2
"type": "bad_request",
3
"errors": [
4
{
5
"code": "invalid_parameter",
6
"parameter": "shipTo.address",
7
"message": "The shipTo.address is invalid with the shipFrom.address"
8
}
9
]
10
}
Copied!

Physical product data

Each physical product in the customer's shopping cart or the checkout's items[] should be passed in the shipping quote request's items[].
The following describes the key data you should send in each element's productDetails:
  • The id references the product in your upstream order management system.
  • The skuGroupId references the SKU group associated with the product. From this resource, we retrieve the product's compliance data. For more information, refer to the Grouping SKUs page.
  • A product's weight is technically not required, but it's extremely important data. Without it, the GLP won't be able to precisely determine shipping rates, which means totalAmount in the returned shipping quotes will likely be inaccurate. Product weight should be as precise as possible. Make sure the value you pass is exclusive of packaging but inclusive of dunnage. For more information, refer to defining basic product data in the Pre-deployment section. If you don't send weight or the value is inaccurate, then the shipping costs paid by the customer at checkout might be lower than the actual shipping costs assessed by the carrier. In this scenario, you're responsible for paying the difference. Therefore, we highly recommend that you send weight in the request.
  • A product's url , image , countryOfOrigin, and partNumber are generally not used by your GLP when generating shipping quotes. These attributes are however part of productDetails. So, if you send productDetails in checkouts, then, for simplicity's sake, you can reuse the same object in the shipping quotes request.
The product quantity selected by the customer is a key input for accurately calculating shipping costs. Therefore, it's a required value in items[].

Ship from

In the request, shipFrom represents the address of the product's warehouse. However, you only need to provide shipFrom.address.country. This is true even when you store your products in multiple warehouses in the same country.

Packages

In a shipping quotes request, you can also send packages[]. The values in this array are used to calculate dimensional weight, which helps determine totalAmount in each shipping quote we return to you.
If the products are typically shipped in large or irregularly shaped parcels, we recommend that you send packages[]. This helps ensure that the returned shipping quote amounts are as accurate as possible.
For each element in the array, you can specify a package's weight and weightUnit. The enumerated values of weightUnit are oz, lb, g, and kg. The default value is lb.
You can also send a package's height, width, and length. These values should be defined in inches.
In the request, there doesn't need to be any correlation between packages[] and items[].
If packages[] is empty when you submit the request, we determine whether you have a default box associated with your site, and if you do, we send that box's weight and dimensions to the GLP.
If your warehouse management software uses packing algorithms, prior to sending the shipping quotes request, you can send a different request to get recommended box counts and dimensions and then pass the returned values in packages[].
For more information on default boxes and packaging algorithms, refer to configuring packaging in the Pre-deployment section.

How Digital River handles your request

From your shipping quotes request, Digital River retrieves product and packaging data, and uses it to define another shipping quotes request that gets routed to a GLP.
To determine the appropriate GLP, we use the shipFrom.address.country and shipTo.address.country contained in your request, along with unique rules configured to your site.
If we determine that the ship to country is not supported by your trading patterns, we return a 409 Conflict with a code of InvalidShipToCountryCode.
When configuring the request, we also determine whether any unique product requirements exist.
To make this determination, from each line item in your request, Digital River accesses the SKU group referenced in productDetails.
We then use that SKU group to determine whether any such requirements exist, and, if they do, we package this data in the request.
Once configured, we send the transformed shipping quote request to the applicable GLP.

How Digital River handles the response

When the GLP responds to our request with a list of shipping quotes, we convert the cost of each back into the same currency you specified in your POST/shipping-quotes request.
For each shipping quote returned by the GLP, we also aggregate any carrier assessed fees or surcharges into a single total amount.

The shipping quotes response

Your POST/shipping-quotes request returns a currency and an array of shipping quotes[].
Shipping quotes
1
{
2
"currency": "CAD",
3
"quotes": [
4
{
5
"id": "58SLC-DHL",
6
"description": "Express",
7
"estimatedDelivery": "3 - 5 Business Days",
8
"shippingTerms": "DDP",
9
"totalAmount": 28.19,
10
"shipFrom": {
11
"address": {
12
"city": "Salt Lake City",
13
"postalCode": "84604",
14
"state": "Utah",
15
"country": "US"
16
}
17
},
18
"fees": {
19
"details": [
20
{
21
"name": "Fuel Surcharge",
22
"amount": 1.72
23
},
24
{
25
"name": "Temporary Surcharge",
26
"amount": 0.45
27
},
28
{
29
"name": "Dangerous Goods Fee",
30
"amount": 1.56
31
}
32
],
33
"amount": 3.72
34
}
35
},
36
{
37
"id": "58SLC-DHL",
38
"description": "Express",
39
"shippingTerms": "DAP",
40
"totalAmount": 28.19,
41
"shipFrom": {
42
"address": {
43
"city": "Salt Lake City",
44
"postalCode": "84604",
45
"state": "Utah",
46
"country": "US"
47
}
48
},
49
"fees": {
50
"details": [
51
{
52
"name": "Fuel Surcharge",
53
"amount": 1.72
54
},
55
{
56
"name": "Temporary Surcharge",
57
"amount": 0.45
58
},
59
{
60
"name": "Dangerous Goods Fee",
61
"amount": 1.56
62
}
63
],
64
"amount": 3.72
65
}
66
}
67
],
68
"liveMode": false
69
}
Copied!
If you configure your shipping quotes request correctly, the currency we give back to you should be the same as the checkout's currency.
Each element in the quotes[] array represents a shipping quote and contains the following attributes:

Unique identifier

Each shipping quote has a unique id. This identifier is generated by the GLP.
The shipping quotes in the array are not a resource. As a result, you can't use id to make an API call to retrieve a unique shipping quote.
However, when handling a customer's shipping quote selection, you do need to pass id to the checkout.

Description

The description indicates the duration of transportation. In other words, how quickly the goods are transported to the customer and what priority level they are assigned. Some common values are Economy, Express, and Priority. This is a pass-thru value from the GLP.

Estimated delivery range

A shipping quote's estimatedDelivery defines a minimum and maximum delivery period in days. For example, estimatedDelivery might be 3 - 5 Business Days.

Shipping terms

A shipping quote's shippingTerms are designated as either DDP or DAP. These values indicate when customers must pay duties, fees, and import taxes.
In delivered-duty-paid (DDP) shipments, the customer pays all duties, fees, and import taxes upfront during the checkout process. Upon product delivery, there are no additional charges they must pay.
To activate the guaranteed landed cost feature, customers must select a shipping quote with DDP terms.
In delivered-at-place (DAP) shipments, customers do not pay the full landed cost at checkout-time. Instead, they pay product and shipping costs, and then, upon delivery, they're responsible for paying duties, fees, and import taxes.
For more information, refer to:

Shipping costs and fees

A shipping quote's totalAmount represents how much customers must pay to ship an order's products to the final destination address. It includes the estimated cost of handling, transportation, and postage as well as carrier assessed surcharges and fees.
In fees, we itemize these estimated fees and surcharges. A carrier might collect them to, for example, offset the cost of higher fuel prices, package signature options, or dangerous goods handling requirements.
The denomination of totalAmount, fees.amount, and fees.details[].amount is contained in the response's single currency.

Ship from

Each shipping quote's shipFrom represents the address of the products' warehouse. This means that each quote you get back is associated with an individual warehouse.
In the shipping quotes request, you specified a shipFrom.address.country. If you have multiple warehouses in this country, then the response may contain one or more quotes[] with the same description and serviceLevel but different shipFrom values.
This allows you to filter the shipping quotes you display to the customer based on warehouse location.

Handling the shipping quotes response

Depending on your business objectives, you may decide you want to filter the returned shipping quotes before displaying them to customers.

Filtering shipping quotes

If you want to activate the guaranteed landed cost feature, then you should only display shipping quotes whose shippingTerms are DDP to customers. To trigger this feature, setting a checkout's shippingTerms to DDP is one of the necessary preconditions.
For more information, refer to:
In a effort to minimize rejections, returns, and chargebacks, you may decide you only want to present shipping quotes with DDP terms.
Orders with DAP terms generally have higher return rates. At the time of delivery, some customers may be unaware of the outstanding balance and, in response, either refuse the delivery altogether or accept the delivery and then return the products.
You should be aware however that some carrier and ship to country combinations don't support the prepay DDP option. In these cases, the only quotes[] contained in the shipping quotes response, and therefore the only quotes[] you'll be able to display to the customer, are those with DAP terms.
So, if one of your approved ship to countries doesn't support DDP, make sure you have logic in place that displays DAP quotes in the event DDP quotes are not returned.
If you want customers to select a shipping quote associated with a specific warehouse, then you can filter by shipFrom. This is useful when you have multiple warehouses but you'd like the products to ship from a facility that's in close proximity to a GLP distribution hub.

Displaying shipping quotes

Radio button controls are commonly used to display shipping quotes. This control requires customers to select a single quote from the mutually exclusive and (potentially) filtered options you present.
For each shipping quote that you display, reveal its serviceLevel, estimatedDelivery, and totalAmount.
If you'd like to provide customers with more shipping cost granularity, you can also display fees.details[] and/or fees.amount.
You should indicate whether the quote's shippingTerms are DAP or DDP. We recommend however that you don't use these acronyms in your graphical user interface (GUI). Few, if any, customers will understand their meaning. Instead, display a more user-friendly description. For example:
Shipping terms
Customer-facing text
DAP
Import charges collected upon delivery
DDP
No additional import charges at delivery
Here's an example of what this might look like in a GUI:

Handling the shipping quote selection

When customers select a shipping quote, handle that event by retrieving data from the selection and using it to define the checkout's shippingChoice and shipFrom:
Shipping quote
Text
POST/checkouts/{id}
id
shippingChoice.id
amount
shippingChoice.amount
description
shippingChoice.description
serviceLevel
shippingChoice.serviceLevel
shippingTerms
shippingChoice.shippingTerms
shipFrom
shipFrom
You can then submit an update checkout request. If all the necessary preconditions are met, this request prompts Digital River to call its landed cost service.
If the checkout's shippingTerms are DDP, then the response to your update checkout request provides recalculated duty, fee, and import tax amounts at both the checkout-level and line-item level.
For more information, refer to how landed cost is represented in checkouts on the Landed cost page.
In the Global Logistics solution, the customer is the designated importer of record. As a result, the customer pays the checkout's totalImporterTax.
If the checkout's shippingTerms are DAP, then checkout-level and line-item level duty, fee, and import tax amounts are all zero.
DDP Checkout
DAP Checkout
1
{
2
"id": "206bfba3-7bda-4d0b-b6e3-657875b5cc6c",
3
"createdTime": "2021-11-11T22:25:24Z",
4
"currency": "EUR",
5
"email": "[email protected]",
6
"shipTo": {
7
"address": {
8
"line1": "Neuer Wall 10",
9
"city": "Hamburg",
10
"postalCode": "20354",
11
"country": "DE"
12
},
13
"name": "John",
14
"phone": "9526123456",
15
"email": "[email protected]"
16
},
17
"shipFrom": {
18
"address": {
19
"line1": "Landed Cost Cross Order",
20
"line2": "80 Sunraysia Road",
21
"city": "INVERMAY",
22
"postalCode": "3352",
23
"state": "Victoria",
24
"country": "AU"
25
}
26
},
27
"totalAmount": 1809.99,
28
"subtotal": 1809.99,
29
"totalFees": 0.0,
30
"totalTax": 0.0,
31
"totalImporterTax": 288.99,
32
"importerOfRecordTax": true,
33
"totalDuty": 221.0,
34
"totalDiscount": 0.0,
35
"totalShipping": 100.0,
36
"items": [
37
{
38
"id": "434e3932-a20d-49d3-ad82-0abb25eaa9be",
39
"skuId": "3c99757b-a543-455f-bbd3-57dc1bb21579",
40
"amount": 1200.0,
41
"quantity": 3,
42
"tax": {
43
"rate": 0.36,
44
"amount": 0.0
45
},
46
"importerTax": {
47
"amount": 288.99
48
},
49
"duties": {
50
"amount": 221.0
51
},
52
"fees": {
53
"amount": 0.0,
54
"taxAmount": 0.0
55
},
56
"tariffCode": "6404201000"
57
}
58
],
59
"shippingChoice": {
60
"id": "testDDP",
61
"amount": 100.0,
62
"description": "FedEx Next Day",
63
"serviceLevel": "Test",
64
"taxAmount": 0.0,
65
"shippingTerms": "DDP"
66
},
67
"updatedTime": "2021-11-11T22:25:24Z",
68
"locale": "en_US",
69
"customerType": "individual",
70
"sellingEntity": {
71
"id": "DR_IRELAND-ENTITY",
72
"name": "Digital River Ireland Ltd."
73
},
74
"liveMode": false,
75
"payment": {
76
"session": {
77
"id": "1822d8bd-1531-40da-aedc-10ac9b0eda4c",
78
"amountContributed": 0.0,
79
"amountRemainingToBeContributed": 1809.99,
80
"state": "requires_source",
81
"clientSecret": "1822d8bd-1531-40da-aedc-10ac9b0eda4c_4b58e8ed-505c-4334-b349-bc65be9029e5"
82
}
83
}
84
}
Copied!
1
{
2
"id": "2554c935-98a4-49e6-95ac-1d179c47b2e4",
3
"createdTime": "2021-11-11T22:26:22Z",
4
"currency": "EUR",
5
"email": "[email protected]",
6
"shipTo": {
7
"address": {
8
"line1": "Neuer Wall 10",
9
"city": "Hamburg",
10
"postalCode": "20354",
11
"country": "DE"
12
},
13
"name": "John",
14
"phone": "9526123456",
15
"email": "[email protected]"
16
},
17
"shipFrom": {
18
"address": {
19
"line1": "Landed Cost Cross Order",
20
"line2": "80 Sunraysia Road",
21
"city": "INVERMAY",
22
"postalCode": "3352",
23
"state": "Victoria",
24
"country": "AU"
25
}
26
},
27
"totalAmount": 1300.0,
28
"subtotal": 1300.0,
29
"totalFees": 0.0,
30
"totalTax": 0.0,
31
"totalImporterTax": 0.0,
32
"totalDuty": 0.0,
33
"totalDiscount": 0.0,
34
"totalShipping": 100.0,
35
"items": [
36
{
37
"id": "5fbe0052-7b63-460a-a5f6-c516ab9b900d",
38
"skuId": "3c99757b-a543-455f-bbd3-57dc1bb21579",
39
"amount": 1200.0,
40
"quantity": 3,
41
"tax": {
42
"rate": 0.0,
43
"amount": 0.0
44
},
45
"importerTax": {},
46
"duties": {},
47
"fees": {
48
"amount": 0.0,
49
"taxAmount": 0.0
50
},
51
"tariffCode": "6404201000"
52
}
53
],
54
"shippingChoice": {
55
"id": "testDAP",
56
"amount": 100.0,
57
"description": "FedEx Next Day",
58
"serviceLevel": "Test",
59
"taxAmount": 0.0,
60
"shippingTerms": "DAP"
61
},
62
"updatedTime": "2021-11-11T22:26:22Z",
63
"locale": "en_US",
64
"customerType": "individual",
65
"sellingEntity": {
66
"id": "DR_IRELAND-ENTITY",
67
"name": "Digital River Ireland Ltd."
68
},
69
"liveMode": false,
70
"payment": {
71
"session": {
72
"id": "561f72d9-44e0-4002-840b-908df73926c4",
73
"amountContributed": 0.0,
74
"amountRemainingToBeContributed": 1300.0,
75
"state": "requires_source",
76
"clientSecret": "561f72d9-44e0-4002-840b-908df73926c4_3493ddf5-d60e-474d-b2d3-2bda3237649d"
77
}
78
}
79
}
Copied!
In both DAP and DDP scenarios, use the checkout's data to update the product, shipping, duties, fees, taxes, and total amounts displayed to the customer. When displaying duty and import tax amounts in DAP scenarios, let customers know that they don't pay these costs at checkout time. We recommend using language such as "Outstanding" or "Collected upon delivery".
Here's an example of what this might look like in a GUI:
DDP selection
DAP selection

Collecting payment

In Global Logistics, you collect payment in much the same way you would in any checkout flow.
Prior to initiating the payment collection process, you obtain the customer's billing information and use it to set (at a minimum) the checkout's billTo.address.country. In the same create checkout request, you also set the checkout's currency.
Once you initiate payment collection, Drop-in only displays payment methods applicable to that currency and bill to country.
If you're using DigitalRiver.js to collect payment, make sure that only applicable payment methods are presented to the customer. You do this by passing the checkout's billTo.address.country and currency to your front-end retrieveAvailablePaymentMethods() method.
For more information, refer to:

Submitting the order

After the necessary preconditions are met, you can convert the checkout to an order. Once you synchronously or asynchronously receive an order in an accepted state, send a ship request to your third-party logistics (3PL) provider.
For more information, refer to handling accepted orders on the Processing orders page.
A successfully created order also prompts Digital River to save landed cost data for reconciliation purposes.

Sending the ship request

Once the order is in an accepted state, you should use its data to define a request that gets routed to one of your 3PL's warehouses.
At a minimum, the request should include the order's identifier and each line item's unique identifier. The 3PL needs these values to define a shipping label request that gets routed to the global logistics provider (GLP).
For more information, refer to Managing shipping labels.
As with any ship request, you also need to include sufficient order details so that the warehouse knows which products and in what quantity to pick and pack.

Landed cost reconciliation

In the Global Logistics solution, after you create an order, Digital River persists order-level and line-item level duty, fee, and import tax data. We store this data so that it can be reconciled with the actual duties, fees, and import taxes assessed by a country's custom agency. This reconciliation process is part of the guaranteed landed cost feature.

Managing shipping labels

Upon receipt of your ship request, the third-party logistics (3PL) provider picks and packs the goods at the warehouse.
When the 3PL needs to print the ship label, they must determine, based on the order's ship to country, whether it's a domestic or international shipment.
If it's a domestic shipment, then the 3PL prints a standard ship label, ships the products, and notifies you of the shipment. In most integrations, this notification triggers a payment capture request.
For more information, refer to the Capturing and cancelling payment charges page.
If it's an international shipment, your 3PL must send a shipping label request to Digital River. In the hub and spoke logistics model, the returned shipping labels contain the address of one of the GLP's in-country hubs. In the hubless logistics model, the labels contain the end customer's ship to address.

Defining and sending the shipping label request

In a POST/shipping-labels request, your 3PL must send an order identifier, product data, packaging data, and a label format.
Unless you're switching the fulfillment warehouse, you don't need to send shippingChoice or shipFrom in the shipping label request.
POST/shipping-labels
1
curl --location --request POST 'https: //api.digitalriver.com/shipping-labels' \
2
...
3
--data-raw '{
4
"orderId": "1003597810082",
5
"labelFormat": "PDF",
6
"items": [
7
{
8
"itemId": "11668110082",
9
"quantity": 1
10
}
11
],
12
"packages": [
13
{
14
"weight": 5.345,
15
"weightUnit": "lb",
16
"height": 2,
17
"width": 5,
18
"length": 8
19
}
20
]
21
}'
Copied!

Order identifier

After you convert a checkout to an order, Digital River returns a unique order identifier. Your integration should have then passed this order identifier to your 3PL in the ship request.
When defining the shipping label request, your 3PL needs to retrieve this identifier and use it to set orderId.
Order
Text
Ship request
Text
POST/shipping-labels
id
order identifier
orderId
If your 3PL sends an invalid orderId, then the following error is returned:
404 Not Found
1
{
2
"type": "not_found",
3
"errors": [
4
{
5
"code": "not_found",
6
"parameter": "id",
7
"message": "Order 'I8Na1N0gxyq8yni' not found."
8
}
9
]
10
}
Copied!

Shipping choice

In the request, shippingChoice is optional because the order already contains a shippingChoice. If you don't specify shippingChoice in the shipping label request, then the order's shippingChoice is by default encoded in the shipping label's data file.
For more information, refer to Switching the fulfillment warehouse.

Ship from

In the request, shipFrom is optional because the order already contains a shipFrom. If you don't specify shipFrom in the shipping label request, then the order's shipFrom is by default encoded in the shipping label's data file.
For more information, refer to Switching the fulfillment warehouse.
If your 3PL sends a shipFrom that's not supported by your trading patterns, then the following error is returned:
400 Bad Request
1
{
2
"type": "bad_request",
3
"errors": [
4
{
5
"code": "invalid_parameter",