Rate Shop & Shipping Label Example Requests for Suppliers

Overview
Rate Shop API
Label API
- Using a rate from the Rate Shop API
Testing

Related Guides

Overview

This guide shows suppliers the request to send to the Rate Shop an Order and Create Shipping Labels APIs, and which fields to leave out. The Rate Shop API takes its defaults from the order itself, so a rate shop request needs very few fields.

Rate Shop API

The minimal request

Field	Send it?	Notes
`poNumber`	Always	The purchase order number of the order.
`carrierPickupDate`	Only if the pickup isn't today	`YYYY-MM-DD`. Today or later - see Testing.
`warehouseCode`	Only if you have several warehouses	The Code of the warehouse in Warehouse Manager. Not the warehouse name or Dsco ID. See Finding your warehouse code.
`signatureRequired`	Only if you need to override the order's signature requirement	When `true`, only ship methods that require a signature are rate shopped. Leave it out otherwise - if the order's ship method requires a signature, that is already taken into account.

Request body for POST /rateshop:

{
  "poNumber": "8327539",
  "carrierPickupDate": "2026-10-02",
  "warehouseCode": "WH01"
}

The response

[
  {
    "orderId": "1234567890",
    "poNumber": "8327539",
    "recommendedRate": {
      "carrier": "UPS",
      "name": "Ground",
      "serviceLevelCode": "UPSN_CG",
      "dscoServiceLevelCode": "UPCG",
      "estimatedArrivalDate": "2026-10-06T00:00:00.000Z",
      "warehouseCode": "WH01"
    }
  }
]

dscoServiceLevelCode is the Dsco ship code of the recommendation. serviceLevelCode is the same recommendation mapped to the retailer's own ship method values when the retailer has set up such a mapping; otherwise the two are identical.

To create the label for this rate, send dscoServiceLevelCode as carrierServiceLevel in the Label API, together with the recommended carrier. Sending serviceLevelCode (the retailer's own value) also works: the Label API converts it back to the Dsco ship code using the retailer's ship mapping. The Label API accepts only FedEx, UPS, USPS and Canada Post as carrier, so a recommendation from another carrier cannot be used for a label.

Optional override fields

In most cases, don't send these fields. Rate shop takes what it needs from the order and the retailer's rate shop configuration. Use them only for custom scenarios where you must override something that the order or the configuration doesn't specify.

Field	When to send it
`originalShipMethod`	Only to rate shop as if the order had a different ship method. If no rate shop configuration exists for the value sent, the same value is returned as the recommendation, leaving no useful rate.
`shipMethods`	Only to limit the candidates to a specific set of ship methods. Must be Dsco ship codes.
`promiseDate`	Only to override the order's expected or required delivery date. Never set it equal to `carrierPickupDate`: no delivery can arrive on the day it is picked up, so no method qualifies.

A 200 response does not always mean the order was rate shopped. When rate shopping is skipped or finds no rate, the API can return the order's original ship method as recommendedRate instead of an error. If your retailer sees a blank ship date and recommended method for your orders, check whether any of the fields above were sent.

Label API

To let Dsco pick the carrier and service level, set rateshop to true and leave out carrier and carrierServiceLevel entirely. Rate shopping runs as part of the label request - there is no need to call the Rate Shop API first.

Request body for POST /shippinglabels:

{
  "shipments": [
    {
      "partnerName": "Acme Retail",
      "poNumber": "8327539",
      "warehouseCode": "WH01",
      "rateshop": true,
      "shipDate": "2026-10-02T12:00:00Z",
      "labelFormats": "PDF",
      "packageType": "YOUR_PACKAGING",
      "packageDimensions": { "length": 12, "width": 8, "height": 4 },
      "packageWeight": 3
    }
  ]
}

partnerName, warehouseCode (the warehouse Code), labelFormats, packageType, packageWeight, and poNumber or suborderId are required. packageDimensions is also required when packageType is YOUR_PACKAGING.
Weights and dimensions are read as lb and in. To send kg or cm, add "carrierSpecs": { "weightUnits": "kg", "dimensionUnits": "cm" }.
Send signatureRequired only together with rateshop: true. A label request that sends it without rateshop: true is rejected. When true, rate shopping only considers ship methods that require a signature.
carrier and carrierServiceLevel must not be sent with rateshop: true, not even as empty strings.

The response contains the generated labelUrl, trackingNumber, and the carrier and carrierServiceLevel that rate shopping selected. See the Create Shipping Labels reference for the full response.

Using a rate from the Rate Shop API

If you already called the Rate Shop API, create the label with the recommended rate instead of rateshop: true. Send the recommended carrier, and the dscoServiceLevelCode as carrierServiceLevel:

{
  "shipments": [
    {
      "partnerName": "Acme Retail",
      "poNumber": "8327539",
      "warehouseCode": "WH01",
      "carrier": "UPS",
      "carrierServiceLevel": "UPCG",
      "shipDate": "2026-10-02T12:00:00Z",
      "labelFormats": "PDF",
      "packageType": "YOUR_PACKAGING",
      "packageDimensions": { "length": 12, "width": 8, "height": 4 },
      "packageWeight": 3
    }
  ]
}

UPCG is the dscoServiceLevelCode from the Rate Shop response. You can send the serviceLevelCode value UPSN_CG instead, exactly as the Rate Shop API returned it; the label is then created with UPCG. If the value is neither a Dsco ship code nor in the retailer's ship mapping, that shipment fails with The requested ship method is not a DSCO ship code and is not in the retailer ship mapping.

Testing

Test with current orders and a carrierPickupDate (or shipDate) of today or later. Do not test with old POs: rate shopping is skipped for completed orders, so the API returns an error with the message No recommended rate found even when the request is correct.

Questions can be sent to the Dsco platform support team at support-dsco@rithum.com.