4D Shipping - Getting Started with Canada Post

Materials:

Contents

Introduction

To work with Canada Post use the CanadaPost components. When working with Canada Post both a shipping and a developer account are required. Please follow the directions from Canada Post at the link below to acquire these.

Once an account has been acquired any of the CanadaPost components can be set to use it like this example:

Canadapostship ship = new Canadapostship(); ship.CanadaPostAccount.UserId = "YourUserId"; ship.CanadaPostAccount.Password = "YourPassword"; ship.CanadaPostAccount.AccountNumber = "YourAccountNumber"; //ship.CanadaPostAccount.ContractId = "YourContractId";

The UserId property will take a developer API key. The AccountNumber and Password properties will take a shipper’s account number and password, respectively. If the shipper is a contract shipper then the ContractId property will take that Id as well, otherwise leave it empty.

Canada Post provides both a production and testing environment. Two different API keys are used to access two different servers. The API keys are provided by Canada Post directly. URL’s for production and staging are:

Rating Packages

One of the first steps when shipping a package is finding out how much it will cost. This is called “rating” and can be done with the CanadaPostRates component. The more information provided about a potential shipment will return a more accurate estimate of the final price. If RequestedService is unspecified then a selection of available services will be returned in the Services collection. Information about each service, including their estimated price and delivery date, will be available. Here is an example rating a small package between Toronto and Ottawa:

Canadapostrates rates = new Canadapostrates(); rates.CanadaPostAccount.Server = "https://ct.soa-gw.canadapost.ca"; rates.CanadaPostAccount.UserId = "YourUserId"; rates.CanadaPostAccount.Password = "YourPassword"; rates.CanadaPostAccount.AccountNumber = "YourAccountNumber"; rates.SenderAddress.PostalCode = "M5S1W7"; rates.RecipientAddress.PostalCode = "K1P5A4"; rates.Packages.Add(new PackageDetail()); rates.Packages[0].Weight = "1.1"; rates.Packages[0].PackagingType = TPackagingTypes.ptYourPackaging; //rates.RequestedService = ServiceTypes.stCanadaPriority; try { rates.GetRates(); for (int x = 0; x < rates.Services.Count; x++) { Debug.WriteLine("\r\n---Service #" + x + "---\r\n" + rates.Services[x].ServiceTypeDescription + "\r\n" + "Cost: " + rates.Services[x].AccountNetCharge + "\r\n" + "Delivery Date: " + rates.Services[x].DeliveryDate); } } catch (Exception ex) { Debug.WriteLine(ex.Message); }

If the service type is already known it can be specified with RequestedService. The server will return information about that specific service.

Generating a Label

After getting an estimated rate for shipping a package a label will need to be generated and affixed to the packaging. Domestically shipped packages (those shipped only within the borders of the Canada) will have their labels generated with the Canadapostship component while all others will use the Canadapostshipintl component.

To create a label Canada Post will need to know some information about how the package should be shipped, including:

  • Who is sending the package.
  • Who is receiving the package.
  • What service will be used.
  • Basic package information like weight and packaging type.

All of this information can be set with properties and/or configuration settings. Here is an example:

Canadapostship ship = new Canadapostship(); ship.CanadaPostAccount.Server = "https://ct.soa-gw.canadapost.ca"; ship.CanadaPostAccount.UserId = "YourUserId"; ship.CanadaPostAccount.Password = "YourPassword"; ship.CanadaPostAccount.AccountNumber = "YourAccountNumber"; ship.ServiceType = ServiceTypes.stCanadaPriority; ship.Packages.Add(new PackageDetail()); ship.Packages[0].Weight = "1.1"; ship.Packages[0].PackagingType = TPackagingTypes.ptYourPackaging; ship.Packages[0].ShippingLabelFile = @"C:\temp\canadapost\label.pdf"; ship.SenderContact.Company = "The National War Memorial"; ship.SenderContact.Phone = "(866) 522-2122"; ship.SenderAddress.Address1 = "Wellington St"; ship.SenderAddress.City = "Ottawa"; ship.SenderAddress.Province = "ON"; ship.SenderAddress.PostalCode = "K1P5A4"; ship.RecipientContact.Company = "Royal Ontario Musuem"; ship.RecipientContact.Phone = "(416) 586-8000"; ship.RecipientAddress.Address1 = "100 Queens Park"; ship.RecipientAddress.City = "Toronto"; ship.RecipientAddress.Province = "ON"; ship.RecipientAddress.PostalCode = "M5S2C6"; try { ship.GetPackageLabel(0); Console.WriteLine("This package can be tracked with this number: " + ship.Packages[0].TrackingNumber); } catch (Exception ex) { Console.WriteLine(ex.Message); }

