Contract Shipping

Code Samples for Contract Shipping: Java (.zip) | PHP (.zip) | C# (.zip)

Backgrounder: Shipping and Manifest Services

Legend

i Conduct your testing in the development environment. You will be billed for any manifests you submit through a Transmit Shipments call in the production environment.

Terms and definitions for shipping and manifest services

Knowledge of the following terms will assist you in understanding shipping and manifest services.

Term Description

Shipment

A single physical item to be shipped by Canada Post. Shipments have a logical counterpart: the collection of data about the shipment. Your shipping system provides the data to Canada Post so that Canada Post can deliver the shipment according to your preferences and specifications.

Group

The purpose of a group-id is to group several shipments together to include on the same manifest. For example, grouping is useful in the following scenarios:

  • You have multiple fulfillment locations.
  • You want all shipments in a group to be shipped on the same day.
  • You want to group shipments together for internal reference or billing purposes.

A group controls which shipments are grouped together in one Transmit Shipments request and consequently which shipments are grouped together for billing of manifests.

Key features of groups are as follows:

  • A group allows separate pickups or drop-offs from different physical locations.
  • A service provider for multiple customers automatically receives separation for each customer they are serving.
  • Any character value may be used in a group name. A new group name automatically creates a group when the first shipment member is created under that name.
  • A group name repeated from a previous shipment links the new shipments with all others in the same group.
  • The same group name CANNOT be used to link shipments between different "behalf of" customers.
  • The list of shipments within a single group can be accessed by invoking the Get Shipments service with the group specified.

Additional behaviour of groups is described below under Manifest.

Manifest

A manifest is proof of payment for a collection of physical shipments. If you are a commercial customer and you use contract shipping web services you must produce a hard copy of your manifest and provide to Canada Post when we pick up your shipments or when you drop off your shipments at a mail processing plant.

To create a manifest, you must use the Transmit Shipments web service call. Transmit Shipments is a mandatory call. It triggers the upload of shipment data for billing and tracking systems. The response from a transmit shipments call provides you with the information you need to invoke the Get Manifest web service and then the Get Artifact service, which in turn allows you to print your manifest. We monitor all shipments that have not followed this process. Failure to comply will result in manual billing at full rates and/or a loss of your automation discount.

Manifest groupings are created by Canada Post logic after a transmit request is made for one or more customer group codes. The Canada Post logic creates groupings required to segregate the shipments for billing or delivery purposes.

For billing, manifests are segregated by the payer customer number.

For delivery purposes, manifests are segregated by domestic, U.S.A. and international destinations and drop locations.

Lifespan of shipments, groups and manifests

Shipments

Logical shipments are kept on Canada Post servers until 90 days after they have been transmitted. This represents 90 days after the physical shipment was picked up or deposited. The logical shipments are referenced in web services by the Canada Post system-provided unique shipment-id. After transmit, for shipments that support tracking, the tracking-pin number is used as a reference rather than the shipment-id. It is also possible to use a customer provided reference number for tracking.

Untransmitted shipments are not deleted from our servers until they are either transmitted or voided, in which case they will be deleted after 90 days.

Groups

A group is created for any unique value that is passed by your application when a Create Shipment request is made. A group will become empty when it is referenced in a Transmit Shipments request. Empty groups are deleted overnight. There is no issue with re-using a group that was previously referenced in a Transmit Shipments request.

Manifests

Manifests are created when the Transmit Shipments request is made. Manifests exist for the same amount of time as the shipments they contain (90 days).

The hierarchy of the shipment entities for a customer mailing for themselves from one location is shown below.

Standard Hierarchy

Standard Hierarchy

The hierarchy of entities for a customer mailing on behalf of others and/or from multiple locations is shown below.

Advanced Hierarchy

Advanced Hierarchy