Managing a Global Logistics order
Gain a better understanding of how to manage 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:
Overview
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.
Sending the ship request
Once the order's state
moves to accepted
, you should use its data to send a ship request to your 3PL.
At a minimum, this request must include the order's id
as well as the id
and quantity
of each of the order's physical items[]
.
You'll also likely want to pass the order's:
shipFrom
so that your 3PL knows which warehouse to route the request to.shipTo
so that your 3PL knows where the goods are going.The relevant
items[].productDetails
so that warehouse personnel know which products to pick and pack.
Managing shipping labels
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.
If necessary, Global Logistics also provides the capability to switch the fulfillment warehouse.
Defining and sending the shipping label request
In the POST /shipping-labels
request, your 3PL must send an orderId
, a labelFormat
, and items[]
nested in packages[]
.
Both shippingChoice
and shipFrom
are optional.
Order identifier
When defining the request, retrieve the order id
sent in the ship request and use it to set orderId
.
Order | Ship request | POST /shipping-labels | ||
---|---|---|---|---|
| ➔ | order identifier | ➔ |
|
Shipping choice and ship from
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
.
For details, refer to Switching the fulfillment warehouse.
Packaging and product data
The request must contain packages[]
and nested inside each element of this array must be one or more items[]
.
For each packages[]
:
The required
weight
should represent the scale weight of the package (with the goods and dunnage inside of it) at the warehouse. The enumeratedweightUnit
values areoz
,lb
,g
, andkg
.The optional, but highly recommended
height
,width
, andlength
should 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[]
:
The
itemId
is required. This represents the uniqueid
of one of the order's physicalitems[]
.
Order | Ship request | POST /shipping-labels | ||
---|---|---|---|---|
| ➔ | line item identifier | ➔ |
|
The
quantity
is required.
Label format
The labelFormat
represents the file format you want the shipping labels to be returned in. You can ask for labels in PDF
, PNG
, JPG
, GIF
, or ZPL
.
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.
To handle this, first submit a POST /shipping-quotes
and then, from the response, select a new quotes[]
.
Next, define a shipping label request by passing the selected quotes[]
data in shippingChoice
and shipFrom
.
If you don't use the quotes[].id
to define shippingChoice.id
, then the create shipping label request will fail.
Once the request is successfully submitted, Digital River uses these values to update the order's shippingChoice
and shipFrom
.
How your request gets processed
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.
When the GLP responds to our request for shipping labels, we log their reply and then pass a transformed response to your 3PL.
Successful shipping label response
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.
Unique identifier
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.
Order identifier
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.
Shipments
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
height
andwidth
. These are the label's dimensions. The values are denoted in inches.The
format
of the datafile
. The possible values arePDF
,PNG
,JPG
,GIF
orZPL
.
The value of format
might not always be the same as the labelFormat
specified in the request. This is because not all formats are supported by every GLP. As a result, make sure your application first checks the value of format
before attempting to print the label.
A
file
with binary base64 encoded data. In many cases,file
only contains an encoded label. Sometimes howeverfile
also 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
fileUrl
that 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.
Return to address
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.
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.
Failure responses
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:
Multi-package shipments not supported
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[]
.
Invalid orderId
orderId
If the request contains an invalid orderId
, then the following error is returned:
Invalid labelFormat
labelFormat
If the request contains an invalid labelFormat
, then the following error is returned:
Invalid items[].itemId
items[].itemId
If the request contains an invalid packages[].items[].itemId
, then the following error is returned:
Invalid shipFrom
shipFrom
If the request contains a shipFrom
that's not supported by your trading patterns, then the following error is returned:
Invalid weightUnit
weightUnit
If the request contains a weightUnit
that's not an enumerated value, then the following error is returned:
Handling the shipping label response
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[]
.
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.
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.
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.
Tracking order shipments
In this section, you'll find details on:
Sending the order tracking request
To track shipments, send an order's unique identifier as a path parameter in a GET /orders/{id}/tracking
.
This request is most commonly initiated when customers go to their order management page and select a specific order they want to track.
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:
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:
The order tracking response
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 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. 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
id
generated by Digital River.A
shipFrom
that represents the address of the warehouse where the products were picked and packed.One or more
items[]
, each that have anitemId
generated by Digital River, plusproductDetails
and a shippedquantity
.An overall
status
of 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 adescription
andstatus
of an event that occurred at a particularlocation
on a specificdate
. The date-time values are the local time at the specifiedlocation
.
array index | date | location | description |
---|---|---|---|
0 |
|
|
|
1 |
|
|
|
2 |
|
|
|
3 |
|
|
|
4 |
|
|
|
5 |
|
|
|
Handling the order tracking response
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.
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.
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.
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 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 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.
Last updated