Managing a Global Logistics order
Gain a better understanding of how to managage a Global Logistics order
On this page, you'll find an overview of the order management process in Global Logistics. For more details about each stage, refer to:
After the order's
state
becomes accepted
, 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 the 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.
At a minimum, the request must include the order's
id
and each items[].id
. The 3PL needs these values to define the POST/ shipping-labels
request that GL routes to the global logistics provider (GLP).You can also pass the order's
shipFrom
and shippingChoice
to your 3PL for inclusion in the shipping labels request.As with any ship request, you'll also need to include sufficient order details so that the warehouse knows which products and in what quantity to pick and pack.
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 label, ships the products, and notifies you of the shipment. In most integrations, this notification triggers a payment capture request.
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.
In the
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, your 3PL doesn't need to send
shippingChoice
or shipFrom
in the shipping label request.POST/shipping-labels
curl --location --request POST 'https: //api.digitalriver.com/shipping-labels' \
...
--data-raw '{
"orderId": "1003597810082",
"labelFormat": "PDF",
"items": [
{
"itemId": "11668110082",
"quantity": 1
}
],
"packages": [
{
"weight": 5.345,
"weightUnit": "lb",
"height": 2,
"width": 5,
"length": 8
}
]
}'
When defining the shipping label request, your 3PL needs to retrieve the order
id
you sent in the ship request 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
{
"type": "not_found",
"errors": [
{
"code": "not_found",
"parameter": "id",
"message": "Order 'I8Na1N0gxyq8yni' not found."
}
]
}
In the request,
shipFrom
is optional because the order already contains a shipFrom
. If shipFrom
is not passed, then, by default, the order's shipFrom
is encoded in the shipping label's data file
.If your 3PL sends a
shipFrom
that's not supported by your trading patterns, then the following error is returned:400 Bad Request
{
"type": "bad_request",
"errors": [
{
"code": "invalid_parameter",
"message": "The logistics partner was not found."
}
]
}
- Must include the product
quantity
being shipped.
Order | Text | Ship request | Text | POST/shipping-labels |
---|---|---|---|---|
items[].id | ➔ | line item identifiers | ➔ | items[].itemId |
- Can optionally send a
productDetailsId
that uniquely identifies the product in your order management system.
If you send
packages[]
, each element must contain a weight
denoted by a weightUnit
. The weight
should represent the scale weight of the package at your 3PL's warehouse. The enumerated weightUnit
values are oz
, lb
, g
, and kg
.Failure to provide
weight
or weightUnit
returns a 400 Bad Request
with a code
of missing_parameter
.You can also pass the dimensions of each package in the shipment. A package's
height
, width
, and length
should be denoted in inches.It's important that a package's weight and dimensions are as accurate as possible. These values are used by the carrier to determine a shipment's actual costs.
If
packages[]
is empty when you submit the request, we determine whether you have a default box, and, if you do, we send that box's weight and dimensions to the GLP.In the request,
labelFormat
represents the file format you want the shipping labels to be returned in. Currently, the only available format is PDF
. However, if you choose to, you can set up a different labelFormat
, such as JPG or PNG, with your GLP.In these scenarios, you can use a
POST /shipping-labels
to update an order's shippingChoice
and shipFrom
. To do this, you must first define and submit a POST /shipping-quotes
and then, from the response, select a new quote.When defining the shipping label request, use the selected quote's data to set
shippingChoice
and shipFrom
. Once you submit this request, Digital River uses these values to update the order's shippingChoice
and shipFrom
.When Digital River receives a shipping label request from your 3PL, we retrieve
orderId
from the payload and use it to look up the order in our system.We then use each of the request's
items[].itemId
values to get data on the order's physical products that are going out in the shipment.This consists of a product's name, declared value (i.e., the order's
items[].amount
), quantity, harmonized system tariff code, country of origin, and weight. We also pass along any product signature requirements and dangerous goods classifications. If the product contains a part number, url, and image, then we send that data as well.At the order-level, we pass
shipFrom
, shipTo
, shippingChoice
, and any other order data needed by the GLP.We also pass the packaging data sent by the 3PL, or, in the event no packaging data exists in the shipping label request, your default box's weight and dimensions.
We then route this product, order, and packaging data to the appropriate GLP.
Upon receipt of the transformed shipping label request, the GLP determines where the goods must be shipped and then generates one or more shipping labels that point the products to either the address of the end customer or the address of an in-country GLP hub.
The GLP also determines whether the products have dangerous goods handling requirements and/or signature requirements, and, if they do, the GLP adds this information to the shipping label's encoded data.
The GLP then returns the shipping labels to Digital River.
After the GLP generates a shipment's shipping labels, order tracking data typically becomes available. For details, refer to Tracking order shipments.
A shipping label request also prompts the GLP to prepare a shipment's customs documentation. This documentation is then packaged in a digital pre-clearance request that the GLP typically sends to an importation country's customs agency.
The shipping label response provides your 3PL the data it needs to print one or more physical shipping labels. Sometimes, the response also contains supplemental customs documentation.
Shipping labels
{
"id": "100000048501",
"orderId": "1003597810082",
"labels": [
{
"height": 6,
"width": 4,
"format": "PDF",
"file": ...
}
],
"returnTo": {
"address": {
"line1": "123 Airport Road",
"city": "Salt Lake City",
"postalCode": "84604",
"state": "Utah",
"country": "US"
},
"phone": "555-555-5555",
"organization": "DR Client 4"
},
"liveMode": false
}
The response contains a unique
id
. This value is generated by Digital River.In the response, we return
labels[]
. Each element of this array contains:- A
height
andwidth
. These are the shipping label's dimensions. The values are denoted in inches. - The
format
of the shipping label's datafile
. This is an enumerated fileformat
. Currently, the only returned value isPDF
. - A
file
with binary base64 encoded data. In most cases,file
contains an encoded shipping label. However,file
doesn't hold any product data. Instead, Digital River stores product data at the shipment level and then retrieves it when you make an order tracking request. Sometimesfile
also contains additional documentation, such as the commercial invoice. This happens when the GLP is unable to submit a digital pre-clearance request to a country's customs agency (not all country-carrier combinations support this feature). In these cases, the 3PL needs to print the customs documentation and attach it to the packages.
In the shipping label response,
returnTo
contains the product return address assigned by the GLP. After returns request is approved, you should instruct customers to mail the products they're returning to this address.The GLP always attempts to find a return to address that's in the same country (or at least the same political region) as the shipment's destination address. If no such location exists, then the return to address is the warehouse where the goods are picked and packed.
You can use these
returnTo
values as you see fit. For example, you may decide to display them on a customer's order management page, include them in email notifications or list them on invoices.Upon receiving the shipping label response, the 3PL needs to decode each
labels[]
base64 data file
and write the binary out to the designated file format
. They can then open the file and print the label.If the response contains multiple
labels[]
, then it doesn't matter which label gets applied to each package in the shipment. A shipping label's data file
doesn't contain any product data, and, as a result, no one-to-one association exists between a label and a box. Instead, all the boxes (and the products within them) are tracked as a single shipment.When
labels[].file
contains customs documentation, such as the commercial invoice, the 3PL must also print this paperwork and secure it to the packages.Shipping label
Customs documentation


