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 details about each stage, refer to:
After the order's
state moves to accepted, you must send a ship request to your third-party logistics (3PL) provider so that the goods can be picked and packed at the appropriate warehouse. When ready to ship, your 3PL needs to send a label request to Digital River, which we route to the appropriate global logistics provider (GLP).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.
shipFromso that your 3PL knows which warehouse to route the request to.shipToso that your 3PL knows where the goods are going.- The relevant
items[].productDetailsso that warehouse personnel know which products to pick and pack.
Once the goods are picked and packed, and a ship label needs to be printed, your 3PL needs to define and send a shipping label request and then be setup to handle the successful response as well as potential errors.
In the
POST /shipping-labels request, your 3PL must send an orderId, a labelFormat, and items[] nested in packages[].When defining the request, retrieve the order
id sent in the ship request and use it to set orderId.Order | Text | Ship request | Text | POST /shipping-labels |
|---|---|---|---|---|
id | ➔ | order identifier | ➔ | orderId |
The request's
shippingChoice and shipFrom are optional because the order already contains this data. If these parameters are not defined, then, by default, the order's shippingChoice and shipFrom are encoded in the shipping label's data file.The request must contain
packages[] and nested inside each element of this array must be one or more items[]. For each
packages[]:- The required
weightshould represent the scale weight of the package (with the goods and dunnage inside of it) at the warehouse. The enumeratedweightUnitvalues areoz,lb,g, andkg. - The optional, but highly recommended
height,width, andlengthshould represent the actual dimensions of the package in inches.
It's important that a package's weight and dimensions be as accurate as possible. These values are used by carriers to determine a shipment's actual costs.
For each
items[] in that packages[] :Order | Text | Ship request | Text | POST /shipping-labels |
|---|---|---|---|---|
items[].id | ➔ | line item identifier | ➔ | items[].itemId |
- The
quantityis required.
The
labelFormat represents the file format you want the shipping labels to be returned in. You can ask for labels in PDF, PNG, JPG, or ZPL.To handle this scenario, 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 quotes[].When defining the shipping label request, use that selected quote's data to set
shippingChoice and shipFrom. Digital River then uses these values to update the order's shippingChoice and shipFrom.When Global Logistics receives a shipping label request, we retrieve
orderId from the payload and use it to look up the order in our system. We use
items[].id to get data on the products going out in that shipment. This includes the product's name, declared value, tariff code, country of origin, and weight. If the product contains a part number, url, image, signature requirements and dangerous goods classifications, we pass that data as well. We then route a transformed request to the appropriate GLP who determines where the shipment is going and generates one or more labels that point the products to either the address of the end customer or the address of an in-country hub. The GLP also determines whether the products have any handling and/or signature requirements, and, if they do, adds them to the label's data.
A label request also prompts the GLP to prepare a shipment's customs documentation and then package it in a digital pre-clearance request that they typically send to an importation country's customs agency.
A successful response provides your 3PL the data it needs to print one or more shipping labels. The response might also contain supplemental customs documentation.
At this point, order tracking data typically becomes available. For details, refer to Tracking order shipments.
The response contains a unique
id whose value is generated by Digital River. You can pass this value as a query parameter in a list shipping labels request or a path parameter in a get unique shipping label request. The
orderId identifies the order in Digital River's system. You can pass this value as a query parameter in a list shipping labels request.The response contains one or more
shipments[]. Each shipment has a unique id plus one or more labels[] and packages[].Each shipping
labels[] contains:- A
heightandwidth. These are the label's dimensions. The values are denoted in inches. - The
formatof the label's datafile. The possible values arePDF,PNG,JPG, orZPL. - A
filewith binary base64 encoded data. In many cases,fileonly contains an encoded label. Sometimes howeverfilealso holds additional documentation, such as a 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 the hub and spoke logistics model, each label's
file encodes the address of one of the GLP's in-country hubs. In the hubless logistics model, this file encodes the end customer's ship to address.- In some cases, there's a
fileUrlthat provides the web address of a decoded label.
Each
packages[] in the response maps to one of the packages[] sent by the 3PL in the request.The
returnTo contains the product return address assigned by the GLP. After a returns request is approved, you should instruct customers to mail the products they're sending back 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.If you fail to define parameters marked as required in the shipping label request specifications, you'll receive an error. In addition, the following are other common reasons the request might fail:
If the 3PL sends a
POST /shipping-labels that contains multiple packages[], and the GLP that Global Logistics routes the request to determines that the shipment is assigned to a carrier that doesn't support multi-package shipments, then the GLP returns an error to GL. If you instructed a Digital River representative to deactivate the auto-split feature, GL passes this error back to the 3PL. To handle it, the 3PL could split the failed request into multiple
POST/ shipping-labels, each with a single packages[]. Alternatively, 3PL personnel could repackage all the goods into a single, larger box and send one POST /shipping-labels with one packages[].409 Conflict
{
"type": "conflict",
"errors": [
{
"code": "invalid_parameter",
"parameter": "request.shippingChoice.id",
"message": "Multiple package shipments are not supported by the selected shipping choice."
}
]
}
If the request contains 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."
}
]
}
If the request contains an invalid
labelFormat, then the following error is returned:409 Conflict
{
"type": "conflict",
"errors": [
{
"code": "invalid_parameter",
"message": "The label format is invalid."
}
]
}
If the request contains an invalid
packages[].items[].itemId, then the following error is returned:400 Bad Request
{
"type": "bad_request",
"errors": [
{
"code": "invalid_parameter",
"message": "The original order items is required."
}
]
}
If the request contains 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."
}
]
}
If the request contains a
weightUnit that's not an enumerated value, then the following error is returned:400 Bad Request
{
"type": "bad_request",
"errors": [
{
"code": "invalid_parameter",
"parameter": "packages[0].weightUnit",
"message": "'lbs' is not a valid item type."
}
]
}
For each
shipments[], the 3PL needs to iterate through each labels[], decode its base64 data file, and then write the binary out to the designated format. The 3PL can then open the file, configure the label's dimensions using height and width, print the label and affix it to one of the shipment's packages[].If a
shipments[] contains multiple labels[], then it doesn't matter which gets affixed to each packages[]. A label's file doesn't contain any product data which means that no one-to-one association exists between a shipment label and a shipment package. When a
labels[].file contains additional documentation, such as the commercial invoice, the 3PL must also print this paperwork and secure it to that shipment's packages[].Shipping label
Customs documentation
Alternatively, if
labels[] contains a fileUrl, the 3PL can access the label resource at that address, print it and affix it to a packages[].Once the goods ship, your 3PL typically sends a 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.
If customers selected a quote with DAP shipping terms during the checkout process, then the recipient is required to pay the unpaid balance at the time of delivery. On the other hand, in shipments whose terms are DDP, the GLP pays the duties, fees, and import taxes assessed by a country's custom agency.
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.
In this section, you'll find details on:
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' \
...
This request is most commonly initiated when customers go to their order management page and select a specific order they want to track.
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 a shipment's tracking information. In this case, 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."
}
]
}
In the order tracking response, you'll find real-time data on the
items[] in each shipments[] 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. We return an array because an order's goods are sometimes sent out for delivery in multiple batches.Each element in
shipments[] contains:- A unique
idgenerated by Digital River. - A
shipFromthat represents the address of the warehouse where the products were picked and packed. - One or more
items[], each that have anitemIdgenerated by Digital River, plusproductDetailsand a shippedquantity. - An overall
statusof that particular shipment.
Each GLP maintains its own unique shipment statuses that Digital River normalizes to one of our
status values . - Various
trackingDetails[]that provide you adescriptionandstatusof an event that occurred at a particularlocationon a specificdate. The date-time values are the local time at the specifiedlocation.
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 |
For each
shipments[], you can use its items[] to display product details, status to inform customers about a shipment's overall progress, and trackingDetails[] to give them a description and status of an event that occurred at a particular location on a specific date.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-returnsrequest 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 5mo ago