Rating

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

Get Rates – SOAP

Summary

Name: Get Rates
Reason to Call:

To get a list of services, prices and transit times for a shipment.

Input: Basic address and parcel information
Output: Service(s), price(s), transit time(s) and expected delivery date
Error Example: No services are appropriate for the shipment of the defined parcel. Validate the parcel criteria against product specifications.
Typical prior call: No directly related prior calls
Typical next call: Create Shipment or Create Non-Contract Shipment
Version history: Release notes

Call Details

WSDL: rating.wsdl
Endpoint (Development): https://ct.soa-gw.canadapost.ca/rs/soap/rating/v3*
Endpoint (Production): https://soa-gw.canadapost.ca/rs/soap/rating/v3
Namespace: http://www.canadapost.ca/ws/soap/ship/rate/v3
Operation: GetRates

*If you’re not a commercial customer of Canada Post with a contract, but you are developing a third-party shipping solution intended for commercial customers, please see important information about how to test contract shipping in our sandbox environment.

SOAP Body

This section describes the XML input elements to this service. For the hierarchical structure, see the XML diagram.

Get Rates – Request Elements
Element Name Type Required / Optional Description

get-rates-request

complex

required

The top level XML element for the request input information.

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.

mailing-scenario

complex

required

This is the overall XML structure for the request input information.

customer-number

simple

conditionally required

The customer number of the owner of the mail (mailed on behalf of customer).

(numeric  – up to 10 digits)

This element is required to obtain discounted rates for commercial customers and Solutions for Small Business members. It must be omitted to obtain counter (i.e., consumer) rates.

contract-id

simple

conditionally required

This element is required to obtain discounted rates for commercial customers when the customer-number element is provided. The contract-id element must be omitted for Solutions for Small Business members or general businesss users.

(numeric – up to 10 digits)

promo-code

simple

optional

If you have a promotional discount code, enter it here. The discount amount will be returned in the response under the adjustment structure.

quote-type

simple

optional

Either commercial or counter.

  • "commercial" will return the discounted price for the commercial customer or Solutions for Small Business member.
  • "counter" will return the regular price paid by consumers.

Defaults to "commercial" if not specified.

expected-mailing-date

simple

optional

The expected mailing date for the parcel.

This date is used in calculations of the expected delivery date, however all rate quotes are based on the current system date.

(YYYY-MM-DD date format)

options

complex

optional

Structure containing the list of options desired for the shipment.

option

complex

required

May occur  1 … 20 times.

Holds the option code and qualifier for a selected option.

option-code

simple

required

(10 alphanumeric)

Holds the Canada Post-specific option code

Valid values:
SO - Signature
COV - Coverage  (requires qualifier)
COD - COD (requires qualifier)
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

option-amount

simple

required depending on option-code

Required for COV – the amount of insurance to be purchased.

5.2 digits e.g. 99999.99

parcel-characteristics

complex

required

Details of the parcel such as weight, dimensions and appearance.

weight

simple

required

The weight of the parcel in kilograms.

(99.999)

Contained within parcel-characteristics.

dimensions

complex

optional

Details of the parcel dimensions in centimeters.

length 

simple

required

Longest dimension.

(3.1 digits e.g. 999.9 pattern)

width

simple

required

Second longest dimension.

(3.1 digits e.g. 999.9 pattern)

height

simple

required

Shortest dimension.

(3.1 digits e.g. 999.9 pattern)

unpackaged

simple

optional

true | false

  • defaults to "false"
  • true indicates that the parcel will be unpackaged (e.g. tires)

mailing-tube

simple

optional

true | false

  • defaults to "false"
  • true indicates that the object will be shipped in a mailing tube

oversized

simple

optional

true | false

  • defaults to "false"
  • true indicates that the object has oversized dimensions
  • automatically set correctly if dimensions are provided

services

complex

optional

Specifies the services to rate for this mailing scenario.

service-code

simple

required

May occur  1 … 20 times.

A specific service to be rated. If no instances of service-code are included in the request, all services applicable to the shipment and destination will be rated and returned.

