Code Samples for E-commerce Platforms:  REST  |  SOAP

E-commerce Platforms

Integrate our web services into your platform and offer them to your customers

Legend

i Only e-commerce platforms that have been approved by Canada Post can make these web service calls. To become a platform with Canada Post, sign in to the Developer Program home page and select Become a Platform.

number

Read Getting Started to find out how to sign up, get your API keys and more.

number

For essential information common to all our web services, read the Fundamentals of Canada Post Web Services:  REST  |  SOAP

Service summary

Use the platform web services if you are an e-commerce platform and want to register your merchant customers with Canada Post so that they can ship with Canada Post from your platform.

Registering a merchant with Canada Post

The diagram below provides an overview of how to sign up merchants for web services.

Registering a merchant with Canada Post

Registering a merchant with Canada Post

Platform services

Platform services are provided through the following calls.

  1. Get Merchant Registration Token
    REST   |    SOAP
    Use this call to get a unique registration token (token-id) required to launch a merchant into the Canada Post sign-up process.
  2. Get Merchant Registration Info
    REST   |    SOAP
    This call returns the merchant information such as their Canada Post customer number and the username and password required for using web services. You need this to information to perform web service shipping transactions for the merchant.

Programming details

  1. When one of your merchant users wants to ship using Canada Post and is prepared to proceed with the Canada Post registration process, using your own authenticated browser session:
    • Call the Canada Post web service Get Merchant Registration Token using the appropriate endpoint:
      • REST: POST https://soa-gw.canadapost.ca/ot/token
      • SOAP: https://soa-gw.canadapost.ca/ot/soap/merchant/registration
    • Associate the response to this request with your own unique identification of the merchant on your system.

    Note: The token-id is only valid for 30 minutes—starting when it is issued and including the time a merchant takes to register with Canada Post.

  2. Post the following fields to this URL to initiate a Canada Post registration session:

    Live environment: https://www.canadapost-postescanada.ca/information/app/drc/merchant

    Testing environment: https://www.canadapost-postescanada.ca/information/app/drc/testMerchant

    Mandatory Optional
    • return-url *
      (for call-back to your system)
    • token-id
      (to refer to the interested user)
    • platform-id
      (your customer number)
    • first-name
    • last-name
    • address-line-1
    • prov-state
    • postal-zip-code
    • country-code
    • email
    • city

    *Your URL must be complete—nothing will be appended to it on the Canada Post side.

  3. We will redirect to the page specified in your return-url. We will pass the following 2 query parameters with a GET to the redirected page.
    • token-id
    • registration-status (will be one of: SUCCESS, CANCELLED, BAD_REQUEST, UNEXPECTED_ERROR, UNAUTHORIZED and SERVICE_UNAVAILABLE)
  4. Provide a completion status message to your merchant.
  5. If registration-status is OK, proceed to the next step. If Cancelled, please let the merchant know that you will be unable to submit requests on their behalf until they accept the terms and conditions, but their relationship with Canada Post remains in effect. If other, then an error occurred; please try again later.
  6. Trade the token for merchant credentials by calling the Canada Post web service Get Merchant Registration Info using the appropriate endpoint:
    • REST: GET https://soa-gw.canadapost.ca/ot/token/{token-id}
    • SOAP: https://soa-gw.canadapost.ca/ot/soap/merchant/registration
  7. Associate the response to this request with your own unique identification of the merchant on your system. Save the merchant API key (username and password) to your server. The token-id is no longer useful but the merchant username and password will allow you to submit web services on behalf of the registered merchant.
  8. Test the merchant credentials by calling a non-chargeable web service (such as Get Rates or Get Customer Information) to test that the credentials work end-to-end.
  9. Pass the merchant’s ongoing HTTPS requests through your server, and add your platform key and the appropriate merchant key.

Request element essentials

  • Calls made for a merchant are only accepted by the production endpoints. Authorization error AA002 (wrong environment) will be returned for calls made with merchant credentials to the test environment.
  • Protect the security of your platform API key (username and password) by keeping it on your server side.
  • Before signing up merchants, consider checking that their account with you is in good standing.
  • Note the following about customer numbers:
    • Even though you are submitting calls on behalf of a merchant, the merchant customer number is placed in the mailed-by element. The mailed on behalf of element (MOBO) is a repeat of the merchant customer number (unless the merchant has a previously arranged agreement with another customer).
    • Enter your platform customer number in the request element named platform-id.
    • The platform-id must be the same customer number that you used to register the merchant; that is, the customer number that owns the web service username that authenticated the registration request.

Making SOAP calls to web services on behalf of merchants

For SOAP calls, place the <platform-id> element at the top level of each request i.e., at the same level as locale or mailed-by.

