Retrieve Shipping Label Rates (with DeliverByDateUtc)

When to Use & Considerations

This endpoint will retrieve shipping rates that satisfy the DeliverByDateUtc.
- Include ApplyDeliverByDate to use the DeliverByDateUtc from the order entity OR the DeliverByDateUtc included in the request.
Best Practice: retrieve DeliverByDateUtc from the Order Entity (it is not always populated on all orders from all channels), and send that value or the needed DeliverByDateUtc in this request.
See ShippingRate for all available parameters.
See Purchase a Shipping Label to purchase a specific rate returned from this endpoint.
On success, the response status will be 200 multipart/mixed; boundary=”boundary” (where "boundary" is a unique value per response)

A collection of shipping rates are returned as application/json in the first part of the body
If PurchaseCheapestRate is specified on the request, ChannelAdvisor will also purchase a label for the lowest shipping service and return the label data as an attachment.

Note: ShippingLabelRequestID ensures a label purchase request is not duplicated.

Workflows When ApplyDeliverByDate = true

Success Scenarios
- DeliverByDateUtc is not defined in the request AND the Order Entity has DeliverByDate defined, THEN the Order Entity DeliverByDate will be used.
- DeliverByDateUtc is defined in the request, THEN the supplied DeliverByDateUtc is used in the request.
Failure Scenario
- DeliverByDateUtc is not defined in the request AND the Order Entity has no DeliverByDateUtc defined, THEN the response will return HTTPS 400 status response.

Resource URL / Endpoint

POST https://api.channeladvisor.com/v1/Orders(OrderID)/ShippingRates

Important and/or Required Parameters.

Property	Format	Required	Note
DeliverByDateUtc	DateTime	Optional	Strictly optional, but best practice is to define this value should be included when using ApplyDeliverByDate.
ApplyDeliverByDate	boolean	Optional	Strictly optional, but when true, returns rates that meet the DeliverByDateUtc included in the request OR from the Order Entity.
WeightUnit	string	Required	Valid values are: Gram, Pound
Weight	decimal	Required	Total weight of the package
Items	Collection	Required	An array of ShippingItems
DistributionCenterID	integer	Conditionally	Required if no source address information is provided. Only used for address lookup and will not update fulfillment with the provided DistributionCenterID.
PackageID	integer	Conditionally	Required if package dimension is not provided
PurchaseCheapestRate	boolean	Optional	If specified, we will purchase the shipping service associated with the lowest cost
LabelFormat	enum	Optional	Valid values are: PDF, ZPL. The default value is PDF
ShippingLabelRequestID	string (50)	Recommended	Seller supplied unique identifier for the label purchase request. Supply this value in each request to ensure duplicate labels are not purchased. Note: once set, this value is applied on the Fulfillment and will not be returned in the response. If a future request is supplied with the same ID, the response will supply the existing label. See Purchase Shipping Label with Existing Request ID.

Example Request

POST https://api.channeladvisor.com/v1/Orders(12345678)/ShippingRates?access_token=xxxxxxxxxx
{
  "ApplyDeliverByDate": true,
  "DeliverByDateUtc": "2021-11-24T12:00:00Z",
  "MeasurementUnit": "Inch", 
  "Height": 10,
  "Width": 12,
  "Length": 12,
  "Weight": 1000,
  "WeightUnit": "Gram",
  "SourceFirstName": "ShipperFirstName",
  "SourceLastName": "ShipperLastName",
  "SourceAddressLine1": "100 Main Ave",
  "SourceCity": "Raleigh",
  "SourceStateOrProvince": "NC",
  "SourcePostalCode": "27615",
  "SourceCountryCode": "US",
  "SourcePhoneNumber": "919-555-1234",
  "DestinationFirstName": "BuyersFirstName",
  "DestinationLastName": "BuyersLastName",
  "DestinationAddressLine1": "3025 Carrington Mill Blvd",
  "DestinationCity": "Morrisville",
  "DestinationStateOrProvince": "NC",
  "DestinationPostalCode": "27560",
  "DestinationCountryCode": "US",
  "DestinationPhoneNumber": "919-555-1234",
  "Items": [
    {
      "Quantity": 1,
      "Sku": "MyTestSku"
    }
  ],
  "PurchaseCheapestRate": false,
  "ShippingLabelPartnerAccountIDs": [500],
  "LabelFormat": "ZPL",
  "ShippingLabelRequestID": "9bagr9lmodz83l4k9dkngksoq"
}

Example Response (Success)

200 OK

--ldffp37k2vseqd50bzep5z3svkdfl1mv
Content-Type: application/json

{
  "ShippingRates": [
    {
      "ShippingLabelPartnerAccountID": 500,
      "RateID": "19090424-201b-4ae4-91a0-a960592a9045",
      "ServiceName": "First Overnight",
      "ServiceCode": "FIRST_OVERNIGHT",
      "ServiceOfferID": null,
      "CarrierID": 2,
      "ClassID": 5,
      "TransitDays": "UNKNOWN",
      "DeliveryDate": "11/24/2020 8:00:00 AM",
      "Cost": 79.15,
      "WarningMessage": null
    },
    {
      "ShippingLabelPartnerAccountID": 500,
      "RateID": "3bc3b248-93db-4492-a0d5-fba4a09ed313",
      "ServiceName": "Priority Overnight",
      "ServiceCode": "PRIORITY_OVERNIGHT",
      "ServiceOfferID": null,
      "CarrierID": 2,
      "ClassID": 23,
      "TransitDays": "UNKNOWN",
      "DeliveryDate": "11/24/2020 10:30:00 AM",
      "Cost": 46.98,
      "WarningMessage": null
    }
  ],
  "Errors": [],
  "ExpiresInSeconds": 1800
}
--ldffp37k2vseqd50bzep5z3svkdfl1mv
Content-Disposition: attachment; filename=label.ZPL
Content-Type: application/text
  
^XA^CF,0,0,0^PR12^MD30^PW800^POI^CI13^LH0,20
^FO12,124^GB755,2,2^FS
^FO12,390^GB777,2,2^FS
^FO32,3^AdN,0,0^FWN^FH^FDFROM:^FS
^FO32,19^AdN,0,0^FWN^FH^FDAmazing Shoes^FS
^FO32,37^AdN,0,0^FWN^FH^FD^FS
^FO32,55^AdN,0,0^FWN^FH^FD123 Test^FS
^FO32,73^AdN,0,0^FWN^FH^FD^FS
^FO32,109^AdN,0,0^FWN^FH^FDUS ^FS
^FO224,3^AdN,0,0^FWN^FH^FD(919) 555-1234^FS
etc...

--ldffp37k2vseqd50bzep5z3svkdfl1mv--
Content-Type: application/json

{
  "ShippingLabelUrl": "https://api.channeladvisor.com/v1/Fulfillments(456789123)/Label",
  "FulfillmentID": 456789123,
  "Cost": 46.98,
  "CarrierID": 2,
  "ClassID": 23,
  "DeliveryDate": "11/24/2020",
  "TrackingNumber": "123456789",
  "LabelFormat": "ZPL"
}
--ldffp37k2vseqd50bzep5z3svkdfl1mv--

Example Response (No DeliverByDateUtc Available or Defined))

400 Bad Request

{
	"$id": "183",
	"Message": "DeliverByDateUtc is required when not available on the order."
}

Note: the id will vary and is not unique to this response message.