Contract Shipping

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

Transmit Shipments – REST

Summary

Name: Transmit Shipments
Reason to Call: Used when one or more groups of shipments is ready for pickup by Canada Post or drop-off to a Canada Post location. This can be used for shipments belonging to any customer who has a contract.
Input:

The inputs include:

  • the mailed-on-behalf-of customer number
  • the list of groups that are ready for pickup/drop-off
  • the pickup or deposit location for your shipments
  • the method of payment
  • an optional list of shipments to be excluded from the pickup
Output:

The output is a list of links to the manifests that are created based on characteristics of the shipments to be transmitted. You must use these links to call the Get Manifest service to ensure a manifest is successfully created. You can also use the links to get more information about these manifests.

Error Example: Group id was not found for transmission; please remove or correct.
Typical Prior Call: Create Shipment
Typical Next Call: Get Manifest
Version history: Release notes
Transmit Shipments – Summary of Service

Transmit Shipments – Summary of Service

Request Details

Request – Structure for Transmit Shipments

Endpoint

POST https://XX/rs/{mailed by customer}/{mobo}/manifest

Replace... With...

XX (Development)

ct.soa-gw.canadapost.ca

XX (Production)

soa-gw.canadapost.ca

{mailed by customer}

your customer number

{mobo}

the mailed on behalf of customer number or repeat your customer number

HTTP Headers

HTTP Header Variable

Value

Accept

application/vnd.cpc.manifest-v8+xml (Note: */* in place of the header value will return an error)

Content-Type

application/vnd.cpc.manifest-v8+xml (Note: */* in place of the header value will return an error)

Authorization

Basic {Base64 encoding of userid:password}

Accept-language

en-CA or fr-CA

Body

<?xml version="1.0" encoding="utf-8"?>
<transmit-set xmlns=”http://www.canadapost.ca/ws/manifest-v8”>
xxx
</transmit-set>

Request – Top Level View of Elements

This section describes the top level (complex) XML elements that are part of the input to this service. The exact hierarchical structure of the XML inputs is shown in the XML Diagram.

Transmit Shipments – Top Level View of Request Elements
Element Name Type Required / Optional Description

transmit-set

Complex

Required

This is the top level XML element of the request structure.

customer-request-id

Simple

Optional

For Future Use.

group-ids

Complex

Required

Contained within transmit-set.

This is a list of group-ids. The Transmit Shipments service will create a manifest for each group. The manifest will list the shipments included in the group (with the exception of shipments you exclude)

requested-shipping-point

Simple

Conditionally required

(6-character alphanumeric string)

Must be in valid Postal Code format

e.g. A9A9A9

Pattern is [A-Z]\d[A-Z]\d[A-Z]\d

Contained within transmit-set.

If you deposit your shipments yourself, you have 2 choices:

  • Omit this element and provide the site number of your deposit location in shipping-point-id. (recommended), or
  • Provide the postal code of your deposit location here and omit shipping-point-id.

Note: Using requested-shipping-point to indicate your deposit location postal code will be discontinued in a future release. If you deposit your shipments yourself, we recommend using the shipping-point-id element.

Mandatory when cpc-pickup-indicator is provided.

Mutually exclusive with shipping-point-id, but one of the two must be provided.

If you provide the same Postal Code here that you used in your Create Shipment requests, then there will be no pricing adjustments related to the starting point for shipping. If you use a different Postal Code here than in Create Shipment, it may result in a pricing adjustment depending on the distance between the original shipping point (in the Create Shipment request) and the final shipping point (in the Transmit Shipments) request.

cpc-pickup-indicator

Simple

Optional

(true)

Set this element to true if your shipments are picked up by Canada Post or a third party. Do not provide this element when false. Provide the Postal Code of your pickup location in requested-shipping-point. If you use the same indicator and requested-shipping-point as you did in Create Shipment, there will be no pricing adjustment; see details in requested-shipping-point.

Omit this element if you deposit your shipments yourself.

Mutually exclusive with shipping-point-id.

Note: In a future release it will become mandatory to explicitly identify whether your shipment is picked up by Canada Post (by providing both this indicator and requested-shipping-point) or deposited at a Canada Post site (by providing shipping-point-id).

We recommend preparing for this change by providing this indicator (and requested-shipping-point) if your shipment is picked up by Canada Post.

