This class loosely follows the API available from CanadaPost. See their documentation for more information.
The Canada API returns XML elements that are dash-separated. These are converted to lowerCamelCase Javascript objects, and vice-versa when calling a method.
This means that instead of providing a property like show-packing-instructions
, you may provide showPackingInstructions
,
and it will be converted before being sent with the request.
Result objects are somewhat normalized, to reduce the amount of unncessary XML information/structure that is generated.
All Candada Post API methods return a promise. Old-style callbacks are not supported.
- CanadaPostClient
The main class for working with the Canada Post API
Creates a new instance of the CanadaPostClient class, that will authenticate requests with the provided username and password.
Arguments:
userId
(String) - Your usernamepassword
(String) - Your passwordcustomer
(String) [optional] - Your customer ID. This will be used by default for requests, if one is required in the path.lang
(String) [optional] - The language of the responses. Should be one of en-CA, or fr-CA.useTestEndpoint
(Boolean) [optional] - Whether to force the use of the "test endpoint" for development purposes. Iftrue
the test endpoint will be used. Iffalse
the live endpoint will be used. If omitted, NODE_ENV will be checked. If NODE_ENV is set to "production", the live endpoint will be used, otherwise the test endpoint will be used.
Example:
const cpClient = new CanadaPostClient('b4c32...', 'c0009a...');
let result = cpClient.discoverServices('P0ST4L','US');
Returns: CanadaPostClient instance
Discovers available services for creating a shipment between the origin postal code, and destination.
Arguments:
originPostalCode
(String) - The origin postal code, within Canada, that the item is being shipped fromdestinationCountry
(String) - The ISO2 country code the package is being shipped todestinationPostalCode
(String) [optional] - If the destination is within Canada, provide the destination postal code for more accurate results.
Returns: Promise
Resolves: Array
- An array of services codes for shipping from the origin to the destination
Gets the rates for a given mailing scenario.
Arguments:
scenario
(Object) - An object that represents the mailing scenario. See this page for info. Common fields include the following:parcelCharacteristics
(Object) - An object that describes the parcelweight
(Number) - The weight of the parcel in kilogramsdimensions
(Object) - The dimensions of the parcel.length
(Number) - Longest dimension in centimeters, to one decimal pointwidth
(Number) - Second longest dimension in centimeters, to one decimal pointheight
(Number) - Shortest dimension in centimeters, to one decimal point
originPostalCode
(String) - The origin postal code, within Canada, that the item is being shipped fromdestination
(Object) - The destination address, with only one of the following child attributesdomestic
(Object) - For Canadian shipmentspostalCode
(String) - The destination postal code
unitedStates
(Object) - For US shipmentszipCode
(String) - The destination ZIP code
international
(Object) - For other, worldwide destinationscountryCode
(String) - The ISO 3166-1 alpha-2 country code (e.g. GB, MX). See the International Shipping Chart
Returns: Promise
Resolves: Array
- An array of available services and their prices for shipping from the origin postal code to the destination
Creates a non-contract shipment
Arguments:
shipment
(Object) - An object that represents the shipment. See this page for info. Common fields include the following:requestedShippingPoint
(String) - The origin postal code from where the parcel will be shipped.deliverySpec
(Object) - The specifications of the deliveryserviceCode
(String) - The code to use (e.g. DOM.EP, USA.XP)sender
(Object) - The sender's address informationname
(String)company
(String)contactPhone
(String)addressDetails
(Object)addressLine1
(String)addressLine2
(String)city
(String)provState
(String)postalZipCode
(String)
destination
(Object) - The recipient's address informationname
(String)company
(String)clientVoiceNumber
(String) - Recipient's phone number (required for international shipments)addressDetails
(Object)addressLine1
(String)addressLine2
(String)city
(String)provState
(String)postalZipCode
(String)countryCode
(String)
parcelCharacteristics
(Object) - An object that describes the parcelweight
(Number) - The weight of the parcel in kilogramsdimensions
(Object) - The dimensions of the parcel.length
(Number) - Longest dimension in centimeters, to one decimal pointwidth
(Number) - Second longest dimension in centimeters, to one decimal pointheight
(Number) - Shortest dimension in centimeters, to one decimal point
preferences
(Object) - Your shipment preferencesshowPackingInstructions
(String) - true/false for whether to show packing instructions on the generated shipping label
Returns: Promise
Resolves: Object
- An object representing the created shipment, with the shipmentId, trackingPin, labels, and other URLs.
Refunds a non-contract shipment
Arguments:
id
(String) - The shipment ID to refundemail
(String) - The account holder's e-mail address
Returns: Promise
Resolves: Object
- An object with a serviceTicketDate, and serviceTicketId to indicate your refund request has been recieved. You can use the serviceTicketId when communicating with Canada Post
Note that refunds take a few days to process, and a successful response here does not indicate the refund has completed.
Gets basic tracking information about a particular shipment
Arguments:
pin
(String) - The PIN (Parcel Identification Number/Tracking Number) or Delivery Notice Card (DNC) number.type
(String) [optional] - The type of tracking number provided, either "pin" or "dnc". Defaults to "pin".
Returns: Promise
Resolves: Object
- An object with the tracking information, including expectedDeliveryDate, and the most recent shipping event.
Gets tracking information about a particular shipment
Arguments:
pin
(String) - The PIN (Parcel Identification Number/Tracking Number) or Delivery Notice Card (DNC) number.type
(String) [optional] - The type of tracking number provided, either "pin" or "dnc". Defaults to "pin".
Returns: Promise
Resolves: Object
- An object with the tracking information, including expectedDeliveryDate, and an array of significantEvents.
Gets a list of shipments in a particular date range
Arguments:
from
(Date) - The start (older) dateto
(Date) [optional] - The end (more recent) date. Defaults to current date.
Returns: Promise
Resolves: Array
- An array of objects, which include shipmentId, that were recorded on that date range.
Note that due to a Canada Post limitation, time zone information is discarded, and all dates/times are assumed to be Eastern time zone.
Gets basic information about a shipment.
Arguments:
id
(String) - The id of the shipment to look up
Returns: Promise
Resolves: Object
- An object that includes shipmentId, trackingPin, and links to receipt and shippingLabel.
Gets detailed information about a shipment.
Arguments:
id
(String) - The id of the shipment to look up
Returns: Promise
Resolves: Object
- An object that includes detailed shipping information.
Example:
nonContractShipmentDetails
(Object) - An object that represents shipment details. Common fields include the following:finalShippingPoint
(String) - The final postal code for deliverytrackingPin
(String) - The tracking pin for the shipmentrefundRequestInfo
(Object) - Details on the shipment's refund statusserviceTicketId
(String) - The ticket ID of the refund requestserviceTicketDate
(String) - The date of the refund request
deliverySpec
(Object) - The specifications of the deliveryserviceCode
(String) - The code to use (e.g. DOM.EP, USA.XP)sender
(Object) - The sender's address informationname
(String)company
(String)contactPhone
(String)addressDetails
(Object)addressLine1
(String)addressLine2
(String)city
(String)provState
(String)postalZipCode
(String)
destination
(Object) - The recipient's address informationname
(String)company
(String)clientVoiceNumber
(String)addressDetails
(Object)addressLine1
(String)addressLine2
(String)city
(String)provState
(String)postalZipCode
(String)countryCode
(String)
parcelCharacteristics
(Object) - An object that describes the parcelweight
(Number) - The weight of the parcel in kilogramsdimensions
(Object) - The dimensions of the parcel.length
(Number) - Longest dimension in centimeters, to one decimal pointwidth
(Number) - Second longest dimension in centimeters, to one decimal pointheight
(Number) - Shortest dimension in centimeters, to one decimal point
preferences
(Object) - Your shipment preferencesshowPackingInstructions
(String) - true/false for whether to show packing instructions on the generated shipping label