Developer Program

Ready to join the Developer Program? Join NOW FREE

Resources

Rating

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

Discover Services – REST

Summary

Name:	Discover Services
Reason to Call:	To discover the list of postal services that can be used for a given destination country, customer, contract, origin and/or destination postal code.
Input:	Destination Country
Output:	Service links and descriptions
Version history:	Release notes

Discover Services – Summary of Service

Request Details

Request – Structure for Discover Services

Endpoint

GET https://XX/rs/ship/service?country={country code}&contract={contract-id}&origpc={origin-postal-code}&destpc={destination-postal-code}
Replace...	With...
XX (Development)	ct.soa-gw.canadapost.ca
XX (Production)	soa-gw.canadapost.ca
{country code}	the desired 2-character country code
{contract-id}	The Canada Post contract number

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)
Authorization	Basic {Base64 encoding of userid:password}
Accept-language	en-CA or fr-CA

Body

None

Query String

If no search parameters are provided, all domestic, U.S. and international services accessible without a contract will be listed. The following parameters can be provided in the request to refine the response.

Query Parameter	Optional or required	Description
country	optional	If the country-code is provided, only services suitable for sending items to the provided country will be returned.
contract	optional	If the contract-id is provided, the response will also include restricted services accessible with that contract

Request – Elements

The Discover Services service does not require any input XML data.

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.

Element Name	Type	Description
services	complex	The list of services that can be used for the specified query parameters.
service	complex	Contains details for a service.
service-code	simple	The code used to request the service.
service-name	simple	The name of the service in the requested language.
link	simple	Link for Get Service. (See Provided endpoints)

Response – XML Diagram

The following diagram shows the high level response. Either the services structure (a valid response) or the messages structure (error response) will be returned.

Diagram of XML Response to Discover Services

Response – Possible Error Responses

The messages below could be returned for incorrect query parameter values.

Code	Description
2550	The contract number is not valid.
7266	Postal Code must be in format A9A or A9A9A9.
8534	A valid destination country must be supplied.
9194	origin-postal-code must also be provided when destination-postal-code is provided.

See HTTP status codes for general error handling information.

Examples

Sample REST XML Request – Discover Services

Get https://XX/rs/ship/service?country=JP
Accept: application/vnd.cpc.ship.rate-v4+xml

Sample REST XML Response – Discover Services


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

 
<services>
         <service-code>INT.XP</service-code>

        <service-name>Xpresspost International</service-name>

        <link rel="service" href="https://XX/rs/ship/service/INT.XP?country=JP" media-type="application/vnd.cpc.ship.rate-v4+xml"></link>

      
      </service>

      <service>
         <service-code>INT.SP.SURF</service-code>

        <service-name>Small Packet International Surface</service-name>

        <link rel="service" href="https://XX/rs/ship/service/INT.SP.SURF?country=JP" media-type="application/vnd.cpc.ship.rate-v4+xml"></link>

      
      </service>

      <service>
         <service-code>INT.SP.AIR</service-code>

        <service-name>Small Packet International Air</service-name>

        <link rel="service" href="https://XX/rs/ship/service/INT.SP.AIR?country=JP" media-type="application/vnd.cpc.ship.rate-v4+xml"></link>

      
</services>

Sign in