Shipping Labels Integration Guide for Retailers & Suppliers

Transparency & Other Guides

This is a combined retailer/supplier guide intentionally so both parties transparently understand each other's integration requirements and responsibilities as success in e-commerce transactions is a two-party dance.

Overview

This guide explains how a partner, a retailer or supplier, would use Rithum's Dsco platform, and optionally Rithum's Dsco Platform API, to generate Shipping Labels to ship their orders.

Terms

Below are terms used throughout this guide.

Term Definition
Dsco platform support team The Dsco platform support team can be reached at support-dsco@rithum.com.

The Flow

A retailer places an order with a supplier, and the supplier acknowledged the order and is ready to ship. The supplier navigates to the shipment editor in Dsco and indicates they want to create a shipping label through the shipping label feature in Dsco rather than attach an existing tracking number to the shipment. The supplier is shown a form in which they provide missing details, among others the package dimensions, desired carrier and service level, and the warehouse they will ship the order from. Upon completing the form, the Dsco platform generates a shipping label using the credentials of the carrier account owned by either the retailer or supplier participating in the transaction and connected to Dsco as part of Shipping Labels onboarding. Upon successful generation of the shipping label, the order is reported as shipped and the supplier can download the shipping label and packing slip from the Dsco UI to print and attach to the package sent from their warehouse. The complete flow is as follows, and assumes both the retailer- and supplier accounts have onboarded to Dsco successfully and are ready for use.

  1. Retailer -> Supplier
    The retailer initiates a connection with the supplier to allow both parties to do business and provide goods to an end consumer.
  2. Supplier -> Dsco
    The supplier completes the connection onboarding process that involves setting up a warehouse and fulfilling test orders among others.
  3. Retailer -> Dsco
    The retailer verifies the supplier has completed all onboarding steps and activates the connection.
  4. Retailer -> Dsco
    The retailer authorizes the supplier to leverage Dsco's shipping label feature with the help of their Client Success Manager/Program Manager or the Dsco onboarding team.
  5. Retailer/Supplier -> Dsco
    Either the retailer or supplier connects their carrier account to the Dsco platform to ensure the shipping label request can be forwarded to the carrier on their behalf and they are billed the cost of the shipment by the carrier.
  6. Retailer -> Supplier
    The retailer creates an order to be fulfilled by the supplier.
  7. Supplier -> Dsco
    The supplier leverages the Dsco UI as described in this section's introduction to successfully generate a shipping label and ship the retailer's order.

(Optional) Dsco Platform API integration
Any retailer and supplier wishing to create stand-alone Shipping Labels can leverage the Shipping Labels part of the Dsco Platform API to do so. In this case, the supplier would not leverage the Dsco UI to generate a shipping label when needed, but steps (1) through (5) still need to be performed to authorize the supplier for Shipping Labels and ensure the shipping label request can be forwarded to the carrier on behalf of the retailer or supplier to whom the cost of the shipment by the carrier are billed.

Onboarding

As summarized in the previous section, there are onboarding steps both the retailer and supplier need to take to leverage Dsco's shipping label feature - these steps are documented in this section.

Dsco account setup and retailer/supplier connection

This documentation assumes that suppliers are already familiar with the process of setting up their Dsco account and establishing a connection between a retailer and supplier - this is a concern that the Dsco platform support team can assist in. Therefore, the steps (1) through (3) in the previous section are assumed to be familiar and are not covered in more depth.

Configuring the Shipping Labels feature

Configuring the Shipping Labels feature involves both the connected retailer and supplier and is done partly through the Dsco UI, and partly with the help of the Dsco platform support team.

[Retailer] Enabling the Delivery Solutions product

Not all retailers have the Delivery Solutions product enabled - the retailer can enable the product by working with their Client Success Manager or the Sales team.

[Retailer] Authorizing the connected supplier to use the Dsco Shipping Labels feature

Suppliers needs to be authorized by the retailer to generate Shipping Labels for an order placed by the retailer and fulfilled by the supplier. The retailer can collaborate with their Client Success Manager/Program Manager or the Dsco onboarding team to do so.

[Retailer/Supplier] Connecting the carrier account

Either the retailer or supplier needs to connect their carrier account to the Dsco platform to ensure the shipping label request can be forwarded to the carrier on their behalf and they are billed the cost of the shipment by the carrier.

This process of connecting the carrier account currently involves a manual step by the Dsco platform support team to generate a link that redirects to the carrier's website to authenticate with the carrier account that is to be used for generating Shipping Labels. Therefore, the party responsible for the connection is required to reach out and provide

The Dsco platform support team will respond to the support request with the onboarding link and any other instructions for the party to successfully connect their carrier account and take the next steps.

Identifying a shipment in an API request

Every shipment sent to the Create Shipping Labels API identifies three things, all using identifiers the supplier already works with. No Dsco system IDs are required.

What Field Where to find it
The trading partner that placed the order partnerName The retailer's name as shown in the Dsco UI. It must match exactly one retailer connected to your account.
The warehouse the order ships from warehouseCode The warehouse code you configured for the warehouse in the Dsco UI.
The order poNumber or suborderId The purchase order number the retailer sent you, or the Dsco order ID. Provide one of the two - a shipment that omits both is rejected with a 400.

The supplier itself is identified from the credentials used to authenticate the request, so no supplier identifier is sent in the payload.