Code Description
DOM.RP Regular Parcel
DOM.EP Expedited Parcel
DOM.XP Xpresspost
DOM.XP.CERT Xpresspost Certified
DOM.PC Priority
DOM.LIB Library Materials
USA.EP Expedited Parcel USA
USA.PW.ENV Priority Worldwide Envelope USA
USA.PW.PAK Priority Worldwide pak USA
USA.PW.PARCEL Priority Worldwide Parcel USA
USA.SP.AIR Small Packet USA Air
USA.TP Tracked Packet – USA
USA.TP.LVM Tracked Packet – USA (LVM)
(large volume mailers)
USA.XP Xpresspost USA
INT.XP Xpresspost International
INT.IP.AIR International Parcel Air
INT.IP.SURF International Parcel Surface
INT.PW.ENV Priority Worldwide Envelope Int’l
INT.PW.PAK Priority Worldwide pak Int’l
INT.PW.PARCEL Priority Worldwide parcel Int’l
INT.SP.AIR Small Packet International Air
INT.SP.SURF Small Packet International Surface
INT.TP Tracked Packet – International

origin-postal-code

simple

required

Postal Code from which the parcel will be sent.
Format ANANAN (only accepted with uppercase)

destination

complex

required

Defines the destination of the parcel.

domestic

complex

choice

Defines the destination in Canada.

postal-code

simple

required

The destination Postal Code.

Format ANANAN (only accepted with uppercase)

united-states

complex

choice

Defines destination in the United States.

zip-code

simple

required

Used when country code = US. Format is 5 digits or 5-4 (for extended Zip Codes)

E.g. 12345 or 12345-6789

international

complex

choice

Defines an international destination (destination other than the United States or Canada). Only one of international, us-destination or domestic can be specified.

country-code

simple

required

The destination country code. Standard 2-character country code (valid country code other than CA or US)

Request – XML Diagram

Response Details

Response – Elements

The following table describes the XML elements in the response to Get Rates. For the hierarchy of the response, see the XML diagram.

Get Rates – Response Elements
Element Name Type Description

get-rates-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.

price-quotes

complex

One or more price quotes depending on the number of postal services available or selected for the shipment.

price-quote

complex

Costs and delivery standards for one particular postal-service.

service-code

simple

The code for the mail service being quoted.

service-name

simple

Service name in preferred language.

price-details

complex

Contains the detailed breakdown of the costs for this shipment if sent using this service.

base

simple

Base cost of the shipment before taxes

taxes

complex

Contains details on taxes charged for this shipment if sent using this service. (Will not contain all three tax type elements at once.)

gst

simple

Goods and services tax.

pst

simple

Provincial sales tax.

hst

simple

Harmonized sales tax.

percent

attribute of HST, PST or GST

Indicates the percentage of the tax applied to the base amount.

due

simple

Total cost of the shipment if sent using this service including the cost of selected or required options, surcharges, discounts and taxes.

options

complex

This structure contains the options that were selected and will also show free options and the parcel characteristics of mailing tube, unpackaged or oversize if selected or warranted by dimensions.

option

complex

This structure contains details about a single option.

option-code

simple

The unique code for the option.

Structure to show additional details about the option if available.

option-name

simple

Option name in preferred language.

option-price

simple

Cost of this option for the current parcel.

qualifier

complex

Contains additional details about the option if available.

step-size

simple

Indicates the step size for additional step pricing. E.g. the amount of coverage purchased in one step such as $100.

step-cost

simple

Indicates the cost for a step size. E.g. 75 cents for each step size ($100) of coverage.

included-amount

simple

Indicates how much is covered by base service. E.g. the first $100 of coverage is included.

max-value

simple

Indicates the maximum option-amount. E.g. $5000 maximum coverage.

included

simple

Indicates that the option is included at no charge.

percent

simple

If the option is based on a percentage value the percentage will be returned.

adjustments

complex

Structure containing details of the adjustments to a price.

adjustment

complex

Structure containing details of an adjustment to a price.

