Using a shipping endpoint
Gain a better understanding of how to use the Prebuilt Checkout shipping endpoint with Global Logistics and/or a third-party logistics provider
You might find such an endpoint to be useful, if, for example, Global Logistics facilitates your international transactions and another logistics provider assists you with domestic transactions.
Global Logistics also has the capability to help process your domestic orders.
If saved in Dashboard, Digital River calls this endpoint when processing checkouts that contain physical products.
Depending on whether you're using Global Logistics and/or a third-party logistics provider, the service you set up to handle our call can either filter and adjust the shipping options we send or use the request's data to make another call to your third-party provider to get the transaction's shipping options.
Either way, your response to our request must contain the options you want us to present to customers in the shipping choice selection stage.
On this page, you’ll find details on:
In your create checkout-session request, we recommend that you either reference or directly pass the weight and weight unit of each physical product in the customer's cart.
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.
Global Logistics uses this weight data to get more precise shipping rates, and, if the transaction is being facilitated by a third-party logistics provider, they can most likely do the same.
Goods eligible for inclusion in cross-border shipments should also be assigned a name, description, image, and url. For details on why this is important, refer to Defining basic product data on the Global Logistics page.
If you send
items[].skuId in the request, you can store all this product data in the referenced SKU. Otherwise, you'll need to pass it in items[].productDetails. You'll need to restrict the ship to countries that customers can select during the address collection stage to those that you support.
For details on how to do this, refer to Shopping country on the Checkout-sessions page or Restricting shipping and billing countries on the Configuring the modal page.
If you (1) use the Prebuilt Checkout solution, (2) enable the Global Logistics service, and (3) save a shipping endpoint in Dashboard, then you can use the information in this section to better understand:
Using the shipping endpoint with Global Logistics
Once customers input a shipping address, and it's determined that the transaction matches one of your trading patterns, our Global Logistics service calls the appropriate Global Logistics Provider to get the transaction’s available shipping options.
In that same request, Global Logistics also passes any default package data that may be saved to your account.
We then send a request to your shipping endpoint that contains these available
shippingMethods[] options plus the checkout-session’s currency, shipTo, items[], and unique identifier (sessionId). If you sent
upstreamId in the create checkout-session request, we pass this value in sessionUpstreamId as well.POST /checkout/shipping-quotes
{
"sessionId": "614fa310-2e62-442f-8499-4a3d2b55fef4",
"currency": "EUR",
"shipTo": {
"address": {
"line1": "Oranienburger Str. 32",
"city": "Berlin",
"postalCode": "10117",
"country": "DE"
},
"name": "Johann Doe",
"phone": "07854319925",
"email": "[email protected]"
},
"items": [
{
"sku": {
"id": "sku_e628c0d0-33b7-4dea-aa40-9eadc43e1583",
"name": "Red shirt",
"eccn": "8A992",
"taxCode": "55101504.100",
"image": "https://mdbootstrap.com/img/Photos/Horizontal/E-commerce/Vertical/12.jpg",
"url": "https://digitalriver.com/physical-product",
"physical": true,
"skuGroupId": "physical-product",
"weight": 20.5,
"weightUnit": "oz"
},
"amount": 11.95,
"quantity": 1,
"id": "948264e5-13ac-4001-b553-baea65cdcdea"
}
],
"shippingMethods": [
{
"amount": 15.06,
"description": "Economy",
"serviceLevel": "XLTUS-DEFAULT",
"shippingTerms": "DAP",
"shipFrom": {
"address": {
"city": "Los Angeles",
"postalCode": "90245",
"state": "California",
"country": "US"
}
}
},
{
"amount": 17.17,
"description": "Express",
"serviceLevel": "XLTUS-DEFAULT",
"shippingTerms": "DDP",
"shipFrom": {
"address": {
"city": "Los Angeles",
"postalCode": "90245",
"state": "California",
"country": "US"
}
}
},
{
"amount": 18.1,
"description": "Economy",
"serviceLevel": "XLTUK-DEFAULT",
"shippingTerms": "DDP",
"shipFrom": {
"address": {
"city": "Los Angeles",
"postalCode": "90245",
"state": "California",
"country": "US"
}
}
},
{
"amount": 24.84,
"description": "Express",
"serviceLevel": "XLTUK-DEFAULT",
"shippingTerms": "DDP",
"shipFrom": {
"address": {
"city": "Los Angeles",
"postalCode": "90245",
"state": "California",
"country": "US"
}
}
}
]
}
After your service accepts our request, it could process
shippingMethods[] by:- Discarding all the elements that have
shippingTermsofDAP. By doing so, you might potentially reduce the frequency of delivery refusals and returns. - Reducing one or more
amountvalues to give your customers a discount on their shipping costs.
Your service's response to our request must contain the
shippingMethods[] you want Digital River to present as options in the shipping choice selection stage. For each shippingMethods[], the values of description, serviceLevel, shippingTerms , and shipFrom must map to one of the methods we sent to your shipping endpoint. Each shippingMethods[] must also have an amount.Response
{
"shippingMethods": [
{
"amount": 16.99,
"description": "Express",
"serviceLevel": "XLTUS-DEFAULT",
"shippingTerms": "DDP",
"shipFrom": {
"address": {
"city": "Los Angeles",
"postalCode": "90245",
"state": "California",
"country": "US"
}
}
},
{
"amount": 17.99,
"description": "Economy",
"serviceLevel": "XLTUK-DEFAULT",
"shippingTerms": "DDP",
"shipFrom": {
"address": {
"city": "Los Angeles",
"postalCode": "90245",
"state": "California",
"country": "US"
}
}
},
{
"amount": 23.99,
"description": "Express",
"serviceLevel": "XLTUK-DEFAULT",
"shippingTerms": "DDP",
"shipFrom": {
"address": {
"city": "Los Angeles",
"postalCode": "90245",
"state": "California",
"country": "US"
}
}
}
]
}
For each
shippingMethods[] your service sends in the response, Digital River displays its amount, description, serviceLevel, and shippingTerms in the shipping choice selection stage.Digital River renders the
shippingTerms in such a way that their meaning is clearer to customers.Once customers make their selection, we use its data to set the checkout-session’s
shippingChoice and shipFrom.After Digital River converts the checkout-session to an order and sends you the event with a
type of order.accepted, you can retrieve shippingChoice and shipFrom from the event's data.object and then pass it (along with other required data) in a ship request to your 3PL. This allows your 3PL to send shippingChoice and shipFrom (along with other required data) to Global Logistics in a POST /shipping-labels request.
For details, refer to Managing a Global Logistics order.Event
{
"id": "e7f66af3-4207-4c23-b866-73efc8449525",
"type": "order.accepted",
"data": {
"object": {
"id": "255895420336",
...
"shipFrom": {
"address": {
"city": "Los Angeles",
"postalCode": "90245",
"state": "California",
"country": "US"
}
},
...
"shippingChoice": {
"amount": 17.99,
"description": "Economy",
"serviceLevel": "XLTUS-DEFAULT",
"taxAmount": 0.0,
"shippingTerms": "DDP"
},
...
"state": "accepted",
...
}
},
...
}
If you (1) use the Prebuilt Checkout solution, (2) save a shipping endpoint in Dashboard and (3) engage a third-party logistics service, you can use the information in this section to better understand:
Using the shipping endpoint with a 3rd party logistics provider
Once customers input a shipping address, and Digital River determines that the transaction is being facilitated by a third-party logistics provider, we send a request to your shipping endpoint that always contains the checkout-session’s
currency, shipTo, items[], and unique identifier (sessionId). For each
items[], we also give you an id that uniquely identifies that line item in our system.If you sent
upstreamId in the create checkout-session request, we pass this value in sessionUpstreamId as well.Since Digital River doesn't yet know what shipping options are available, the request contains no
shippingMethods[]. POST /checkout/shipping-quotes
{
"sessionId": "8e8f8a1b-4049-4e4f-a8b6-d5c6a90b713b",
"currency": "USD",
"shipTo": {
"address": {
"line1": "1234 Rocky Mountain Highway",
"city": "Estes Park",
"state": "CO",
"postalCode": "80517",
"country": "US"
},
"name": "John D.",
"phone": "5555555555",
"email": "[email protected]"
},
"items": [
{
"sku": {
"id": "sku_e628c0d0-33b7-4dea-aa40-9eadc43e1583",
"name": "Blue shirt",
"eccn": "8A992",
"taxCode": "55101504.100",
"image": "https://mdbootstrap.com/img/Photos/Horizontal/E-commerce/Vertical/12.jpg",
"url": "https://digitalriver.com/blue-shirt",
"physical": true,
"skuGroupId": "physical-product",
"weight": 20.5,
"weightUnit": "oz"
},
"amount": 11.95,
"quantity": 1,
"id": "714eb8ef-5a11-4faa-b6e5-35992d01d628"
},
{
"sku": {
"id": "sku_32ee813a-e7a8-46dc-97f4-fca07b47eca6",
"name": "Red shirt",
"eccn": "8A992",
"taxCode": "55101504.100",
"image": "https://mdbootstrap.com/img/Photos/Horizontal/E-commerce/Vertical/12.jpg",
"url": "https://digitalriver.com/red-shirt",
"physical": true,
"skuGroupId": "physical-product",
"weight": 20.5,
"weightUnit": "oz"
},
"amount": 11.95,
"quantity": 1,
"id": "945gh8ed-3g21-6ffg-mj6e6-45113e11d628"
}
]
}
After you accept our request, you can use its
currency, items[], and shipTo to call your logistics provider and get the transaction’s available shipping options. In that request, you'll most likely want to pass the
weight and weightUnit of each items[]. In most cases, your logistics provider can use that data to give you back more precise shipping rates.In addition, depending on the sophistication of the integration you have with your logistics provider, they may be able to give you the location of the warehouse(s) from which each
items[] is going to be shipped. After your logistics provider returns shipping method options, your service could add a mark up, discount them, and/or filter them by terms.
Your response must contain the
shippingMethods[] you want Digital River to present as options in the shipping choice selection stage. Each element in this array must have an amount, description, and serviceLevel and can optionally include shippingTerms and a shipFrom location.If your logistic provider's service was able to tell you where each line item is going to ship from, your response can also contain
shipments[], each of which should have a single shipFrom and a nested array of itemIds[], each mapped to one of the items[].id we sent to your shipping endpoint. Response
{
"shipments": [
{
"itemIds": [
"714eb8ef-5a11-4faa-b6e5-35992d01d628"
],
"shipFrom": {
"address": {
"line1": "10380 Bren Rd W",
"city": "Minnetonka",
"postalCode": "55343",
"state": "MN",
"country": "US"
}
}
},
{
"itemIds": [
"945gh8ed-3g21-6ffg-mj6e6-45113e11d628"
],
"shipFrom": {
"address": {
"line1": "1234 5th Ave",
"city": "New York",
"postalCode": "10005",
"state": "NY",
"country": "US"
}
}
}
],
"shippingMethods": [
{
"description": "Standard Shipping",
"serviceLevel": "Standard",
"amount": 2.99
},
{
"description": "Expedited Shipping",
"serviceLevel": "Expedited",
"amount": 10.98
}
]
}
For each
shipments[] in your response, we iterate through its itemsIds[], looking up each line item in our system and then use the shipments[].shipFrom to set that items[].shipFrom attribute in the checkout-session. For each
shippingMethods[] your service sends in the response, Digital River displays its amount, description, serviceLevel, and shippingTerms in the shipping choice selection stage.Digital River renders
shippingTerms in such a way that their meaning is clearer to customers.Once customers make their selection, we use its data to set the checkout-session’s
shippingChoice and, if that selection contains a shipFrom , we use that value to set the checkout-session's shipFrom.After Digital River converts the checkout-session to an order and sends you the event with a
type of order.accepted, you can you pass the order's data to your fulfillment service, which can then read the line-item level and/or order-level ship from values and route ship requests to the appropriate warehouses.Event
{
"id": "a443e1ee-61ec-4f9c-8c27-97b144c8f8f5",
"type": "order.accepted",
"data": {
"object": {
"id": "255896870336",
...
"items": [
{
"id": "185466030336",
"productDetails": {
"id": "physical-product-1",
"skuGroupId": "physical-product",
"name": "Blue shirt",
"url": "https://digitalriver.com/blue-shirt",
"countryOfOrigin": "US",
"image": "https://mdbootstrap.com/img/Photos/Horizontal/E-commerce/Vertical/12.jpg",
"weight": 20.5,
"weightUnit": "oz",
"partNumber": "Part123"
},
...
"shipFrom": {
"address": {
"line1": "10380 Bren Rd W",
"city": "Minnetonka",
"postalCode": "55343",
"state": "MN",
"country": "US"
}
},
...
},
{
"id": "185466050336",
"productDetails": {
"id": "physical-product-2",
"skuGroupId": "physical-product",
"name": "Red shirt",
"url": "https://digitalriver.com/red-shirt",
"countryOfOrigin": "US",
"image": "https://mdbootstrap.com/img/Photos/Horizontal/E-commerce/Vertical/12.jpg",
"weight": 20.5,
"weightUnit": "oz",
"partNumber": "Part123"
},
...
"shipFrom": {
"address": {
"line1": "1234 5th Ave",
"city": "New York",
"postalCode": "10005",
"state": "NY",
"country": "US"
}
},
...
}
],
"shippingChoice": {
"amount": 10.98,
"description": "Expedited Shipping",
"serviceLevel": "Expedited",
"taxAmount": 0.0
},
...
}
},
...
}
Last modified 3d ago