Links to all of the information associated with the created shipment, including the parcel identification numbers (PIN) for tracking.

These links will remain accessible to the client for a fixed period of time (currently 90 days), or until the shipment is voided by the client.

Transmit Shipments - Unless your Create Shipment request includes the element transmit-shipment (which identifies a shipment that does not require a manifest for proof of payment) the shipment process is not complete until you perform a Transmit Shipments call. Transmit Shipments sends shipment data for billing and tracking to Canada Post and provides you the information you need to get a manifest (your hard-copy proof of payment required every time you have shipments for pickup or drop-off to Canada Post). 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.

To print your manifest, use the information provided in the response to Transmit Shipments to invoke Get Manifest and then Get Artifact.

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

Accept

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

Content-Type

application/vnd.cpc.shipment-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

shipment

complex

required

The top level XML element for the request input information.

create-qr-code

Simple

Optional

This is an optional element, used to request the QR code image of the public label in base64 format, along with contains public key label URL, and expiry date.

If true, two new links are provided: publicLabel and publicKeyInfo.

Note: Only applicable to 8 1/2 X 11 paper encoded in pdf

create-public-key

Simple

Optional

This is an optional element, used to request the public key label URL, and expiry date.

If true, two new links are provided: publicLabel and publicKeyInfo

Note: Only applicable to 8 1/2 X 11 paper encoded in pdf

customer-request-id

simple

optional

(Character String - up to 35 characters)
A unique ID that you can define for this shipment. It must be unique or the request will be rejected.

Supplier Account vendors must use this field to provide a unique identifier for any shipment that is a pre-authorized payment request.

You can also use this ID recover shipment details, such as the label, without the need for the information provided in the Create Shipment response. Instead, just use this ID in a request to Get Shipments.

group-id

simple

conditionally required

(Character String - up to 32 characters)

This element represents the group-id number (or group name) in which to place the created shipment. The group will be created by the Canada Post service if it does not exist.

Must be prefixed by the version number of the namespace you are using,
e.g. <v8:group-id>1234</v8:group-id>

The group-id element is required unless transmit-shipment is provided, in which case group-id must not be provided.

Do not create a unique group for each individual shipment. 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).

transmit-shipment

Simple

conditionally required

{true}

Contained within shipment.

Must be prefixed by the version number of the namespace you are using,
e.g. <v8:transmit-shipment>true</v8:transmit-shipment>

This element identifies a shipment where no manifest is required for proof of payment.

This shipment will be transmitted immediately and a subsequent Transmit Shipments call is not required.

Use this element if you ship fewer than 50 parcels per day from multiple locations using one of these business models:

• Consumer-to-consumer shipping (e.g. online auction websites)
• Distributed order management
• Third-party direct fulfillment

When this element is set to true, you will be charged immediately once your Create Shipment request is complete. Your shipment cannot be voided.

Important: If you use traditional contract shipping and manifest processes (e.g. you ship more than 50 parcels per day from a central warehouse), this process is not for you. You must continue to use the regular manifest process. Failure to do so will result in refusal of your shipment until you produce the required manifests.

If you are a non-contract shipping customer who uses contract shipping web services, you must provide this element.

quickship-label-requested

Simple

Optional

{true}

Use this element if you already have a domestic parcel with the recipient’s name and address on it, but you want to create an additional label to affix to the parcel for tracking purposes.

Set this element to true, and, for billing purposes, provide the country code (must be CA) and the postal code, in the destination structure. A label that contains a tracking barcode and the words “Quick Ship – Refer to Address Label/Expédition rapide – Reportez-vous à l’étiquette d’adresse” will be created.

Only provide this parameter when you want a Quick Ship label (i.e. do not provide when false).

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

Postal Code of the location where your shipments are picked up. The Postal Code you provide is used for pricing purposes.

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

You will be asked to provide the requested-shipping-point again in your Transmit Shipments request. If you use a different Postal Code, it may result in a price adjustment depending on the difference in distance between the two locations.

cpc-pickup-indicator

simple

Optional

(true)

Set this element to true if your shipments are picked up by Canada Post or a third party. Provide the Postal Code of your pickup location in requested-shipping-point.

