Rating
Get Rates – REST
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 |
Get Rates – Summary of Service
Request Details
Request – Structure for Get Rates
Endpoint
POST https://XX/rs/ship/price |
|
|---|---|
| Replace... | With... |
XX (Development) |
ct.soa-gw.canadapost.ca* |
XX (Production) |
soa-gw.canadapost.ca |
*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.
HTTP Headers
HTTP Header Variable |
Value |
|---|---|
Accept |
application/vnd.cpc.ship.rate-v4+xml (Note: */* in place of the header value will return an error) |
Content-Type |
application/vnd.cpc.ship.rate-v4+xml (Note: */* in place of the header value will return an error) |
Authorization |
Basic {Base64 encoding of userid:password} |
Accept-language |
en-CA or fr-CA |
Body
<?xml version="1.0" encoding="utf-8"?>
<mailing-scenario xmlns=”http://www.canadapost.ca/ws/ship/rate-v4”>
xxx
</mailing-scenario>
Request – Elements
This section describes the XML elements of this service. The exact hierarchical structure of the XML inputs is shown in a diagram below this table.
| Element Name | Type | Required / Optional | Description | ||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
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
The following is the hierarchical structure of the XML to be used for providing the shipping input information.
Response Details
Response – Elements
The following table describes the XML fields in the response. For a detailed view of the hierarchy of the response, see the diagram below.
| Response Elements | ||
|---|---|---|
| Element Name | Type | Description |
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-link |
simple |
|
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 |
(numeric 99999.99) 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 |
(numeric 99999.99) Goods and services tax. |
pst |
simple |
Provincial sales tax. |
hst |
simple |
(numeric 99999.99) Harmonized sales tax. |
percent |
attribute of HST, PST or GST |
numeric 999.99 value 1 to 100 Indicates the percentage of the tax applied to the base amount. |
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 |
(9999.99 numeric) Amount of the adjustment in dollars and cents. |
qualifier |
complex |
Contains the qualifier for the adjustment if applicable. |
percent |
simple |
numeric 999.99 value 1 to 100 If the adjustment is based on a percentage value the percentage will be returned. E.g. fuel surcharge |
due |
simple |
(numeric 99999.99) 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 |
(10 alphanumeric) 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 |
(5.2 digits e.g. 99999.99 pattern) Cost of this option for the current parcel. |
qualifier |
complex |
(12 alphanumeric) 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 |
(5.2 digits e.g. 99999.99 pattern) |
included-amount |
simple |
(5.2 digits e.g. 99999.99 pattern) |
max-value |
simple |
(5.2 digits e.g. 99999.99 pattern) |
included |
simple |
Indicates that the option is included at no charge. |
percent |
simple |
numeric 999.99 value 1 to 100 If the option is based on a percentage value the percentage will be returned. |
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 |
(99 numeric) Indicates the number of days from drop-off or pickup to 1st delivery attempt. |
expected-delivery-date |
simple |
(YYYY-MM-DD date format) The estimated date of delivery, starting from the expected mailing-date. |
Response – XML Diagram
The following diagrams show the response structure. Either price-quotes or messages (error response) will be returned.
Response – Possible Error Responses
A correctly structured request may receive a business rule validation error related to the validity of the parcel specifications and origin/destination or customer and contract selected. In this case, the HTTP error code will be 400 and there will be diagnostic message text in the preferred language (English or French).
| Code | Message |
|---|---|
1622 |
The expected-mailing-date must not be in the past. |
7050 |
The {0} option requires the {1} option. Please add the prerequisite or remove the option. |
9111 |
No services are appropriate for the shipment of the defined parcel. Validate the parcel criteria against product specifications. |
9112 |
The service {0} is not available for the specified country or customer/contract. |
For details, see Structure of the HTTP response.
Examples
Sample REST XML Request – Get Rates
<mailing-scenario xmlns="http://www.canadapost.ca/ws/ship/rate-v4">
<customer-number>1234567</customer-number>
<parcel-characteristics>
<weight>1</weight>
</parcel-characteristics>
<origin-postal-code>K2B8J6</origin-postal-code>
<destination>
<domestic>
<postal-code>J0E1X0</postal-code>
</domestic>
</destination>
</mailing-scenario>
Sample REST XML Response – Get Rates
<price-quotes>
<price-quote>
<service-code>DOM.EP</service-code>
<service-link rel="service" href="https://ct.soa-gw.canadapost.ca/rs/ship/service/DOM.EP?country=CA" media-type="application/vnd.cpc.ship.rate-v4+xml"></service-link>
<service-name>Expedited Parcel</service-name>
<price-details>
<base>9.59</base>
<taxes>
<gst>0.00</gst>
<pst>0</pst>
<hst>0</hst>
</taxes>
<due>10.21</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.29</adjustment-cost>
<qualifier>
<percent>3.000</percent>
</qualifier>
</adjustment>
<adjustment>
<adjustment-code>FUELSC</adjustment-code>
<adjustment-name>Fuel surcharge</adjustment-name>
<adjustment-cost>0.91</adjustment-cost>
<qualifier>
<percent>9.75</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>2</expected-transit-time>
<expected-delivery-date>2011-10-24</expected-delivery-date>
</service-standard>
</price-quote>
<price-quote>
<service-code>DOM.PC</service-code>
<service-link rel="service" href="https://ct.soa-gw.canadapost.ca/rs/ship/service/DOM.PC?country=CA" media-type="application/vnd.cpc.ship.rate-v4+xml"></service-link>
<service-name>Priority Courier</service-name>
<price-details>
<base>22.64</base>
<taxes>
<gst>0.00</gst>
<pst>0</pst>
<hst>0</hst>
</taxes>
<due>25.20</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.68</adjustment-cost>
<qualifier>
<percent>3.000</percent>
</qualifier>
</adjustment>
<adjustment>
<adjustment-code>FUELSC</adjustment-code>
<adjustment-name>Fuel surcharge</adjustment-name>
<adjustment-cost>3.24</adjustment-cost>
<qualifier>
<percent>14.75</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>1</expected-transit-time>
<expected-delivery-date>2011-10-21</expected-delivery-date>
</service-standard>
</price-quote>
<price-quote>
<service-code>DOM.RP</service-code>
<service-link rel="service" href="https://ct.soa-gw.canadapost.ca/rs/ship/service/DOM.RP?country=CA" media-type="application/vnd.cpc.ship.rate-v4+xml"></service-link>
<service-name>Regular Parcel</service-name>
<price-details>
<base>9.59</base>
<taxes>
<gst>0.00</gst>
<pst>0</pst>
<hst>0</hst>
</taxes>
<due>10.21</due>
<options>
<option>
<option-code>DC</option-code>
<option-name>Delivery confirmation</option-name>
<option-price>0</option-price>
<qualifier>
<included>true</included>
</qualifier>
</option>
</options>
<adjustments>
<adjustment>
<adjustment-code>AUTDISC</adjustment-code>
<adjustment-name>Automation discount</adjustment-name>
<adjustment-cost>-0.29</adjustment-cost>
<qualifier>
<percent>3.000</percent>
</qualifier>
</adjustment>
<adjustment>
<adjustment-code>FUELSC</adjustment-code>
<adjustment-name>Fuel surcharge</adjustment-name>
<adjustment-cost>0.91</adjustment-cost>
<qualifier>
<percent>9.75</percent>
</qualifier>
</adjustment>
</adjustments>
</price-details>
<weight-details></weight-details>
<service-standard>
<am-delivery>false</am-delivery>
<guaranteed-delivery>false</guaranteed-delivery>
<expected-transit-time>4</expected-transit-time>
<expected-delivery-date>2011-10-26</expected-delivery-date>
</service-standard>
</price-quote>
<price-quote>
<service-code>DOM.XP</service-code>
<service-link rel="service" href="https://ct.soa-gw.canadapost.ca/rs/ship/service/DOM.XP?country=CA" media-type="application/vnd.cpc.ship.rate-v4+xml"></service-link>
<service-name>Xpresspost</service-name>
<price-details>
<base>12.26</base>
<taxes>
<gst>0.00</gst>
<pst>0</pst>
<hst>0</hst>
</taxes>
<due>13.64</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.37</adjustment-cost>
<qualifier>
<percent>3.000</percent>
</qualifier>
</adjustment>
<adjustment>
<adjustment-code>FUELSC</adjustment-code>
<adjustment-name>Fuel surcharge</adjustment-name>
<adjustment-cost>1.75</adjustment-cost>
<qualifier>
<percent>14.75</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>2</expected-transit-time>
<expected-delivery-date>2011-10-24</expected-delivery-date>
</service-standard>
</price-quote>
</price-quotes>
