Rate Shop Integration Guide for Retailers & Suppliers

• Overview
• Terms
• The Flow
• Integrating the Dsco Platform API to rate shop orders
• Rate shopping orders in batches
  • Change log retention

Overview

This guide explains how a supplier would use Rithum's Dsco platform and Rithum's Dsco Platform API to rate shop their orders.

Terms

Below are terms used throughout this guide.

The Flow

A retailer places an order with a supplier, and the supplier acknowledged the order and is ready to ship. The supplier has prepared the order in their warehouse and is ready to ship, ideally with the most cost-efficient ship method that guarantees the order is delivered on time. The supplier makes a Dsco Platform API call to obtain a recommended ship method, providing various optional parameters such as ship methods, warehouse location, and delivery requirements, along with the Dsco order ID. The Rate Shop request yields the recommended ship method, which the supplier can then pass into another Dsco Platform API call to obtain a shipping label (documented in the Shipping Labels Guide). The shipping label request yields a tracking number, which the supplier can then pass into another Dsco Platform API call to create a shipment. Upon doing so, 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 rate shop and shipping label features 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 Platform API as described in this section's introduction to successfully rate shop an order, generate a shipping label, and ship the retailer's order.

Integrating the Dsco Platform API to rate shop orders

Multiple variants of valid Rate Shop requests to the Dsco Platform API can be found in a Postman collection available for download below.

• Click here to download the Postman collection to get started.
• Click here to download a template of the Postman environment to configure the collection for use.

Rate shopping orders in batches

A supplier with many orders to ship does not have to rate shop them one at a time. The Rate Shop Small Batch API accepts up to five megabytes of orders in a single call and rate shops them asynchronously. The results are collected afterwards from the Get Rate Shop Change Log API, which returns one entry per submitted order and reports whether the batch has finished.

Integrating against the batch API is a submit-then-poll exchange.

1. Supplier -> Dsco
   The supplier submits the orders to Rate Shop Small Batch. Each order identifies itself with either its Dsco order ID (orderId) or its purchase order number (poNumber), and may carry the same optional parameters as a single rate shop request. An order that provides neither identifier is rejected.
2. Dsco -> Supplier
   The API responds immediately with an HTTP 202 and a requestId. The response confirms only that the batch was accepted - no rate has been shopped yet.
3. Supplier -> Dsco
   The supplier passes that requestId to the Get Rate Shop 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 the recommended ship method when the order was rate shopped successfully, or a message explaining why no rate could be found. The recommended ship method is then used to obtain a shipping label exactly as it would be for a single rate shop request.

Change log retention

Change logs are meant to give feedback on asynchronous batch calls shortly after they are made, and are kept for two weeks by default. A batch should be polled within minutes - or at most hours - of submitting it.