Create a test accountSign in to DashboardSystem status
Search…
⌃K
Links

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:

Overview

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.

Sending the ship request

Once the order's state is accepted, you should use its data to send a ship request that gets routed to one of your 3PL's warehouses.
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.

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 label, ships the products, and notifies you of the shipment. In most integrations, this notification triggers a payment capture request.
For details, 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

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
}
]
}'

Order identifier

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."
}
]
}

Shipping choice

In the request, shippingChoice is optional because the order already contains a shippingChoice. If shippingChoice is not passed in the label request then, by default, the order's shippingChoice is encoded in the shipping label's data file.

Ship from

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."
}
]
}

Product data

For each items[] in a shipping label request, your 3PL:
  • Must include the product quantity being shipped.
  • Must include itemId. This represents the unique id of each of the order's physical items[].
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.

Packaging data

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.

Label format

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.

Switching the fulfillment warehouse

After the order is created, you might occasionally need to change its shipFrom. This typically happens when a 3PL notifies you, after order submission, that the products are out-of-stock at the originally designated warehouse.
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.

How Digital River handles the ship label request

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.

How the GLP handles the ship label request

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.

How Digital River handles the response

When the GLP responds to our request for shipping labels, we log their reply and then pass the shipping label response to your 3PL.

The shipping label response

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
}

Unique identifier

The response contains a unique id. This value is generated by Digital River.

Order identifier

The orderId identifies the order in Digital River's system.

Shipping labels

In the response, we return labels[]. Each element of this array contains:
  • A height and width. These are the shipping label's dimensions. The values are denoted in inches.
  • The format of the shipping label's data file. This is an enumerated file format. Currently, the only returned value is PDF.
  • 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. Sometimes file 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.

Return to address

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.
The same returnTo is also contained in the logistics return object.
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.

Handling the shipping label response

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.

How the goods move to the end customer

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.

Tracking order shipments

In this section, you'll find details on:

When tracking information becomes available

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."
}
]
}

Sending the order tracking request

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.

The order tracking response

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
}

Order identifier

The response contains a single orderId that identifies the order in Digital River's system.

Ship to

In shipTo, you're given the final delivery address of the order's products, along with details on the buyer.

Shipments

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 of items[] contains productDetails and a shipped quantity. Regardless of how you send product data in checkouts, the productDetails object is returned in the order tracking response. We also return an itemId that identifies each of an order's items[] that have shipped.
  • A shipment status: The status of a shipment can be pending_shipment, in_transit, delivery_attempted, delivered, refused, cancelled, awaiting_shipment, and contact_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's status 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 a description of an event that occurred at a particular location on a specific date. The date-time values are the local time at the specified location.
    array index
    date
    location
    description
    0
    2021-08-13T15:20:00Z
    -
    Order Data Created/Received
    1
    2021-08-13T15:21:00Z
    Salt Lake City Utah US
    Shipping Label Generated
    2
    2021-08-13T20:36:00Z
    Salt Lake City Utah US
    Customs status updated
    3
    2021-08-16T08:15:00Z
    LOS ANGELES GATEWAY,CA-USA
    Arrived at Sort Facility LOS ANGELES GATEWAY,CA-USA
    4
    2021-08-19T03:32:00Z
    BRUSSELS-BEL
    Transferred through BRUSSELS-BEL
    5
    2021-08-20T14:06:00Z
    POINTE NOIRE-COG
    Clearance processing complete at POINTE NOIRE-COG

Handling the order tracking response

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.

Processing reversals

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.

Customer-initiated returns

The following describes how to process customer-initiated returns that stem from damaged goods, faulty products, a 'change-of-heart' and other similar scenarios.

Defining and sending a logistics returns request

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
}
]
}'
The request must include orderId. This value identifies the order in Digital River's system.
For each product being returned, you also need to send an items[].itemId that identifies the items[] in the order, plus the quantity being returned.
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.

How your request is handled

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 logistics return response

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
}

Handling the logistics return response

Upon receiving a 201 Created status code, provide customers with the orderId and rmaNumber and tell them to either write these identifiers directly on the returns package or include them on the shipping documentation inside the package.
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.

Handling the return received event

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.

Delivery refusals

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.

Undeliverable packages

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 logistics returns object

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.

Logistics return identifier

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.

Order identifier

The orderId references the order in Digital River's system.

RMA number

The rmaNumber represents the return merchandise authorization number generated by your order management system. This field is only populated in customer-initiated returns.

Product information

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.

Reason

The reason is collected from the customer during the return validation process. This field is only populated in customer-initiated returns.

Type

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 your POST /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 agreement​

Return to

In a logistics return object, returnTo contains the address where end customers must mail products. This is the same returnTo in the shipping label response.
Previous
Digital River signature
Next - Order management
Subscription management
Last modified 25d ago