The goods are then moved to the address designated on the shipping label. At this point, your 3PL typically sends a shipped notification to your system that triggers a payment capture request.
In the hub and spoke logistics model, the 3PL affixed shipping labels direct the goods to a GLP hub. At this hub, the final destination shipping labels are printed and put on the packages. The GLP then moves the goods to an export gateway before shipping them to the destination country.
In the hubless model, the 3PL affixed shipping labels direct the goods to one of the GLP's export gateways. At this facility, the final destination shipping labels are printed and attached and then the goods are shipped.
The GLP pays the duties, fees, and import taxes assessed by a country's custom agency and sends those landed cost actuals to Digital River so that we can use them in our landed cost reconciliation process.
Once the goods clear customs, the GLP coordinates with local carriers to move the products to a distribution warehouse where they are retrieved and delivered the "final mile" to the order's ship to address.
If the customer selected DAP shipping terms during the checkout process, then the recipient is required to pay an order's unpaid balance at the time of delivery.
In this section, you'll find details on:
Order tracking information typically becomes available after the GLP generates a shipping label and creates a shipment. If you send a
GET /orders/{id}/tracking
request prior to label generation, then the following error is thrown:404 Not Found
{
"type": "not_found",
"errors": [
{
"code": "invalid_parameter",
"parameter": "orderId",
"message": "There are no shipments found for an order."
}
]
}
Less commonly, the GLP creates a shipping label, but, for whatever reason, has yet to generate tracking information for that shipment. In this scenario, a
GET /orders/{id}/tracking
request returns the following error:404 Not Found
{
"type": "not_found",
"errors": [
{
"code": "invalid_parameter",
"parameter": "orderId",
"message": "The tracking information was not found for an order or order has not been shipped yet."
}
]
}
To track shipments, send an order's unique identifier as a path parameter in a
GET /orders/{id}/tracking
.GET/orders/{id}/tracking
curl --location --request GET 'https: //api.digitalriver.com/orders/1003597810082/tracking' \
...
You'll most commonly send this request when customers go to their order management page and select a specific order they want to track.
In the order tracking response, you'll find real-time data on each
shipments[]
' products as well as their shipFrom
location and delivery status
.Order tracking
{
"orderId": "1003597810082",
"shipTo": {
"address": {
"line1": "10-123 1/2 MAIN STREET NW",
"city": "MONTREAL",
"postalCode": "H3Z 2Y7",
"country": "CA"
},
"name": "JOHN JONES",
"phone": "367-222-4321",
"email": "[email protected]",
"organization": "Digital River"
},
"shipments": [
{
"id": "100000048501",
"status": "pending_shipment",
"shipFrom": {
"address": {
"city": "Salt Lake City",
"postalCode": "84604",
"state": "Utah",
"country": "US"
}
},
"items": [
{
"itemId": "11668110082",
"productDetails": {
"name": "PhysicalSku_1639749025",
"skuGroupId": "group_1639749011",
"weight": 0.0,
"weightUnit": "lb",
"countryOfOrigin": "US"
},
"quantity": 1
}
],
"trackingDetails": [
{
"date": "2021-12-20T02:46:43",
"description": "Order Data Created/Received",
"location": "-"
},
{
"date": "2021-12-19T19:47:16",
"description": "Shipping Label Generated",
"location": "Salt Lake City Utah US"
}
]
}
],
"liveMode": false
}
In
shipTo
, you're given the final delivery address
of the order's products, along with details on the buyer. Each
shipments[]
represents a unique shipment in the order. We return an array because orders are sometimes sent out for delivery in multiple batches.Each element of
shipments[]
contains:- A unique identifier: A shipment's unique
id
is generated by Digital River. - A ship from address: A shipment's
shipFrom
represents the address of the warehouse where the products were picked and packed. - Product data: A shipment's
items[]
contain data on the products in that shipment. Each element ofitems[]
containsproductDetails
and a shippedquantity
. Regardless of how you send product data in checkouts, theproductDetails
object is returned in the order tracking response. We also return anitemId
that identifies each of an order'sitems[]
that have shipped. - A shipment status: The
status
of a shipment can bepending_shipment
,in_transit
,delivery_attempted
,delivered
,refused
,cancelled
,awaiting_shipment
, andcontact_customer_service
. Each GLP maintains its own unique shipment status values. Digital River normalizes this data before we return it to you. So, whichever GLP manages an order's delivery, a shipment'sstatus
will always be one of our standardized values. - Tracking details: A shipment's progress is recorded in
trackingDetails[]
. Each element of this array provides you adescription
of an event that occurred at a particularlocation
on a specificdate
. The date-time values are the local time at the specifiedlocation
.array indexdatelocationdescription02021-08-13T15:20:00Z
-
Order Data Created/Received
12021-08-13T15:21:00Z
Salt Lake City Utah US
Shipping Label Generated
22021-08-13T20:36:00Z
Salt Lake City Utah US
Customs status updated
32021-08-16T08:15:00Z
LOS ANGELES GATEWAY,CA-USA
Arrived at Sort Facility LOS ANGELES GATEWAY,CA-USA
42021-08-19T03:32:00Z
BRUSSELS-BEL
Transferred through BRUSSELS-BEL
52021-08-20T14:06:00Z
POINTE NOIRE-COG
Clearance processing complete at POINTE NOIRE-COG
For each
shipments[]
, you can use its items[]
to display product details, status
to display a shipment's overall progress, and trackingDetails[]
to display information about each stage of a shipment's journey.As with all dates and times in the Digital River APIs, we recommend you transform
date
in trackingDetails[]
into a more human-readable form before you display it to customers.
The Global Logistics (GL) solution allows you to process customer-initiated returns, delivery refusals, and undeliverable packages. You do this by sending return requests and/or listening for return events.
When you receive a
logistics-returns.received
event, use its type
to appropriately update the status of the return in your system and notify customers of the accepted return, refused delivery, or undeliverable package.At any stage of the returns process, you can give customers a refund by using the Refunds API. For details, refer to the Issuing refunds page.
The following describes how to process customer-initiated returns that stem from damaged goods, faulty products, a 'change-of-heart' and other similar scenarios.
If a customer requests a return, and you determine the request is valid, your order management system needs to define and send a
POST /logistics-returns
. You can configure this request to generate both full and partial order returns.POST/logistics-returns
curl --location --request POST 'https://api.digitalriver.com/logistics-returns' \
...
--data-raw '{
"orderId": "1006970340082",
"rmaNumber": "57d34656-966e-4bcf-ad87-4c44ae1beb14",
"reason": "Damaged",
"items": [
{
"itemId": "10366350082",
"quantity": 3
}
]
}'
Additionally, you're required to pass the return merchandise authorization number generated by your system in
rmaNumber
.If you send
reason
, neither Digital River or the global logistics provider (GLP) use this value. But depending on how you build your integration, you may find it useful for customer service or record-keeping purposes.Digital River uses
orderId
and items[].itemId
to look up the relevant shipment and product details and then routes your return authorization request to the appropriate GLP. Upon receipt of this request, the GLP marks the return as pending, acknowledges the request and waits for the specified goods to arrive at their facility.The body of a successful
POST /logistics-returns
response contains a logistics return object whose type
is authorization
. This indicates the GLP has received your return authorization request.Logistics return
{
"id": "100000032201",
"createdTime": "2022-01-10T16:56:22Z",
"orderId": "1006970340082",
"rmaNumber": "e0e09e8e-9363-46ff-9baa-2485316e8b07",
"reason": "Damaged",
"type": "authorization",
"items": [
{
"itemId": "10366350082",
"quantity": 3,
"productDetails": {
"partNumber": "PN_physku1_1641832892693",
"name": "Physical SKU, fulfilled by DR",
"skuGroupId": "16f794d0-6143-45ed-8f14-c933f0983e7b",
"weight": 3.0,
"weightUnit": "oz",
"countryOfOrigin": "AU"
}
}
],
"returnTo": {
"address": {
"line1": "123 Airport Road",
"city": "Salt Lake City",
"postalCode": "84604",
"state": "Utah",
"country": "US"
},
"phone": "555-555-5555",
"organization": "DR Client 4",
"additionalAddressInfo": {}
},
"liveMode": false
}
Make sure you provide customers the full
returnTo
and instruct them to mail the products to that address.Customers are responsible for shipping the goods to the designated address. The GL solution currently doesn't support return ship label generation, supplying customers with pre-paid return ship labels, or carrier pickups from the customer's address.
When the goods arrive at the GLP's facility, their personnel use the included order identifier and RMA number to look up the pending return in their system. Their staff then inspect the products to verify their quality and quantity match the information in the returns authorization request.
If the returned goods don't arrive in the expected condition or their quantity is less than anticipated, the GLP, using a pre-arranged process, will contact your customer service team.
At this point, the GLP (1) sends an API call to Digital River that indicates the goods have been received and accepted and (2) processes the returned goods according to your disposition agreement.
Upon receiving this API call, Digital River creates an event whose
type
is logistics-return.received
and whose data.object
contains a type
of received
.Depending on your return and refund policies, as well as how you structure your workflow, you may decide to use this event to trigger a
POST /refunds
request.If a carrier attempts to deliver a package, but the recipient refuses delivery, then the goods are returned to a GLP facility within the destination country.
Customers sometimes refuse a delivery because they aren't expecting any packages. Alternatively, when a shipment's duty payment terms are delivered-at-place, customers may be unaware of the outstanding duties, fees, and import taxes.
At this point, the GLP (1) sends an API call to Digital River that indicates the goods have been refused by the customer and (2) processes the refused goods according to your disposition agreement.
Upon receiving this API call, Digital River creates an event whose
type
is logistics-return.received
and whose data.object
contains a type
of refused
. This event should trigger a POST /refunds
request.Sometimes packages are undeliverable. This is often due to an incorrect ship to address (e.g., the house or apartment number is inaccurate) on the shipping label. Less commonly, it's because the customer isn't present to sign for delivery or the designated address is a restricted institution (e.g., a prison or correctional facility) that requires advanced permission to enter.
In these scenarios, the carrier typically makes multiple delivery attempts. Additionally, the GLP supplies your customer service team with undelivered shipments reports which they can use to contact customers and attempt to correct the invalid address or obtain an alternative address.
However, if their attempts prove unsuccessful, inform the GLP so that the goods can be returned to their facility within the destination country. At that point, the GLP (1) sends an API call to Digital River that indicates the goods are undeliverable and (2) processes them according to your disposition agreement.
Upon receiving this API call, Digital River creates an event whose
type
is logistics-return.received
and whose data.object
contains a type
of undeliverable
. This event should trigger a POST /refunds
request.The response body of a
POST /logistics-return
and the data.object
of the event whose type
is logistics-return.received
share the same schema. The following is some of the key data in this object:For a complete schema definition, refer to logistics returns on the Digital River API reference site.
The
id
uniquely identifies the logistics return. You can send this value as a path parameter in a GET /logistics-returns/{id}
and as a query parameter in a GET /logistics-returns
request.The
rmaNumber
represents the return merchandise authorization number generated by your order management system. This field is only populated in customer-initiated returns.Each
itemId
references an items[]
in the order in Digital River's system. We also provide the productDetails
associated with that line item.Additionally, when the goods arrive back at the GLP's facility, their personnel inspect them and record their
condition
.The
reason
is collected from the customer during the return validation process. This field is only populated in customer-initiated returns.You can use
type
to determine both the category and status of a logistics return:authorization
: In customer-initiated returns, this value indicates the GLP has acknowledged yourPOST /logistics-returns
request and is awaiting the returned goods.received
: In customer-initiated returns, this value indicates that the goods have arrived at the GLP's facility and their personnel have inspected and approved the return.undeliverable
: In undeliverable return scenarios, this value indicates that, after repeated attempts, the carrier was unable to make delivery and the GLP has marked the shipment as undeliverable.refused
: In refusal return scenarios, this value indicates that the customer has rejected delivery of the goods and the GLP marked the shipment as refused.
Once
type
is received
, undeliverable
, or refused
, the GLP processes the returned goods according to your disposition agreementIn a logistics return object,
returnTo
contains the address where end customers must mail products. This is the same returnTo
in the shipping label response.Last modified 25d ago