shipping-point-id

Simple

Conditionally required

(4-character alphanumeric string)

If you deposit your items at a Post Office or other Canada Post facility, provide the site number of the deposit location. Look up the site number using Find a Deposit Location. This information is used for pricing.

If you enter a different site number than you provided in your Create Shipment request, pricing may be affected.

Mutually exclusive with requested-shipping-point but one of the two must be provided.

Note: If you deposit your items yourself, we recommend using this element rather than the requested-shipping-point element to indicate your deposit location.

method-of-payment

Simple

Required

{15-character string}

Contained within transmit-set.

This indicates what the method of payment is for the manifests that are to be generated.

Valid methods of payment are as follows:

  • CreditCard = the payment will be by credit card.
  • Account = the payment will be via an existing contract with the paid-by-customer.
  • SupplierAccount = the payment will be through the Supplier Account identified as default in the customer profile (only available to Supplier Account providers).

Note: Different shipments may have different paid-by-customers. Separate manifests will be generated for shipments with different paid-by-customers.

manifest-address

Complex

Required

Contained within transmit-set.

This structure contains the address that is printed on the manifest label.

detailed-manifests

Simple

Required

{true,false}

Contained within transmit-set.

This indicates whether a full detailed manifest document will be rendered, or a summarized manifest document will be rendered.

customer-reference

Simple

Optional

(Alphanumeric String - up to 12 letters/digits)

Contained within transmit-set.

A customer reference number may be provided to Canada Post which is placed on the manifest and returned in a Get Manifest Details request.

excluded-shipments

Complex

Optional

Contained within transmit-set.

The list of shipment-ids that are to be excluded from transmission. These shipments will remain in their group and will automatically be picked up for the next transmit.

Request – Detailed View of Simple Elements

Transmit Shipments – Detailed View of Request Elements
Element Name Type Required / Optional Description

group-id

Simple

Required

(Character String – up to 32 characters)

Contained within group-ids.

May occur 1 … N times.

The group-id of any group, whose shipments are to be included in the Transmit Shipments action.

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.

Note: domestic, U.S., and international shipments will be placed on separate manifests even if they contain the same group-id.

Performance limitations
To avoid a timeout of our servers, please follow these recommendations:

  • Do not include more than 30 groups per manifest (i.e., maximum of 30 group-ids in one Transmit Shipments request.)
  • Do not put more than 5,000 shipments in one group.

System limitations
To avoid an error, please do not exceed the following limits before performing a Transmit Shipments call:

  • Maximum of 50 groups per manifest (error 9109 if exceeded).
  • Maximum of 10,000 shipments in one group (error 9110 if exceeded).
  • Maximum of 10,000 shipments across multiple groups (error 9108 if exceeded).

manifest-name

Simple

Optional

(Character String up to 44 characters)

Contact name for the manifest address.

This is printed on the manifest document.

manifest-company

Simple

Required

(Character String up to 44 characters)

Contained within manifest-address.

The company name of the manifest address.

This is printed on the manifest document.

phone-number

Simple

Required

(Character String – up to 32 characters)

Contained within manifest-address

Phone number to be printed on the manifest.

address-details

Complex

Required

Contained within manifest-address.

This structure contains the address details for the manifest address.

The address is printed on the manifest document.

address-line-1

Simple

Required

(Character String up to 44 characters)

Contained within address-details.

address line 1 for the manifest address.

address-line-2

Simple

Optional

(Character String up to 44 characters)

Contained within address-details.

address line 2 for the manifest address.

city

Simple

Required

(Character String up to 40 characters)

Contained within address-details.

City for the manifest address.

prov-state

Simple

Required

(Character String – up to 20 characters)

Contained within address-details.

Province (or state) for the manifest address.

country-code

Simple

Conditionally
Required

(2-character string)

Contained within address-details.

Country code for the manifest address; CA and US are accepted.

Required if US. Optional if CA.

postal-zip-code

Simple

Required

Can be:

  1. 6-character alphanumeric for Canada (A9A9A9)

    Pattern is [A-Z]\d[A-Z]\d[A-Z]\d or

  2. 5-digit or 5-4 digit numeric code for US)

    Pattern is \d{5}(-\d{4})?

Contained within address-details.