If the call is successful then a label will be returned and saved to the location specified with ShippingLabelFile. Alternatively the label data can be worked with by querying the ShippingLabel property. A tracking number will also be returned and is available in the TrackingNumber property.

Sending Packages

Once a label has been affixed a package can be dropped off at a CanadaPost location. To find a CanadaPost location use the CanadaPostAddress component. Here is an example:

Canadapostaddress addr = new Canadapostaddress(); addr.CanadaPostAccount.Server = "https://ct.soa-gw.canadapost.ca"; //development server addr.CanadaPostAccount.UserId = "UserId"; addr.CanadaPostAccount.Password = "Password"; addr.CanadaPostAccount.AccountNumber = "AccountNumber"; addr.Address.Address1 = "28 Distillery Lane"; addr.Address.City = "Toronto"; addr.Address.Province = "ON"; addr.Address.PostalCode = "M5A3C4"; addr.MaxResults = 5; try { addr.FindLocations(); Console.WriteLine("Available Locations for Dropoff are...\r\n"); for (int x = 0; x < addr.Locations.Count; x++) { CanadaPostLocationDetail location = addr.Locations[x]; Console.WriteLine(location.Name + " (" + location.Distance + "km)\r\n" + location.StreetAddress + "\r\n" + location.City + ", " + location.Province + ", " + location.PostalCode + "\r\n"); } } catch (Exception ex) { Console.WriteLine(ex.Message); }

An address is provided with the Address property, after which FindLocations is called. This a list of Canada Post locations sorted by distance to the specified address. The number of results that comes back can be limited by setting MaxResults. Any returned locations can be accessed using the Locations collection. Information about returned locations includes the location’s address as well as the distance between the location and the specified address.

Tracking Packages

Once a package is entered into CanadaPost’s systems it can be tracked with the Canadaposttrack component. Tracking is fairly simple, just call the TrackShipment method and pass in a tracking number (a.k.a. PIN or Parcel Identification Number). When the response comes back from the server the method will return and any tracking events will be contained in the TrackEvents collections. Here is an example:

Canadaposttrack track = new Canadaposttrack(); track.CanadaPostAccount.Server = "https://ct.soa-gw.canadapost.ca"; //development server track.CanadaPostAccount.UserId = "UserId"; track.CanadaPostAccount.Password = "Password"; track.CanadaPostAccount.AccountNumber = "AccountNumber"; try { //track.IdentifierType = CanadaposttrackIdentifierTypes.itDNC; track.TrackShipment("7023210039414604"); for (int x = 0; x < track.TrackEvents.Count; x++) { CanadaPostTrackDetail trkEvent = track.TrackEvents[x]; Console.WriteLine("This package " + trkEvent.Description + " at " + trkEvent.City + " on " + trkEvent.Date); } }

Other identifiers can be used to track a package like a reference number or a Delivery Notice Card (DNC) number. To use another identifier set IdentifierType to the appropriate value.

Shipping packages can be complicated, but we sincerely hope that 4D Shipping makes it significantly easier for you. There is more to be discovered when working with this product, like international shipping, but hopefully this is plenty to get started with. If you need any assistance while working with 4D Shipping please check out the support options below.

Getting Support

If you are stuck with 4D Shipping there are options for help. Please have a look through the Knowledge Base and Documentation first, as often many common questions can be answered there. If you are still having trouble, please contact our support team and they would be happy to help you.

We appreciate your feedback. If you have any questions, comments, or suggestions about this article please contact our support team at support@4dpayments.com.