Register new merchants

What’s a platform?

A platform is an ecommerce or shipping solution that integrates Canada Post APIs to facilitate shipping for multiple merchants. In this ecosystem, the platform acts as the bridge between the merchant’s storefront and Canada Post’s logistics network.

Each platform is assigned a unique 10-digit platformId (customer number) by Canada Post. This ID allows Canada Post to:

• Validate the platform during the "punch-out" registration process
• Associate specific merchants with your platform for billing and reporting purposes
• Track the integration of commercial contracts and pre-negotiated rates

Important: Updated authentication requirements

To interact with our APIs securely, all platforms must now adhere to our updated authentication guide. This is a mandatory requirement to ensure that sensitive data remains protected.

Without proper authentication implementation, your platform won't be able to:

• Initiate the OAuth flow
• Make calls to the Rating, Shipping, or Tracking APIs on behalf of your users
• Renew secure tokens, which will lead to immediate service interruptions

To avoid integration delays, please review the authentication guide immediately to understand how to handle API Keys, OAuth 2.0 tokens, and request headers.

What’s expected from a platform?

Canada Post expects platforms to maintain a high standard of security and technical reliability to protect merchant data. Platforms must treat the merchant Production Secret and Test Secret as highly sensitive "master keys". These should be encrypted at rest (for example, AES-256) and never exposed in client-side logs.

Technical compliance

• Your returnUrl must be served over HTTPS.
• Your application must correctly parse the Form POST body sent by Canada Post upon successful merchant registration.
• The platform is responsible for generating and refreshing Bearer tokens for all subsequent API calls (Rating, Shipping, and so on).

Error handling

Platforms should distinguish between user-initiated cancellations and technical errors. If a registration fails, the platform should display user-friendly messages rather than raw API error codes.

Getting started

To begin onboarding merchants to your platform, make sure you complete a request to become a platform.

Prerequisites

Please note: To use our APIs, you must first have a valid Canada Post business account, which provides a customer number. Commercial customers typically have a formal commercial contract, which also provides a contract number and is billed to a credit account. Solutions for Small Business™ customers can access the API using their small business account number. Returns services are generally billed to the credit card on file in your profile or business account.

Once you have an account, here are the next steps to use the API:

1. Create a canadapost.ca user ID.
2. Join the Canada Post Developer Portal.
3. Get your production and test API credentials (API Key and API Secret).
4. Make sure your server has a dedicated returnUrl served over HTTPS. This endpoint must be configured to handle incoming HTTP POST data.
5. Develop the "punch-out" flow where your platform sends a POST request containing your platformId, returnUrl, and preferred language.

The “punch-out” registration process

The registration process is a "punch-out" integration. This means the merchant's journey begins on your platform but is completed within a Canada Post secure environment.

1. The merchant starts the registration process on the platform website.
2. The platform sends an HTTP POST request to the Canada Post onboarding endpoint. This request must include the platformId, returnUrl, and language.
3. Canada Post validates the platformId. If invalid, a browser error is displayed to the merchant.
4. The merchant signs in or creates a Canada Post business profile.
5. The merchant selects their default payment method, such as a credit card or a supplier account.
6. Canada Post creates the merchant's API credentials and associates their account with the platform in the billing system.
7. Canada Post redirects the merchant back to the platform's returnUrl.
8. The redirection includes a Form POST containing the merchant's new API keys, secrets, and payment configurations.

POST URL

POST https://www.canadapost-postescanada.ca/devonboarding-integrationdev/api/activation

HTTP POST elements explained

Initiate the registration process by sending an HTTP POST request to the endpoint URL specified above. Your request body must include the following parameters:

Post-registration message details

Upon successful registration, Canada Post performs a Form POST to your specified returnUrl. Your application should parse the following parameters from the request body:

Handling registration failures

It’s critical to distinguish between a user-initiated cancellation and a technical configuration error.

Logic-based failures

If the registration fails after the punch-out has started, Canada Post will append a query string parameter registration-status=failure to your returnUrl.

Initial validation failures

If the platformId provided in the initial POST is invalid or inactive, the merchant won’t reach the registration screens; instead, a browser error message will be displayed immediately by Canada Post.

Security best practice

Because these credentials grant access to the merchant's billing and shipping data, make sure your returnUrl is served over HTTPS and that the merchant-prd-client-secret is never exposed in client-side logs or browser consoles.

Sample POST for successful registration 