Omit this element if you deposit your shipments yourself.

Mutually exclusive with shipping-point-id.

You must also set this element to true in your Transmit Shipments request.

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.

You will also be asked to provide the shipping-point-id in your Transmit Shipments request. Enter the same site number or 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.

expected-mailing-date

simple

optional

(YYYY-MM-DD - date format)

Note: You can omit this element. It will be used in a future release.

All shipments are priced as per the current shipment date and are re-priced at time of transmit if transmitted at a later date.

provide-pricing-info

simple

optional

{true}

This element identifies that you want the shipment-price structure included in the response to this call. It will result in a larger payload but eliminates the need for a subsequent call to Get Shipment Price.

Only applicable to a shipment where transmit-shipment=true.

Only provide this parameter if you want pricing details in the response (i.e., do not provide when false).

provide-receipt-info

simple

optional

{true}

This element identifies that you want the shipment-receipt structure included in the response to this call. It will result in a larger payload but eliminates the need for a subsequent call to Get Shipment Receipt.

Only applicable to a shipment where transmit-shipment=true that is paid by credit card or Supplier Account.

Only provide this parameter if you want receipt details in the response (i.e., do not provide when false).

delivery-spec

complex

required

Provides a description of the delivery request details, including recipient, service-code, sender, options, item specification, notification-info and reference-ids.

service-code

simple

Required

(Character String - up to 32 characters)

Must be a valid code representing the Canada Post delivery service used for shipping the item. The most frequently used codes are listed below.

(Note - These delivery services and their codes can be discovered by calling the Get Rates and Discover Services web services described in Rating)

sender

complex

required

This structure contains data about the sender that will appear in the “From” address of the label. Blank fields will be removed for address formatting.

Note: sender address must be domestic.

name

simple

optional

(Character String - up to 44 characters)

Contact name of the sender.

company

simple

required

(Character String - up to 44 characters)

Company name of the sender.

contact-phone

simple

required

(Character String - up to 25 characters)

Contact phone number of the sender.

address-details

complex

required

Contains the address data about the sender. Blank address fields will be removed for formatting the labels.

Note: sender address must be domestic.

address-line-1

simple

required

(Character String - up to 44 characters)

Address of the sender.

address-line-2

simple

optional

(Character String - up to 44 characters)

Address line 2 of the sender.

city

simple

required

(Character String - up to 40 characters)

City of sender.

prov-state

simple

required

(Character String - up to 20 characters)

Province of sender.

Use standard Canadian province codes.

country-code

simple

required

(2-character valid country code)

Country code of sender. Must be CA.

postal-zip-code

simple

required

(6-character alphanumeric)

Must be in valid postal code format

e.g. A9A9A9

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

destination

complex

required

This element should always contain the address of the mail recipient, even if you are using the Deliver to Post Office option.

• For regular shipments, this data will appear in the "To" address of the label.
• For Deliver to Post Office shipments, the system will substitute the Post Office address on the label.
• For Quick Ship shipments (quickship-label-requested = true), this is only used for rating purposes and only the destination country-code (CA) and postal-code elements must be provided.

Blank fields will be removed in the address formatting.

name

simple

conditionally required

(Character String – up to 44 characters)

Contact name of the recipient at the destination.

If the Deliver to Post Office option is used, the name element must be present for the destination.

Not required when quickship-label-requested is true.

When shipping outside of Canada, at least one of name or company is required to comply with international customs regulations.

company

simple

conditionally required

(Character String – up to 44 characters)

Company name of the recipient at the destination.

When shipping outside of Canada, at least one of name or company is required to comply with international customs regulations.

additional-address-info

simple

optional

(Character String – up to 44 characters)

Additional address information for the destination.

This information is printed directly above address line 1 on the shipping label.

client-voice-number

simple

conditionally required

(Character String – up to 25 characters)

Phone number at the destination. Not required for domestic shipments unless the Deliver to Post Office option has been selected.

Note: In addition to numbers, the following characters are also accepted in this field:

• A plus sign (+), but only as the first character in the string.
• Period (.), hyphen (-), open and close brackets, space, and x or p to indicate an extension.

address-details

complex

required

