Purchase Shipping Label with Existing Request ID

Background

  • This example illustrates a potential scenario for duplicate ShippingLabelRequestID.
  • This ensures a duplicate label is not requested.
  • There are two ways to purchase a shipping label:
    1. Using the PurchaseLabel endpoint, which purchases a label.
    2. Using the ShippingRates endpoint, which retrieves rates and has an optional property to purchase the lowest shipping rate available from the response.

Example Scenario for Application-Side Timeout

  1. Purchase a Shipping Label with "ShippingLabelRequestID": "12345"
    OR
    Retrieve Shipping Label Rates with "PurchaseCheapestRate": true and "ShippingLabelRequestID": "12345"
  2. Integration timeout occurs.
  3. ChannelAdvisor received initial request and will complete processing asynchronously.
  4. A second attempt with the same ShippingLabelRequestID is made to either one of these endpoints.
  5. For /v1/Orders(ID)/PurchaseLabel
    1. The previously purchased shipping label response and attachment is provided as the response (see example below).
  6. For /v1/Orders(ID)/ShippingRates
    1. An empty response for the Shipping Rates is provided with the purchased shipping label attached (see example below).

Purchase Label Request Example

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

Example Request with /v1/Order(ID)/PurchaseLabel 
POST https://api.channeladvisor.com/v1/Orders(12345678)/PurchaseLabel?access_token=xxxxxxxxxx
{
  "RateID": "7fd46c9dZPL-5f4d-494b-979e-3b20697d663c",
  "LabelFormat": "ZPL",
  "ShippingLabelRequestID": "12345"
}
Example Response for PurchaseLabel (Existing ShippingLabelRequestID) 
200 OK

--3rf31a2f51fd421087153db40cmn9op5
Content-Type: application/json
{
  "ShippingLabelUrl":"https://api.channeladvisor.com/v1/Fulfillments(87654321)/Label",
  "FulfillmentID":65432198,
  "Cost":12.21,
  "CarrierID":3,
  "ClassID":8,
  "DeliveryDate":"12/2/2020 8:00:00 PM",
  "TrackingNumber": "123456789",
  "LabelFormat": "ZPL"
}
--cbf31a2f51fd421087153db40ced6c2c
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...
  
--cbf31a2f51fd421087153db40ced6c2c--

Shipping Rates Request Example

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

Example Request 
POST https://api.channeladvisor.com/v1/Orders(12345678)/ShippingRates?access_token=xxxxxxxxxx
{
  "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": true,
  "ShippingLabelPartnerAccountIDs": [500],
  "LabelFormat": "ZPL",
  "ShippingLabelRequestID": "12345"
}
Example Response (Success) 
200 OK

--ldffp37k2vseqd50bzep5z3svkdfl1mv
Content-Type: application/json

{
  "ShippingRates": [],
  "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": "06/02/2020",
  "TrackingNumber": "123456789",
  "LabelFormat": "ZPL"
}
--ldffp37k2vseqd50bzep5z3svkdfl1mv--