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.

OrderShip requestPOST /shipping-labels

id

order identifier

orderId

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 enumerated weightUnit values are oz, lb, g, and kg.

  • The optional, but highly recommended height, width, and length 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 unique id of one of the order's physical items[].

OrderShip requestPOST /shipping-labels

items[].id

line item identifier

items[].itemId

  • 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 and width. These are the label's dimensions. The values are denoted in inches.

  • The format of the data file. The possible values are PDF, PNG,JPG, GIF or ZPL.

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 however file 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[].

409 Conflict
{
    "type": "conflict",
    "errors": [
        {
            "code": "invalid_parameter",
            "parameter": "request.shippingChoice.id",
            "message": "Multiple package shipments are not supported by the selected shipping choice."
        }
    ]
}

Invalid orderId

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

Invalid labelFormat

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

Invalid items[].itemId

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

Invalid shipFrom

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

Invalid weightUnit

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

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.

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.

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

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 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": "jchou@digitalriver.com",
        "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. 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 an itemId generated by Digital River, plus productDetails and a shipped quantity.

  • 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 a description and status 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 indexdatelocationdescription

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 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.

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.

Last updated