<!-- HTML -->
<form name="merchant-return"
	action="https://www.[returnUrl]/shipper/onboarding?session=1234567&status=success"
	method="post" type="hidden">
	<input type="hidden" name="customer-number" value="0007020811"/>
	<input type="hidden" name="merchant-prd-client-id" value="ae5213511a244779b68c8a38d90dded8"/>
	<input type="hidden" name="merchant-prd-client-secret" value="2989a6f7cc594aa687c9829932fe5624"/>
	<input type="hidden" name="merchant-test-client-id" value="ae5213511a244779b68c8a38d90dded8"/>
	<input type="hidden" name="merchant-test-client-secret" value="2989a6f7cc594aa687c9829932fe5624"/>
	<input type="hidden" name="credit-card" value="true"/>
	<input type="hidden" name="on-account" value="false"/>
</form>

Use cases

This section outlines typical commercial scenarios for using the Merchant Registration API.

Example 1

New merchant onboarding

A small business owner signs up for your ecommerce platform and needs to set up Canada Post shipping for the first time.

API requirement

The platform must initiate a punch-out POST request containing the platformId and a returnUrl.

Outcome

The merchant is redirected to Canada Post to create a profile, and upon success, the platform receives the merchant's new production API keys and customer number.

Example 2

Existing commercial account linkage

A large retailer with an existing Canada Post commercial contract wants to integrate their pre-negotiated rates into your platform.

API requirement

The merchant signs in during the punch-out process using their existing credentials.

Outcome

The API associates the merchant’s existing contract number with your platformId and returns the on-account: true flag, ensuring they’re billed to their credit account rather than a credit card.

Example 3

Payment method update

A merchant needs to switch their default shipping payment from a personal credit card to a corporate supplier account.

API requirement

The platform re-initiates the registration flow.

Outcome

The merchant selects a new payment method via the Canada Post interface, and the platform receives an updated payload with the credit-card or on-account status set to the new default.

Best practices

Example high-level flow

1. The merchant initiates registration via the platform.
2. The platform sends Form POST to the Canada Post onboarding endpoint.
3. Canada Post validates the Platform ID.
4. The merchant completes registration and selects their payment method.
5. Canada Post creates merchant credentials and associates the merchant with the platform.
6. The merchant is redirected back to the platform's returnUrl via an HTTP POST. The platform captures the payload, validates the registration status, and securely stores the API credentials.

Security best practices checklist

The "post-registration message" includes critical credentials that grant access to a merchant's Canada Post account.

Follow these steps to process the high-level flow securely:

1. Capture the merchant-prd-client-id and merchant-prd-client-secret from the incoming form parameters.
2. Confirm the platform association logic matches the platformId used to initiate the request.
3. Check the credit-card and on-account Booleans to set the merchant's billing profile in your UI.
4. If registration-status is failure, log the error and display a user-friendly message rather than raw API error codes.

Example REST calls for platforms

When making calls on behalf of a merchant, you must use a specific URL structure that identifies both the merchant and your platform.

Platform URL pattern

For the endpoints listed below, you must append your platform-id to the merchant's mailed-by-customer-number using a hyphen.

Pattern:

.../{mailedBy}-{platformId}/{mobo}/{resource}

Example request:

POST https://api.canadapost-postescanada.ca/prod/devportal-portaildesdeveloppeurs/shipping/v1/1111111-1234567/1111111/shipment

Please note: In the example above, 1111111 is the merchant’s customer number and 1234567 is your unique Platform ID.

Affected endpoints

The {customer-number}-{platformId} format is mandatory for the following categories:

• Shipping: Create/Get/Void Shipments, Shipment Details, and Pricing
• Manifesting: Transmit Shipments, Get Manifests/Details
• Returns: Create Authorized/Open Returns, Template Management
• Customer Information: Get Customer or MOBO Information

Implementation logic: Credentials management

It’s a best practice to treat the Production Secret and Test Secret as highly sensitive "master keys".

Production environment

Use merchant-prd-client-id and merchant-prd-client-secret for all live label generation and billing.

Test environment

Use merchant-test-client-id and merchant-test-client-secret for development and troubleshooting without impacting the merchant's live account.

Testing and troubleshooting

Developers must decide when to expose an error message directly to the end-user versus implementing a mitigation strategy to prevent the error.

Common errors and how to fix them

Before troubleshooting, review our list of common errors and their codes. Each entry includes the specific HTTP status code and the recommended mitigation action.

Example: A 9112 error ("Service not available") may indicate a configuration problem. The mitigation is to check the available services for the selected origin or destination.

API error response structure

API error responses typically return a 400 Bad Request (for input validation errors) or a 500 Internal Server Error (for unexpected issues). The response body will contain a structured error object with the following key elements:

• code: The specific alphanumeric error code (for example, 9111).
• message: A plain text description of the error.

Developer support

If you've implemented the recommended mitigation strategies and are still experiencing issues, please contact our developer support team.

Related links

For more information on existing integrations or to see how other solutions are featured, please refer to the Canada Post Partners Directory.