get-tracking-summary-request

complex

required

The top level XML element for the request input information.

Note: Exactly one of pin-number, dnc-number, or reference-criteria must be present under this top level element.

locale

simple

optional

Indicates your language preference for receiving error messages.

EN = English
FR = French

If no value is provided, the default language is English.

pin-number

simple

conditionally required

The PIN (Parcel Identification Number) assigned by Canada Post on creation of the shipping label and used for tracking purposes.

(12, 13 or 16 characters)

When executing a request by PIN, this is mandatory and is the only parameter necessary.

dnc-number

simple

conditionally required

The Delivery Notice Card (DNC) number – The number on the card left by delivery personnel when no one is home to receive the delivery.

(15 numeric characters)

When executing a request by DNC number, this is mandatory and is the only parameter necessary.

reference-criteria

complex

conditionally required

This structure contains the reference parameters for a call by reference parameters.

customer-number

simple

optional

Can be either:

• The customer number for the organization initiating the shipment
• The customer number of the customer on whose behalf the parcel was mailed.

(10-digit numeric)

This is an optional element. If the customer-number element is not specified, the customer-number of the user that was used to authenticate this request will be used.

If you ship parcels on behalf of other customers and you specify their customer number in the request, only tracking results of parcels mailed “on behalf of” that customer (and that match the other criteria in your request) are returned.

If you ship parcels on behalf of other customers and you specify your own customer number, you will receive tracking results for any parcels you shipped for yourself, and all parcels you shipped for any other customers (providing they also match the other criteria in your request).

reference-number

simple

conditionally required

The value assigned to a parcel by the shipper at the time the shipment was created. You would have specified this value in either “customer-ref-1” or “customer-ref-2” fields of the submitted parcel.

(up to 35 characters)

When executing a request by reference parameter, the reference-number element is mandatory and must be included.

The get Tracking Summary service only returns tracking results for parcels that match the reference-number value.

destination-postal-code

simple

optional

The destination Postal Code, zip code or postal identifier for the parcel in its destination country. This is the value that would be supplied in the element “postal-zip-code” in a create shipment request.

Format is any of the following:

• 6-character alphanumeric for Canada
  (A9A9A9)
• 5-digit or 5-4 digit numeric code for US
  (99999 or 99999-9999)
• Character String – up to 14 characters (free format) for other countries.

The destination-postal-code element is optional.

When present, the Get Tracking Summary service only returns tracking results for parcels that match the destination-postal-code value.

Note: For zip codes in the form 99999-9999, only the first 5 digits are used in the matching.

mailing-date-from

simple

conditionally required

The combination of mailing-date-from and mailing-date-to elements defines a range of dates for when the parcel(s) in question was shipped.

Format is: yyyy-mm-dd

The mailing-date-from value cannot be earlier than two calendar months from the current date.

When executing a request by reference parameter, both the mailing-date-from and mailing-date-to elements are mandatory and must be included.

The Get Tracking Summary service only returns tracking results for parcels that were shipped within the range of dates specified by the mailing-date-from and mailing-date-to elements.

mailing-date-to

simple

conditionally required

get-tracking-summary-response

The top level of the XML structure for the response.
It will either contain the results of a successful completion or the error structure.

tracking-summary

The main structure containing the results of the request.

pin-summary

Contains the response for the specified PIN.

May occur 1 …; 100 times

pin

The Parcel Identification Number (PIN) that you can use to call tracking services.

origin-postal-id

The first 3 digits of the origin Postal Code for Canadian destinations.

For an inbound international parcel, this field is blank or contains the postal identifier of the country of origin.

destination-postal-id

The first 3 digits of the destination Postal Code for parcels to be delivered in Canada.

For international parcels this is the postal identifier of the destination country (e.g. ZIP code for parcels with a U.S. destination) or an identifier of the destination country.

destination-province

The 2-digit province code for the destination.

"postal designators" - abbreviations used by Canada Post ISO 3166-2 for Canadian bound parcels.

Parcels bound for international destinations have the postal identifier of the destination country (e.g. ZIP code for parcels with a U.S. destination).

service-name

Canada Post service name in the language specified. The service-name will default to English if language is not specified.

mailed-on-date

The date of the first event for the item. If the item has been mailed from an international location this date may be blank.

expected-delivery-date

The date the item is expected to reach the destination address for addresses in Canada.

If the item has been mailed from or to an international location this date may be blank.

actual-delivery-date

The date the item was delivered.

Blank if not delivered or if delivery information from an international organization for an international shipment has not been provided.

delivery-option-completed-ind

0 – at least one option was not satisfied

1 – all options were satisfied

2 – no options were found

event-date-time

yyyymmdd:hhmmss

The time stamp of the most recent significant event.

event-description

A brief description of the event

attempted-date

The date that a delivery was attempted.

For shipments into or within Canada this will indicate that an unsuccessful attempt to deliver the parcel was made on the specified date.

customer-ref-1

The value supplied by the shipper as customer-ref-1when the shipment was first created with Canada Post. French character set is supported through this interface.

customer-ref-2

The value supplied by the shipper as customer-ref-2 when the shipment was first created with Canada Post. French character set is supported through this interface.

return-pin

If a return label (PIN) was printed at the same time the shipment was created and the shipment is being returned, the return PIN is displayed.

event-type

The value in this field will indicate what type of event is represented for this item.

event-location

For an event representing a scan or delivery, this value will indicate the location where the event took place.

signatory-name

If the event presented as the last most significant event is a signature, the text of this field contains the signatory name.

002

Duplicate Pin

Received on PIN or DNC searches where duplicate PINs have been encountered.

004

No Pin History

No tracking results were found based on the parameters provided. Check your parameters and the order of the from and to dates.

006

Reference number, mailed from date, mailed to date and destination Postal Code are required fields for a reference number search.

Received only on reference number searches.

008

Invalid Date

For summary reference searches, dates greater than 2 months old will result in a return of this error.