create-non-contract-shipment-request

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

mailed-by

simple

required

(1-10 digit numeric)

The 10-digit customer number of the mailed-by customer.

If the number provided has fewer than 10 digits, the system will add leading zeros.

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.

non-contract-shipment

complex

required

The XML structure containing the input information for a shipment.

requested-shipping-point

Simple

Optional

(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 sending location (origin). It is used to determine the nearest post office, which is used for pricing.

This element is required if:

• Your shipment is not picked up by Canada Post at the postal code specified in the sender structure below (i.e., it is picked up at another location), or
• You deposit your shipment at a Canada Post location, in which case you must enter the postal code of that location. Look up the postal code using Find a Deposit Location.

delivery-spec

complex

required

This structure holds all information necessary to describe the delivery request (the shipment and its destination).

service-code

simple

required

This structure contains data about the sender and this data will appear in the "From" address of the label. Blank fields will be removed in the address formatting.

This is the Canada Post delivery service used for shipping the item.

Allowed to be any of:

sender

complex

required

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

Note: sender address must be domestic.

name

simple

optional

(Character String - up to characters)

Contact Name of the corresponding sender.

company

simple

required

(Character String - up to 44 characters)

Company name of the corresponding sender.

contact-phone

simple

Mandatory

(Character String - up to 25 characters)

Phone number of the sender.

address-details

complex

required

This structure contains the address data about the sender.

Blank fields will be removed when printed on shipping labels.

Note: sender address must be domestic.

 address-line-1

simple

required

(Character String - up to 44 characters)

Address line 1 of sender.

 address-line-2

simple

optional

(Character String - up to 44 characters)

Address line 2 of sender.

city

simple

required

(Character String - up to 40 characters)

City of sender.

prov-state

simple

required

(Character String - 2 characters)

Province of sender. 

Use standard Canadian province codes.

postal-zip-code

simple

conditionally
Required

(6-character alphanumeric)

Postal Code of sender.

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. Blank fields will be removed in the address formatting.

name

simple

conditionally required

(Character String - up to 44 characters)

Contact Name of the recipient.

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

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.

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 Info for the destination.

If present, this will be printed directly above address line 1.

client-voice-number

simple

conditionally required

(Character String - up to 25 characters)

Phone number of the recipient. Not required for domestic—will not appear on shipping label.

Required for destination when service is one of Expedited Parcel-USA, Xpresspost-USA, Xpresspost-International(USA.EP, USA.XP, INT.XP)

Also required for destination when the Deliver to Post Office option is used.

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

This structure contains the address data of the recipient.

Blank fields will be removed when printed on shipping labels.

address-line-1

simple

required

(Character String - up to 44 characters)

Address line 1 of destination.

address-line-2

simple

optional

(Character String - up to 44 characters)

Address line 2 of destination.

city

simple

conditionally required

(Character String - up to 40 characters)

Required for domestic and USAshipments but optional for international shipments.

prov-state

simple

conditionally required

(Character String - up to 20 characters)

Province or state of destination. Required for domestic and USA shipments but optional for international shipments.
Use:

• standard province code for provinces within Canada
• standard state code for U.S. states.

country-code

simple

required

(2-character valid country code)

Country code of destination.

postal-zip-code

simple

conditionally
required

Can be:

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

Required for domestic and USA destinations.

Postal Code or zip code of recipient.

options

complex

optional

This structure contains the information on any requested shipping options.

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.

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.

Required for some options such as insurance (COV) and COD.

Note: For COD, there is a $1,000 maximum (including shipping cost, if applicable) on COD shipments for Solutions for Small Business customers.

For COV, 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

conditionally required

Boolean – {true, false}

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

For the COD or COV option, the value must be
{true , false}

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

Note: For the COD option, this element is required and is used to indicate if COD amount includes the shipping cost or not.

Example:
true = COD amount includes shipping cost.
false = COD amount does not include shipping cost.

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.

This qualifier is available for any options that may require a 2nd qualifier.

Currently, the options requiring a 2nd qualifier are:

parcel-characteristics

complex

required

This structure describes the characteristics of the parcel e.g. weight

weight

simple

required

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

Total package weight in kg.

dimensions

complex

optional

This structure contains the physical dimensions of the parcel which are used to make a more accurate determination of the 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 may be derived. Value is in cm.

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.

document

simple

optional

{true, false}

Indicates whether the shipment is a document or not. (If omitted or "false", dimensions are required).

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

notification

complex

conditionally required

This structure 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 client wishes to receive an email notification on a shipment.

on-exception

simple

conditionally required

{true, false}

This element is required if the notification element exists.

Indicates whether client wishes 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 client wishes to receive an email notification on delivery.

preferences

complex

required

This structure contains a number of client preferences with respect to the printing of labels.

show-packing-instructions

simple

required

{true, false}

This element indicates whether packing instructions are to be rendered on the label or not.

show-postage-rate

simple

optional

{true, false}

This element indicates whether postal rate is to be shown on the label or not.

This only applies to U.S.A. and international shipments.

If the element is not present, the default value is false.

show-insured-value

simple

optional

{true, false}

This element indicates whether the insured value is to be shown on the label or not.

This only applies to U.S.A. and international shipments.

If the element is not present, the default value is false.

references

complex

optional

This structure contains reference fields that you assign. These alternate (possibly unique) identification numbers are assigned to the shipment for any purpose useful to you.

cost-centre

simple

optional

(Character String - up to 30 characters)

This is a user-defined value available 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

This structure 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)