The ship-from address

The return address printed on the label and ship-from address registered as origin are resolved from the warehouse identified by warehouseCode, so a ship-from address is never sent in the request. If a retailer has configured a return address override, the return address from the override is printed on the label instead of the warehouse address.

Features

The Shipping Labels feature available to Dsco platform users with access to the Delivery Suite product exposes the following functionality that can be customized to the needs of the retailer and supplier collaborating in the fulfillment of orders.

Return address override

The return address override is applied to all suppliers connected to a retailer if configured for the retailer. The override can be configured by specifying one or more parts of an address. The configured values are printed on any shipping label for any order fulfilled for the retailer, instead of the values otherwise retrieved from the warehouse address.

The return address override can be configured with the help of the Dsco platform support team.

Available carriers and service levels

Currently, the Shipping Labels feature allows customers to generate Shipping Labels for the carrier UPS and supports a subset of the ship methods offered by UPS.

The ship methods that are currently supported are listed in a Postman collection available for download below. Each request of the collection uses a different ship method - the collection can be used to get an idea of what valid request payloads look like for each supported ship method.

Available packaging types

Currently, the Shipping Labels feature allows customers to generate Shipping Labels for the carrier UPS and supports a subset of packaging types offered by UPS.

The packaging types that are currently supported are listed in a Postman collection available for download below. Each request of the collection uses a different packaging type - the collection can be used to get an idea of what valid request payloads look like for each supported packaging type.

Fine-grained carrier account credentials

As mentioned here, the Shipping Labels feature supports the association of carrier account credentials to retailers, suppliers, and also supplier's warehouses. This fine-grained control of which carrier account is used when a shipping label is created gives customers lots of flexibility to manage how the cost of the shipment by the carrier is billed.

The Dsco platform support team can advise customers how to best connect their carrier accounts while onboarding to the Shipping Labels feature depending on their billing strategy.

Rate Shopping (Automatic Carrier Selection)

The Shipping Labels API now supports automatic carrier and service level selection through the Rate Shopping feature. When enabled, the system automatically selects the optimal carrier and service level based on factors such as cost, delivery time, and carrier availability.

How to Use Rate Shopping

To use the Rate Shopping feature in your API requests:

  1. Set the rateshop field to true in your shipping label request
  2. Omit the carrier and carrierServiceLevel fields (sending either as an empty string is rejected)
  3. (Optional) Indicate signature requirements using the signatureRequired field
  4. The system will execute the Rate Shop operation and use the recommended rate to create the shipping label.

Creating shipping labels in batches

A supplier with many orders to ship does not have to create labels one order at a time. The Create Shipping Labels Small Batch API accepts up to five megabytes of orders in a single call and creates the labels asynchronously. The results are collected afterwards from the Get Shipping Label Change Log API, which returns one entry per submitted order and reports whether the batch has finished.

Grouping shipments by order

The batch API groups shipments by order, naming the order and the trading partner once:

{
  "orders": [
    {
      "poNumber": "PO-2026-0001",
      "partnerName": "Acme Retail",
      "shipments": [
        { "warehouseCode": "WH01", "...": "..." },
        { "warehouseCode": "WH02", "...": "..." }
      ]
    }
  ]
}
What Where Field
The order On the order poNumber or suborderId
The trading partner On the order partnerName or retailerId
The warehouse On each shipment warehouseCode

Every row requires an identifier. The trading partner named on the order is applied to every shipment beneath it. The warehouse stays on the shipment, because the shipments of one order may ship from different warehouses, and the ship-from address is resolved from it exactly as described in Identifying a shipment in an API request.

The supplier is never sent in the payload. It is resolved from the credentials used to authenticate the request, so a supplier can only create labels against its own warehouses. A shipment that carries a supplierId is rejected.

Rate shopping is requested per shipment with the rateshop field, the same way it is for a single request.

The submit-then-poll exchange

  1. Supplier -> Dsco
    The supplier submits the orders and their shipments to Create Shipping Labels Small Batch.
  2. Dsco -> Supplier
    The API responds immediately with an HTTP 202 and a requestId. The response confirms only that the batch was accepted - no label has been created yet.
  3. Supplier -> Dsco
    The supplier passes that requestId to the Get Shipping Label Change Log API to retrieve one entry per order. While the batch is still being processed the response carries a status of PROCESSING; once every order has reached a result it carries COMPLETED.
  4. Supplier
    For each entry, requestMethodDetail holds one result per shipment of that order, reporting the tracking number, the carrier and service level used, the shipment cost, and - where label creation failed - a message explaining why. An order is only reported as success when a label was created for every one of its shipments.

Retrieving the labels

Unlike the synchronous API, the change log does not return a label URL for each shipment. To retrieve the label files for a batch, request the merge transformation when submitting it:

{
  "orders": [ "..." ],
  "transformations": { "operations": ["merge"] }
}

The labels generated for every shipment in the batch are then combined into a single PDF. Once the batch reaches a status of COMPLETED, the change log response carries a metadata.mergedLabelUrl attribute pointing at that PDF. The URL expires one hour after it is issued - call the change log API again to obtain a fresh one.

© 2024 Rithum Holdings, Inc., together with its subsidiaries, all rights reserved, protected under U.S. and international copyright law. Rithum and the Rithum logo are trademarks of Rithum, LLC