Rating
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/v4* |
| Endpoint (Production): | https://soa-gw.canadapost.ca/rs/soap/rating/v4 |
| Namespace: | http://www.canadapost.ca/ws/soap/ship/rate/v4 |
| 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 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.
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: |
||||||||||||||||||||||||||||||||||||
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
|
||||||||||||||||||||||||||||||||||||
mailing-tube |
simple |
optional |
true | false
|
||||||||||||||||||||||||||||||||||||
oversized |
simple |
optional |
true | false
|
||||||||||||||||||||||||||||||||||||
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.
|
||||||||||||||||||||||||||||||||||||
origin-postal-code |
simple |
required |
Postal Code from which the parcel will be sent. |
||||||||||||||||||||||||||||||||||||
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) |
||||||||||||||||||||||||||||||||||||
postal-code |
simple |
optional |
The Postal Code field can be provided if the customer would like to receive a Guaranteed date for a Kahala Posts Group (KPG) country. |
||||||||||||||||||||||||||||||||||||
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. |
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 |
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
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>