Making REST calls to web services on behalf of merchants

Every time you make a REST call on behalf of a merchant, you must include Platform-Id in the HTTP header.

In addition, if the URL of the REST request includes mailed-by customer, you must also append a hyphen and your platform-id to the mailed-by customer number. Failure to do so will result in an authentication error. This approach keeps data for the same merchant separate over multiple platforms. See the list of affected REST calls below.

REST example calls for platforms

A request made on your own behalf would look like this:

POST https://soa-gw.canadapost.ca/rs/1234567/1234567/shipment
HTTP Header Variable Value

Accept

application/vnd.cpc.shipment-v2+xml

Content-Type

application/vnd.cpc.shipment-v2+xml

Authorization

Basic {Base64 encoding of userid:password}

Accept-language

en-CA or fr-CA

A request made on behalf of a merchant would look like this:

POST https:// soa-gw.canadapost.ca/rs/1111111-1234567/1111111/shipment
HTTP Header Variable Value

Accept

application/vnd.cpc.shipment-v2+xml

Content-Type

application/vnd.cpc.shipment-v2+xml

Authorization

Basic {Base64 encoding of userid:password}

Accept-language

en-CA or fr-CA

Platform-id

1234567

  • Where 1111111 = the customer-number of the merchant
  • Where 1234567 = your customer number/platform-id
  • Where username = the merchant-username.
  • Where password = the merchant-password

The above were returned to you by the Get Merchant Registration Info web service and then stored on your system.

Note: You can still use the <group-id> field for grouping user shipments within your platform. Overlap of group-id values from other platforms is not a concern since the mailed-by identifier is a top-level separator.

REST request URLs that include mailed-by customer

The following calls require you to append a hyphen and your platform-id to the mailed-by customer number.

Shipping
Create Shipment
Get Groups
Get Shipment
Get Shipment Details
Get Shipment Price
Get Shipments
Void Shipment
Manifest
Transmit Shipments
Get Manifest
Get Manifests
Get Manifest Details
Non-Contract Shipping
Create Non-Contract Shipment
Get Non-Contract Shipment Receipt
Get Non-Contract Shipment Details
Get Non-Contract Shipments
Get Non-Contract Shipment
Returns
Create Authorized Returns
Create Open Return Template
Get Open Return Template
Delete Open Return Template
Get Open Return Templates
Customer Information
Get Customer Information
Get MOBO Customer Information

Dimensions

Dimensions (i.e. parcel length, width, and height) will provide your merchants with more accurate shipping costs. If dimensions are not passed to the Canada Post API, the merchant may be subject to additional charges above the price quoted based on weight alone. This occurs in cases of large box sizes with light contents.

Warning message for your merchants

We recommend you display the following warning to your merchants before they print a label or transmit a manifest:

Note the information provided to Canada Post is subject to verification. Therefore, if Items actually presented to Canada Post are inconsistent with the information provided (incorrect category, volumes, weights, preparation; missing surcharges etc.) prices may be adjusted and/or additional charges added as provided for in the Customer's Agreement with Canada Post. The Customer agrees that such price changes are to be automatically applied to the Customer through the same method of payment chosen by the Customer for the Order (credit card or Canada Post account), with no further notice required to the Customer from Canada Post.

Error messages

Code Description Meaning and Mitigation

AA002

The username and password of the request do not match the endpoint.
E.g. development key against production endpoint or vice versa.

Merchant requests cannot be sent to the development environment.

AA005

Platform id not specified

The platform-id header variable is empty or not present in the URL. This should only be encountered during platform development coding.

AA006

Platform not authorized

The platform-id specified is incorrect or the merchant subsequently came to Canada Post and intentionally revoked permission for your platform to submit transactions on its behalf. The merchant could be asked to revalidate with Canada Post if they want to re-establish their relationship with the platform.

This error would also occur if the online owner of the platform key voluntarily withdrew from the Developer Program.

In rare cases, Canada Post may have deactivated the entire platform status due to fraud or misuse concerns.

AA007

Registration requests cannot be made until the platform status is approved

The request for platform status has been made but Canada Post has not yet approved the request.

In rare cases, Canada Post may have deactivated the entire platform status due to fraud or misuse concerns.

AA008

Only authorized platforms may access registration services.

An attempt was made to access the registration service without applying to Canada Post to become a platform.

AA009

Key type not valid for platform-id

If a key other than a merchant key is being used to authenticate a transaction, the platform-id field must not be specified. Remove the platform-id field from the request even if you are a registered platform. Only requests done on behalf of a merchant can specify the platform-id.

AA010

Incorrectly configured platform request

The platform-id in the header and the platform-id in the URL disagree. These values must match.