Rating

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

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

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-v3+xml (Note: */* in place of the header value will return an error)

Content-Type

application/vnd.cpc.ship.rate-v3+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-v3”>
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.

  • "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

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

See Provided endpoints

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

(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)
Indicates the cost for a step size. E.g. 75 cents for each step size ($100) of coverage.

included-amount

simple

(5.2 digits e.g. 99999.99 pattern)
Indicates how much is covered by base service. E.g. the first $100 of coverage is included.

max-value

simple

(5.2 digits e.g. 99999.99 pattern)
Indicates the maximum option-amount.  E.g. $5000 maximum coverage.

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.

Diagram of XML Response to Get Rates
Diagram of XML Response to Get Rates

Message diagram

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-v3">
<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-v3+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-v3+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-v3+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-v3+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>