Rating

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

Get Service – REST

Summary

Name: Get Service
Reason to Call: To find out details for a given postal service such as the dimension and weight limits and the available options.
Input: Service with optional country
Output: Service description, options and restrictions
Typical Prior Call: Get Rates, Discover Services
Version history: Release notes
Get Service – Summary of Service

Get Service – Summary of Service

Request Details

Request – Structure for Get Service

Endpoint

Invoke the link from one of the prior calls where rel="service" (see Provided endpoints)

HTTP Headers

HTTP Header Variable

Value

Accept

from media-type in original link (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

None

Query String

There is one optional parameter for the query string:

Element Name Description

country

This parameter will fine tune the options if provided. For example, some countries support the signature option for Xpresspost™-International and some do not.

Note: we do not validate whether the shipping service you specified is a valid service for the country you provide. Therefore, even if the service is not offered for the country you specify, a list of the default options will still be returned.

Request – Elements

The Get Service service does not require any input XML data.

Response Details

Response – Elements

Element Name Type Description

service-code

simple

Service identifier.

service-name

simple

Description of service in the language of choice.

comment

simple

Coverage message stating the maximum amount of coverage included with this service (which can be none); only returned on a few U.S. and international services where additional coverage cannot be purchased.

Only applicable to schema version 2 and higher.

options

complex

List of options available/applicable to this service.

option

complex

One specific option.

option-code

simple

The code used to select the option in Get Rates or Create Shipment

option-name

simple

Option name in language of choice.

link

simple

Link for Get Option. See Provided endpoints

mandatory

simple

True | False

Indicates whether this option is mandatory for the service.

qualifier-required

simple

True | False

True indicates that this option if selected must include a qualifier on the option. This is true for insurance (COV) and collect on delivery (COD) options.

qualifier-max

simple

Numeric – indicates the maximum value of the qualifier for this service. The maximum value of a qualifier may differ between services. This is specific to the insurance (COV) option.

restrictions

complex

Details the weight and size restrictions of parcels shipped via this service.

weight-restriction

complex

Details the weight restrictions of items shipped via this service.

min

attribute on weight-restriction

Minimum weight in grams.

max

attribute on weight-restriction

Maximum weight in grams that can be sent using this service.

dimensional-restrictions

complex

Details the dimension restrictions of items shipped via this service

length

Complex

Specifies the dimension range of the longest dimension of an item in cm.

width

Complex

Specifies the dimension range of the second longest dimension of an item in cm.

height

Complex

Specifies the dimension range of the shortest dimension of an item in cm.

min

attribute on length, width and height

Minimum measurement in centimetres allowed for the dimension.

max

attribute on length, width and height

Maximum measurement in centimetres allowed for the dimension.

length-plus-girth-max

Simple

Maximum calculated value of length + 2*width + 2*height in cm.

length-height-width-sum-max

Simple

Maximum value of length + width + height in cm.

oversize-limit

Simple

If any dimension exceeds this limit an oversize fee will apply to the shipment (cm).

density-factor

Simple

Standard density factor used to calculate volumetric equivalent of actual weight (VE).
Note: Canada Post can use another factor to calculate the volumetric equivalent, depending on your parcels agreement.

can-ship-in-mailing-tube

simple

True | False

True indicates that parcels shipped with this service can be shipped in a mailing tube (option CYL can be used).

can-ship-unpackaged

Simple

True | False

True indicates that parcels shipped with this service can be shipped unpackaged (option UP can be used).

allowed-as-return-service

Simple

True | False

True indicates that this service can be used in the return-spec of a Create Shipment request.

Response – XML Diagram

The following is the hierarchical structure of the XML to be used for providing the service details. Either the service response (valid response) or the messages response (error response) will be returned.

Diagram of XML Response to Get Service
Diagram of XML Response to Get Service

Response – Possible Error Responses

No errors are expected for invocation of this service from a provided link. If this service is constructed, the following error could occur:

Code Description
8534 A valid destination country must be supplied.

See HTTP status codes for general error handling information.

Examples

Sample REST XML Request – Get Service

GET http://cpc.ca/rs/shipping/service/INT.XP?country=JP
Accept: application/vnd.cpc.ship.rate-v3+xml

Sample REST XML Response – Get Service

HTTP/1.1 200 OK
Content-Type:application/vnd.cpc.ship.rate-v3+xml

<service>
<service-code>INT.XP</service-code>
<service-name>Xpresspost International</service-name>
<options>
<option>
<option-code>COV</option-code>
<option-name>Coverage</option-name>
<link rel="option" href="https://XX/rs/ship/option/COV" media-type="application/vnd.cpc.ship.rate-v3+xml"></link>
<mandatory>false</mandatory>
<qualifier-required>true</qualifier-required>
<qualifier-max>1000</qualifier-max>
</option>
<option>
<option-code>DC</option-code>
<option-name>Delivery confirmation</option-name>
<link rel="option" href="https://XX/rs/ship/option/DC" media-type="application/vnd.cpc.ship.rate-v3+xml"></link>
<mandatory>true</mandatory>
<qualifier-required>false</qualifier-required>
</option>
<option>
<option-code>RASE</option-code>
<option-name>Return at sender's expense</option-name>
<link rel="option" href="https://XX/rs/ship/option/RASE" media-type="application/vnd.cpc.ship.rate-v3+xml"></link>
<mandatory>true</mandatory>
<qualifier-required>false</qualifier-required>
</option>
</options>
<restrictions>
<weight-restriction min="0" max="30000"></weight-restriction>
<dimensional-restrictions>
<length min="0.1" max="150"></length>
<width min="0.1" max="150"></width>
<height min="0.1" max="150"></height>
<length-plus-girth-max>300</length-plus-girth-max>
<oversize-limit>100</oversize-limit>
</dimensional-restrictions>
<density-factor>6000</density-factor>
<can-ship-in-mailing-tube>true</can-ship-in-mailing-tube>
<can-ship-unpackaged>false</can-ship-unpackaged>
<allowed-as-return-service>false</allowed-as-return-service>
</restrictions>
</service>