Contains the address data the destination of the shipment. Blank fields will be removed for formatting the labels.

address-line-1

simple

conditionally required

(Character String – up to 44 characters)

Address at the destination.

Not required when quickship-label-requested is true; mandatory otherwise.

address-line-2

simple

optional

(Character String – up to 44 characters)

Address line 2 for the destination.

city

simple

conditionally required

(Character String – up to 40 characters)

Destination city.

Optional for international shipments. Required for domestic and U.S.A. shipments.

Not required when quickship-label-requested is true.

prov-state

simple

conditionally required

(Character String – up to 20 characters)

Province or state for the destination.

Use:

• Standard province code for provinces within Canada.
• Standard state code for U.S. states.
• Free form for states and provinces of other countries.

Optional for international shipments. Required for domestic and U.S.A. shipments (except when quickship-label-requested is true).

country-code

simple

required

(2-character valid country code)
Country code for the destination.

Must be CA when quickship-label-requested is true.

postal-zip-code

simple

conditionally required

Can be one of the following:

• (6-character alphanumeric for Canada (A9A9A9)
  Pattern is [A-Z]\d[A-Z]\d[A-Z]\d
• (5-digit or 5-4 digit numeric code for US)
  Pattern is \d{5}(-\d{4})?
• Character String - up to 14 characters (free format) for other countries.

Required for countries that require a Postal Code or zip code (e.g. Canada, U.S.A.)

Postal Code or zip code at the destination.

options

complex

optional

Contains options for the delivery service-code such as insurance, COD, etc.

option

complex

conditionally required

May occur 1 … 20 times.

At least 1 occurrence is required if the corresponding parent XML element "options" exists.

A selection of a shipping option (e.g. COD, insurance, etc.)

option-code

simple

conditionally required

(Alphanumeric String of up to 10 letters/digits)

Required if the corresponding parent XML element "option" exists.

This is the option code indicating which option applies to this shipment.

Valid option codes are as follows

SO - Signature
COV - Coverage
COD - Collect on delivery
PA18 - Proof of Age Required - 18
PA19 - Proof of Age Required - 19
HFP - Card for pickup
DNS - Do not safe drop
LAD - Leave at door - do not card
D2PO - Deliver to Post Office

Note: The D2PO option indicates that the parcel will be delivered directly to a nearby Post Office. For the D2PO option, the following XML elements are required:

• name (under destination)
• client-voice-number (under destination)
• notification
• option-qualifier-2

Note: If you select Collect on Delivery (COD), specify Card for Pickup (HFP) or Deliver to Post Office (D2PO). This is to facilitate the collection of COD funds at a post office. If not specified, the system will default to HFP.

Non-delivery handling codes
(required for some U.S.A. and international shipments)
RASE - Return at Sender’s Expense
RTS - Return to Sender
ABAN - Abandon

option-amount

simple

conditionally required

(Numeric field of pattern 6.2 e.g. 999999.99)

Required if the corresponding parent XML element "option" exists and depending on the value of option-code.

e.g., For COV option, this is the amount of insurance coverage to be purchased.

For COD option, this is the base amount to collect on delivery (shipping costs may also be added by the system as described below in option-qualifier-1).

On U.S. and international shipments, do not provide if you want the system to calculate the maximum allowable coverage (see option-qualifier-1 below).

option-qualifier-1

simple

optional

boolean – {true, false}

Can be used to provide a qualifier for the COD or COV options.

To indicate if the COD amount is to include the shipping cost or not:

• true = Shipping costs will be added to the COD amount you provided in <option-amount>.
• false = The COD amount to collect is specified in option-amount (i.e. Shipping costs are not to be added).

To use with the COV option on U.S. and international shipments to indicate that the system can apply the maximum allowable coverage amount, which would equal the total value of your goods, up to the allowable maximum for product and country:

• true = Use maximum allowable coverage; when used, there is no need to provide option-amount.
• false (the default) = Use the amount of coverage as provided in option-amount.

False is the default if the qualifier is not provided.

option-qualifier-2

simple

conditionally required

{Character String up to 12 characters}

Required if the corresponding parent XML element "option" exists and the option-code is one that requires a 2nd qualifier.

Currently, the options requiring a 2nd qualifier are:

parcel-characteristics

complex

required

Describes the characteristics of the parcel.

weight

simple

required

(Numeric field of pattern 3.3 e.g. 999.999)

Total package weight in kg.

dimensions

complex

optional

Contains the physical dimensions of the parcel, which can be used to make a more accurate determination of shipping cost.

length

simple

conditionally required

(Numeric field of pattern 3.1 e.g. 999.9 pattern)

Length of parcel in cm.

Required if the corresponding parent XML element "dimensions" exists.

If specified, a more accurate price can be derived.

width

simple

conditionally required

(Numeric field of pattern 3.1 e.g. 999.9 pattern)

Width of parcel in cm.

Required if the corresponding parent XML element "dimensions" exists.

If specified, a more accurate price may be derived.

height

simple

conditionally required

(Numeric field of pattern 3.1 e.g. 999.9 pattern)

Height of parcel in cm.

Required if the corresponding parent XML element "dimensions" exists.

If specified, a more accurate price may be derived.

unpackaged

simple

optional

{true, false}

Indicates whether a shipment is unpackaged or not. For example, auto tires may be an example of an unpackaged shipment.

mailing-tube

simple

optional

{true, false}

Indicates whether a shipment is contained in a mailing tube. e.g. a poster tube

oversized

simple

optional

{true, false}

Indicates whether the parcel is oversized or not.

Note: If parcel dimensions have been provided, then this element will be automatically determined (as either true or false) based on the parcel dimensions (regardless of whether you include a value for the "oversized" element field). However, if no dimensions are provided, then you can specify that a parcel is oversized (or not) using this element.

notification

complex

conditionally required

Contains client preferences with respect to email notification for tracking events e.g. delivery.

This element is required if the Deliver to Post Office (D2PO) option has been selected. For Deliver to Post Office, the email indicated within notification will be used to notify the customer that their parcel is ready for pickup.

email

simple

conditionally required

(Character String - up to 60 characters)

Must be a valid email address.

Pattern is (['_A-Za-z0-9\-\+])(\.['_A-Za-z0-9\-\+])@([A-Za-z0-9-])(\.[A-Za-z0-9-])(\.[A-Za-z]{2,})

This element is required if the notification element exists.

Email address to receive automatic tracking updates.

on-shipment

simple

conditionally required

{true, false}

This element is required if the notification element exists.

Indicates whether you wish to receive an email notification upon shipment of the parcel.

on-exception

simple

conditionally required

{true, false}

This element is required if the notification element exists.

Indicates whether you wish to receive an email notification on exceptions.

on-delivery

simple

conditionally required

{true, false}

This element is required if the notification element exists.

Indicates whether you wish to receive an email notification upon delivery of the parcel.

print-preferences

complex

optional

Contains print preferences for the labels.

output-format

simple

optional

{8.5x11, 4x6}

8.5x11 indicates paper and 4x6 indicates thermal.

{PDF, ZPL}

Use this field to specify the output format for your shipping label: PDF or ZPL II. If not provided, PDF will be selected by default.

If you choose ZPL, the response from a Get Artifact call will include a file containing ZPL II printer commands. You will then need to either code a solution or use an application to stream the commands directly to a thermal printer.

For ZPL II labels, your printer must support truncation. Use our sample code to test your printer’s ability to truncate text.

ZPL is only available on thermal paper so <output-format> must be 4x6.

preferences

complex

required

Contains a number of preferences with respect to printing labels, etc.

show-packing-instructions

simple

required

{true, false}

Indicates whether packing instructions are to be rendered on the label.

show-postage-rate

simple

conditionally required

{true, false}

Indicates whether the postal rate is to be shown on the label.

This element is required only for U.S.A. and international shipments.

show-insured-value

simple

conditionally required

{true, false}

Indicates whether the insured value is to be shown on the label.

This element is required only for insured U.S.A. and international shipments.

references

complex

optional

Contains reference fields that you assign. You can assign these alternate (possibly unique) identification numbers to the shipment for any purpose useful to you.

cost-centre

simple

optional

(Character String - up to 30 characters)

This is a value you assign for use by your applications. The value you enter here will appear on your invoice and in the PosteCS secure email that we use to send your invoice.

customer-ref-1

simple

optional

(Character String - up to 35 characters)

This is a user-defined value available for use by your applications. (e.g. you could use this field as an internal "order id"). The value you enter here will appear on the shipping label, in Track and – for customers who subscribe to our Automated Parcel Tracking service – in your APT file.

customer-ref-2

simple

optional

(Character String - up to 35 characters)

This is a user-defined value available for use by your applications. The value you enter here will appear on the shipping label, in Track and – for customers who subscribe to our Automated Parcel Tracking service – in your APT file.

customs

complex

optional

Contains information to be printed on the label to facilitate passing through customs at international borders.

currency

simple

conditionally required

(Character String - 3 alphabetic characters)

This is the currency of the receiving country. The currency code is converted to uppercase, if not already. Value must be:

• CAD for Canadian currency
• USD for U.S. currency
• Other valid ISO currency code

Required if the corresponding parent XML element "customs" exists.

conversion-from-cad

simple

conditionally required

(Numeric field of pattern 3.3 i.e. 999.999)

The conversion rate from the Canadian dollar to the currency you entered in the currency element above; for example, if you used USD as the target currency and $1.00 CAD = $0.85 USD, the conversion rate is 0.85.

Required if the corresponding parent XML element "customs" exists and the currency is not CAD.

reason-for-export

simple

conditionally required

(3 characters)

A code that represents the reason for export, which assists with border crossing.

The codes and their meanings are as follows:

DOC = document
SAM = commercial sample
REP = repair or warranty
SOG = sale of goods
OTH = other

Required if the corresponding parent XML element "customs" exists.

other-reason

simple

conditionally required

(Character String - minimum 4 characters; maximum 44 characters)

Contains the reason for export.

Required if the element reason-for-export is "other".

duties-and-taxes-prepaid

simple

optional

Reserved for future use.

certificate-number

simple

optional

(Character String – up to 10 characters)

If required by customs at the destination, the number of the government/agency certificate or permit.

licence-number

simple

optional

(Character String – up to 10 characters)

If required by customs at the destination, the number of the government/agency import or export licence.

invoice-number

simple

optional

(Character String – up to 10 characters)

If required by customs at the destination, the commercial invoice number.

ioss-id

simple

optional

(Character String up to 13 characters)

Optional field to enter Tax Registration Numbers or IDs (e.g. Tax ID, IRS No., VAT, IOSS number) for electronic transmission to the receiving post. Note: IOSS should be entered as IMxxxxxxxxxx.

sku-list

complex

required

Required if the corresponding customs parent element exists.

Contains the list of unique types of items that are contained within this shipment, as well as information about them. Each item type may have a quantity of 1 or more. This information is printed on the manifest label to assist with processing of the parcel at customs.

item

complex

required

At least one instance of item must exist.

There is a limit of 500 item elements under a sku-list.

Contains the information about the item type (number of units, value per unit, etc.) that are contained in this shipment.

customs-number-of-units

simple

conditionally required

(Numeric field of four digits e.g. 9999)

Required if the corresponding parent XML element "item" exists.

The number of units in the parcel.

customs-unit-of-measure

simple

optional

(Three-character ISO code)

Identifies the unit of measure for the customs-number-of-units.

• PCE – Piece
• NMB – Number
• PAR – Pair
• PKG – Package
• ENV – Envelope
• LTR – Litre
• MLT – Millilitre
• BOX – Box
• BAG – Bag
• MTR – Metre
• MMT – Millimetre
• DZN – Dozen
• GRM – Gram
• KGM – Kilogram
• CTN – Carton
• BIN – Bin
• SET – Number of sets
• BOT – Bottle
• TBE – Tube
• KIT – Kit

customs-description

simple

conditionally required

(Character String - up to 45 characters)

Required if the corresponding parent XML element "item" exists.

A customs description of the item.

sku

simple

optional

(Character String - up to 15 characters)

A customs sku number or sku name for the item

Note: Version 6 only permits up to 15 characters. Previous versions allow up to 44 characters, but data will be truncated at 15 characters. The length limitations are necessary to comply with international customs regulations.

hs-tariff-code

simple

optional

(Numeric field of the general form 9999.99.99.99)

Pattern is \d{4}(\.\d{2}(\.\d{2}(\.\d{2})?)?)?

The tariff code for the item.

unit-weight

simple

conditionally required

(Numeric field of pattern 2.3 e.g. 99.999)

Required if the corresponding parent XML element "item" exists.

The unit weight of the item in kg.

customs-value-per-unit

simple

conditionally required

(Numeric field of pattern 5.2 e.g. 99999.99)

Required if the corresponding parent XML element "item" exists.

The value per unit in Canadian currency of the item.

country-of-origin

simple

optional

(2-character valid country code)

The country of origin of the corresponding item. Provide this if the corresponding parent XML element "item" exists (and if the country of origin is known).

If the country of origin is not known, the element can be omitted.

province-of-origin

simple

conditionally required

(2-character valid province code)

Required if country of origin is Canada.

The province of origin of the goods.

settlement-info

complex

required

This structure contains the customer details for settlement of payment, including payment-method, customer, mailed-on-behalf-of-customer.

paid-by-customer

simple

optional

(10-digit numeric)

paid-by-customer numbers are 10 digits. If the number you provide has fewer than 10 digits, the system will add leading zeros to increase the length to 10.

The customer number of the customer who will be billed for the shipment. This is typically the same as the "mailed on behalf of" customer unless a Central Payer relationship has been identified to Canada Post. If it is not supplied, it defaults to mailed-on-behalf-of.

contract-id

simple

conditionally required

(10-digit numeric)

Contract-id numbers are 10 digits. If the number you provide has fewer than 10 digits, the system will add leading zeros to increase the length to 10.

Required to identify contract discounts if the intended method of payment is Account.

{true}

If you have shipments that originate outside of Canada, but are being delivered directly to a Canada Post plant, use this element to identify these shipments as continuous inbound freight (CIF). This option allows you to be eligible for Canadian sales tax exemptions. You will need to provide Canada Post with documentation that shows proof of origin, such as a Canadian customs document or bill of lading.

Only provide this parameter when the shipment is CIF (i.e. do not provide when false).

intended-method-of-payment

simple

required

Character String – up to 15 characters

This element indicates the customer’s method of payment for a shipment where no manifest is required (transmit-shipments=true), or the intended method of payment otherwise (the actual method of payment being in the subsequent Transmit Shipments).

Valid values for intended-method-of-payment are:

• CreditCard = the payment will be by credit card. This must be saved and defaulted on your Canada Post profile.
• Account = the payment will be by an existing contract with the paid-by-customer.
• SupplierAccount = the payment will be through the Supplier Account specified in pre-authorized-payment or identified as default in the customer profile (only available to Supplier Account providers).

promo-code

simple

optional

Character String – up to 10 characters.

Promotional discount code. Note that a promotion code is only valid for a certain period and product.

Your entry will be converted to uppercase (i.e, you can use lowercase or a mix of lower or upper case and will get the same result).

Note: Promotion Code DEVPROTEST can be used to test this functionality in the sandbox environment. This promo code is only valid in the sandbox environment and for the following products:

• Xpresspost (DOM.XP)
• Xpresspost International (INT.XP)

return-spec

complex

optional

Contains the return delivery request details, including return recipient, label-count, service-code and reference-ids. If this element is absent, no return shipping label is required.

service-code

simple

required

(Character String - up to 32 characters)

Must be a valid code representing the Canada Post delivery service used for shipping the item. The most frequently used codes are listed below.

(Note - These delivery services and their codes can be discovered by calling the Get Rates and Discover Services web services described in Rating)

return-recipient

complex

conditionally required

Required if the corresponding parent XML element “return-spec” exists.

The return-recipient structure provides the shipping details (e.g. address) for the return delivery as it shows on the return label.

name

simple

optional

(Character String - up to 44 characters)

Contact name of the return-recipient.

company

simple

optional

(Character String - up to 44 characters)

Company name of the return-recipient.

address-details

complex

conditionally required

Required if the parent element return-recipient exists (based on whether you have specified the need for a return address)

Contains the address data about return-recipient.

Blank fields will be removed in address fields for formatting the labels.

address-line-1

simple

required

(Character String - up to 44 characters)

Address line 1 of return-recipient.

address-line-2

simple

optional

(Character String - up to 44 characters)

Address line 2 of return-recipient.

city

simple

conditionally required

(Character String - up to 40 characters)

City of return-recipient.

Optional for international shipments. Required for domestic and U.S.A. shipments.

prov-state

simple

conditionally required

(Character String - up to 20 characters)

Province of cod-remittance.

Use standard Canadian province code.

Optional for international shipments. Required for domestic and U.S.A. shipments.

postal-zip-code

simple

conditionally required

6-character alphanumeric Canadian Postal Code for the return-recipient address.

(A9A9A9)
Pattern is [A-Z]\d[A-Z]\d[A-Z]\d

return-notification

simple

optional

(Character String - up to 60 characters)

Pattern is (['_A-Za-z0-9\-\+]+)(\.['_A-Za-z0-9\-\+]+)*@([A-Za-z0-9-]+)(\.[A-Za-z0-9-]+)*(\.[A-Za-z]{2,5})

The email address that an on-delivery notification will be sent to when the return shipment is delivered.

pre-authorized-payment

complex

optional

Supplier Account providers can pre-authorize payment using the Supplier Account of their customer.

Important: This functionality can only be used by Canada Post approved Supplier Account providers, and only on a shipment where no manifest is required.

account-number

simple

required

(Character string – up to 16 characters)

The account number from which the amount will be withdrawn; will be used for reconciliation.

auth-code

simple

required

(Character string – up to 16 characters)

The authorization code from the supplier; will be used for reconciliation.

auth-timestamp

simple

required

The authorization date and time; will be used for reconciliation.

charge-amount

simple

required

The amount authorized in Canadian dollars; must match the total charges that will be calculated.

Format 9999999.99 (leading zeroes not required).

This is the top level of the XML structure.

Your unique transaction ID, if you supplied it in your request.

(Alphanumeric String - up to 32 letters/digits)

Contained within shipment-info.

A unique identifier for the shipment. This can be used in any future calls to Transmit Shipments to indicate that this shipment is to be excluded from the transmit.

(Character String - up to 14 Characters)

Valid values are

• created
• transmitted
• suspended

Contained within shipment-info.

Indicates the current status of the shipment.

(Numeric - up to 16 digits)

Contained within shipment-info.

This is the tracking PIN for the shipment. The tracking PIN can be used as input to other parcel web service calls such as Get Tracking Details.

(Numeric - up to 16 digits)

Contained within shipment-info

This is the tracking PIN for the return shipment. The tracking PIN can be used as input to other parcel web service calls such as Get Tracking Details.

The Canada Post Purchase Order number; only applicable and returned on a shipment where no manifest is required for proof of payment.

This structure will only be returned on a shipment where no manifest is required and where the provide-pricing-info element was set to true in the request.

It contains the same elements provided in the response to Get Shipment Price.

This structure will only be returned on a shipment where no manifest is required and was paid for by credit card or Supplier Account.

It contains the same elements provided in the response to Get Shipment Receipt.

Please note that the same dummy values are always returned in the sandbox environment (AA1111 for auth-code, for example).

Contained within shipment-info.

This structure represents a list of links to information relating to the shipment that was created.

Contained within links.

May occur 1 .. N times

(Note: the xml element link is designated as "Complex" because it contains a number of attributes, and according to the official XML definition, any element that contains attributes is Complex. The link element does not contain any sub-elements)

The links structure contains a number of link elements. These allow the user to separately retrieve the different results of the Create Shipment service, and/or invoke different additional functions on the shipment that was created. Each link represents a link to one of the web services.

See Provided endpoints for a description of link attributes.

Several links will be returned and each will have a unique rel type:

1. rel="self"

   This indicates that the link represents the shipment just created. In this case, the href attribute can be used as an endpoint to the Get Shipment service for the shipment just created. (See Get Shipment for information on how to invoke that service). As the Get Shipment service returns all the same information as the Create Shipment service, it can be used to re-generate (at a later time) all the information provided as part of the Create Shipment

   The href attribute can also be used to delete the shipment (via an invocation of the Void Shipment service - See Void Shipment for information on how to invoke that service).

   The media-type attribute will indicate the version of the XML format to be followed when calling either the Get Shipment or Transmit Shipments service.

2. rel = "label"

   This indicates that the link represents one of the labels rendered as part of the Create Shipment process. In this case, the href attribute is an endpoint to the Get Artifact service for that label. (See Get Artifact for information on how to invoke that service). The media-type attribute will indicate the format of the graphics file (PDF or ZPL).

   Note, for links of type rel="label", the additional attribute index="n" (e.g. index="1") is also required. This accommodates the situation where a multi-page label is spread over a number of separate artifacts (one for each page). In most cases, there will be only one page, so index="1" will be used.

3. rel = "returnLabel"

   This indicates that the link represents the return label rendered as part of the Create Shipment process. In this case, the href attribute is an endpoint to the Get Artifact service for that label. (See Get Artifact for information on how to invoke that service). The media-type attribute will indicate the format of the graphics file (PDF or ZPL).

4. rel = "commercialInvoice"

   This only exists in the case of a US or International shipment where a commercial invoice is required to show to border customs.

   This indicates that the link represents the commercial invoice rendered as part of the Create Shipment process. In this case, the href attribute is an endpoint to the Get Artifact service for that label. (See the section Get Artifact for information on how to invoke that service). The media-type attribute will indicate the format of the graphics file (PDF or ZPL).

5. rel = "details"

   This indicates that the link represents additional details that were created as part of the Create Shipment process. In this case, the href attribute is an endpoint to the Get Shipment Details service to retrieve that information. (See Get Shipment Details for information on how to invoke that service). The media-type attribute will indicate the version of the XML format to be followed when calling the Get Shipment Details service.

6. rel = "price"

   This indicates that the link represents a price estimation generated as part of the Create Shipment process. In this case, the href attribute is an endpoint to the Get Shipment Price service to retrieve that information. (See Get Shipment Price for information on how to invoke that service). The media-type attribute will indicate the version of the XML format to be followed when calling the Get Shipment Price service. Not returned when provide-pricing-info was set to true in the request.

7. rel="group"

   This indicates that the link represents the group that the shipment was created under as part of the Create Shipment process. In this case, the href attribute is an endpoint to the Get Shipments service to retrieve that information. (See Get Shipments for information on how to invoke that service). The media-type attribute will indicate the version of the XML format to be followed when calling the Get Shipments service.

8. rel="receipt"

   This link is used to access a credit card receipt that was generated by a Create Shipment process where no manifest is required for proof of payment (See Get Shipment Receipt for information on how to obtain the receipt). The media-type attribute indicates the version of the XML that will be returned.

   Not returned when provide-receipt-info was set to true in the request.

9. rel="refund"

   This link is used to request the refund of a shipment where no manifest is required. A refund can be issued if you have printed a label that you are not going to use, such one that has become spoiled or damaged. See Request Shipment Refund for details on how to request a refund. This link is only returned on shipment where no manifest is required.

   In all of the above cases, the value of the media-type attribute should be included as an HTTP Accept header in any of the calls to other services pointed to by the href.

10. rel="publicLabel"

    This link is to un-authenticated URL to the label.

11. rel="publicKeyInfo"

    This link is used to request the detail about the public label (expiry date and potentially QR code, if requested)

1156

Address Line 1 is a mandatory field.

1157

City is mandatory when shipping to Canada or USA.

1159

Province is mandatory when shipping to Canada, and State is mandatory when shipping to USA.

1459

The Reason for Export code value is not valid (Note: As of April 2016, gift is no longer valid).

1702

The Contract Number is not associated to the Mailed on Behalf of Customer Number in the CPC accounting system on the mailing date.

1711

Please select a different Method of Payment. Can only be creditcard or account.

1719

The coverage amount cannot exceed the total value of your goods, up to the maximum allowable for the product and country.

7230

The Deliver to Post Office option is not allowed in Quick Ship mode because it requires complete recipient name and address information.

7282

At least one of Recipient Name or Company Name is required per Customs regulations.

9186

Only one of shipping-point-id or requested-shipping-point 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.