Postal Code or zip code for the manifest address.

shipment-id

Simple

Optional

(Alphanumeric String – up to 32 letters/digits)

Contained within excluded-shipments.

This is an identification number representing an existing shipment that is to be excluded from the Transmit Shipments.

Note: If this feature is to be used, your system must store shipment ids from prior Create Shipment or Get Shipment calls and have a mechanism for selecting the ones to be excluded from transmit.

Request – XML Diagram

The following is the hierarchical structure of the XML to be used for providing the shipping input information.

Transmit Shipments – Structure of XML Request
Transmit Shipments – Structure of XML Request

Response Details

Response – Elements

The following table describes the XML fields in the response.

For a detailed view of the hierarchy of the response, see the diagram below.

Transmit Shipments – Detailed View of Response Elements
Element Name Type Description

manifests

Complex

This is the top level of the structure.

link

Complex

Contained within manifests.

Note: Multiple manifests may be created from a single Transmit Shipments call for a number of reasons. The system will generate separate manifests:

  • by Canadian vs. international shipments.
  • by mobo
  • by paid-by-customer
  • by contract number

May occur 1 … N times.

Each link element must be accessed to assemble and print all the paperwork required for drop off or pickup of shipments.

For a description of link attributes, see Provided endpoints.

The link represents one of the manifests rendered as part of the Transmit Shipments process. In this case, the href attribute is an endpoint to the Get Artifact service for that manifest. The media-type attribute will indicate the format of the graphics file (PDF).

If you attempt to transmit shipments that we billed you for automatically (in cases where you inducted shipments before performing a Transmit Shipments call), you will receive a link to an empty manifest. The empty manifest informs you that you were billed automatically and provides details about how to avoid this in the future.

The empty manifest does not contain shipments or details, cannot be retrieved through Get Manifests and cannot be used to induct mail. The detailed manifest we created for you with the shipments that you were billed for automatically will be sent to the email address provided in your online Canada Post profile.

Response – XML Diagram

The following diagram shows the top level response.

Transmit Shipments – Structure of XML Response

Transmit Shipments – Structure of XML Response

Note: the attribute "index" of the link element (in the picture above) is not used in the Transmit Shipment service.

Response – Possible Error Responses

See HTTP status codes for general information regarding error handling.

Possible "400" error messages for this service include the following.

Code Message

7313

Supplier Account payment can only be submitted by the account provider or an authorized user.

7317

The issuer of the default Supplier Account in your Canada Post online profile does not match the platform you are using.

9118

Group id: "99" was not found for transmission. Please remove or correct.

9119

Shipment id: "12373264234" was not found for exclusion. Please remove or correct.

9122

All groups in the transmit request were empty or all shipments were excluded; there was nothing to transmit.

9186

Only one of shipping-point-id or cpc-pickup-indicator can be provided.

9187

requested-shipping-point is mandatory when cpc-pickup-indicator is provided.

9188

shipping-point-id is not valid.

9189

requested-shipping-point and shipping-point-id are mutually exclusive.

Examples

Sample REST XML Request – Transmit Shipments

<transmit-set xmlns="http://www.canadapost.ca/ws/manifest-v8">
<group-ids>
<group-id>1234</group-id>
</group-ids>
<requested-shipping-point>K1K4T3</requested-shipping-point>
<cpc-pickup-indicator>true</cpc-pickup-indicator>
<detailed-manifests>true</detailed-manifests>
<method-of-payment>Account</method-of-payment>
<manifest-address>
<manifest-company>my company</manifest-company>
<manifest-name>MajorShop</manifest-name>
<phone-number>555 555 5555</phone-number>
<address-details>
<address-line-1>1230 Tako RD.</address-line-1>
<city>Ottawa</city>
<prov-state>ON</prov-state>
<postal-zip-code>K1A1A1</postal-zip-code>
</address-details>
</manifest-address>
</transmit-set>

Sample REST XML Response – Transmit Shipments

<manifests>
<link rel="manifest" href="https://XX/1111111111/222222222/manifest/444444444444" media-type="application/vnd.cpc.manifest-v8+xml"></link>
<link rel="manifest" href="https://XX/1111111111/222222222/manifest/333333333333" media-type="application/vnd.cpc.manifest-v8+xml"></link>
</manifests>