adjustment-code

simple

Code identifying the adjustment.

AUTDISC – Automation discount
FUELSC – Fuel surcharge
NCNTGST – Non-contiguous state fee (applies to Priority Worldwide products sent to Alaska and Hawaii)
V1DISC – Solutions for Small Business savings
PROMODISC – Promotional discount (if the promo code is invalid or expired, the discount amount will show as zero under adjustment-cost)
PLATFMDISC – Discount for using an e-commerce platform
NEWREGDISC – Discount for joining the Developer Program
SAADJ – Service area adjustment (rate adjustment up or down for specific source and destination postal code combinations)

adjustment-name

simple

Adjustment name in preferred language.

adjustment-cost

simple

Amount of the adjustment in dollars and cents.

qualifier

complex

Contains the qualifier for the adjustment if applicable.

percent

simple

If the adjustment is based on a percentage value the percentage will be returned. E.g. fuel surcharge

weight-details

complex

Will be empty if dimensions were not provided or actual parcel weight exceeds standard density weight for the dimensions.

cubed-weight

simple

The volumetric equivalent of the actual weight (VE) of the package. VE is not a unit of measure, a mass or a volume. It allows for more accurate pricing of an item given its weight and the space it occupies.

service-standard

complex

Contains details about package delivery if the quoted service is selected.

am-delivery

simple

true | false

Indicates whether a.m. delivery is defined as part of the service standard for this service.

guaranteed-delivery

simple

true | false

Indicates if the delivery date is guaranteed.

expected-transit-time

simple

Indicates the number of days from drop-off or pickup to 1st delivery attempt.

expected-delivery-date

simple

The estimated date of delivery, starting from the expected mailing-date.

Response – XML Diagram

Get Rates – Structure of the XML Response
Get Rates – Structure of the XML Response

Response – Possible Error Responses

The response to error conditions for this web service follows the standard SOAP error response approach used for all Canada Post web services. For more information, see SOAP Fundamentals of Canada Post Web Services.

Examples

Sample SOAP XML Request – Get Rates

<get-rates-request>
<mailing-scenario>
<customer-number>1111111</customer-number>
<contract-id>12345678</contract-id>
<parcel-characteristics>
<weight>1</weight>
</parcel-characteristics>
<services>
<service-code>DOM.XP</service-code>
</services>
<origin-postal-code>V6B4A2</origin-postal-code>
<destination>
<domestic>
<postal-code>J0E1X0</postal-code>
</domestic>
</destination>
</mailing-scenario>
</get-rates-request>

Sample SOAP XML Response – Get Rates

<get-rates-response>
<price-quotes>
<price-quote>
<service-code>DOM.XP</service-code>
<service-name>Xpresspost</service-name>
<price-details>
<base>24.09</base>
<taxes>
<gstpercent="5.0">1.32</gst>
<pst>0.00</pst>
<hst>0.00</hst>
</taxes>
<due>27.73</due>
<options>
<option>
<option-code>DC</option-code>
<option-name>Delivery confirmation</option-name>
<option-price>0</option-price>
</option>
</options>
<adjustments>
<adjustment>
<adjustment-code>AUTDISC</adjustment-code>
<adjustment-name>Automation discount</adjustment-name>
<adjustment-cost>-0.72</adjustment-cost>
<qualifier>
<percent>3.000</percent>
</qualifier>
</adjustment>
<adjustment>
<adjustment-code>FUELSC</adjustment-code>
<adjustment-name>Fuel surcharge</adjustment-name>
<adjustment-cost>3.04</adjustment-cost>
<qualifier>
<percent>13.0</percent>
</qualifier>
</adjustment>
</adjustments>
</price-details>
<weight-details></weight-details>
<service-standard>
<am-delivery>false</am-delivery>
<guaranteed-delivery>true</guaranteed-delivery>
<expected-transit-time>3</expected-transit-time>
<expected-delivery-date>2012-04-19</expected-delivery-date>
</service-standard>
</price-quote>
</price-quotes>
</get-rates-response>