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