Developer Program

Ready to join the Developer Program? Join NOW FREE

Resources

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

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.

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 + 2width + 2height 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

View full-size image

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-v4+xml

Sample REST XML Response – Get Service


  HTTP/1.1  200 OK

    Content-Type:application/vnd.cpc.ship.rate-v4+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-v4+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-v4+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-v4+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>

Sign in