Value must be

• CAD for Canadian Currency
• USD for US currency
• Other valid ISO currency code

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

This is the currency of the receiving country.

conversion-from-cad

simple

conditionally required

(Numeric field of pattern 3.6 i.e. 999.999999)

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

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.

reason-for-export

simple

conditionally required

(3 characters)

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

This is 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

other-reason

simple

optional

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

Conditionally Required

This is the reason for export, if the element reason-for-export is "other" to describe the reason for export.

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

conditionally required

Required if the corresponding customs parent element exists.

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

item

complex

required

May occur 1 … 500 times.

At least one instance of item must exist.

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

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

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.

sku

simple

optional

(Character String - up to 15 characters)

A customs sku number or sku name for the item

Note: Version 3 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.

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.

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.

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

country-of-origin

simple

optional

(2-character valid country code)

This is the country of origin of the corresponding item and should be provided 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)

This should be provided if the country-of-origin is Canada

The province of origin of the goods.

settlement-info

complex

optional

Structure containing elements related to payment or rating.

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.

Converted to uppercase.

For testing purposes, you can use the promo code DEVPROTEST in the development (sandbox) environment. It is valid for the following products:

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

create-non-contract-shipment-response

complex

The top level XML element for the response.

It will either contain the results of a successful completion or the error message structure.

non-contract-shipment-info

complex

The XML structure containing the results of a successful completion of the service.

shipment-id

simple

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

tracking-pin

simple

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

artifacts

complex

This structure contains a set of artifacts (labels) related to this shipment.

artifact

complex

This represents an individual artifact (label) for the shipment.

May occur 1 .. N times

(Note: the xml element artifact is designated as "Complex" because it contains a number of attributes; it does not contain any sub-elements.

This element will include an attribute type="XXX"
where XXX= the type of label that this artifact represents.

These are the possible values for this attribute:

• "label" – the primary shipping label
• "commercialInvoice" – only exists in the case of a U.S. or international shipment where a commercial invoice is required to show to border customs.

artifact-id

simple

A unique identifier for the label (artifact) that can be used in the request to Get Artifact to retrieve the label.

page-index

simple

Note: This element is always zero for PDF since PDF supports multiple pages. It is not required in requests to retrieve PDF documents.

1459

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

1719

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

7272

The Promotional Code is invalid (does not exist or is not applicable to the selected service).

7282

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

7289

The selected service is not valid for the specified customer and/or contract.

7322

The currency code is not a valid 3-digit ISO currency code (such as USD).