# Canada Post

[Canada Post](http://www.canadapost.ca) offers both domestic and international shipping services for via ShipStation API for Canada Post account holders.

This guide provides developers with the details needed to build Canada Post shipping capabilities into your ShipStation API workflows.

If you are using or plan to use the Canada Post services included with ShipStation API, rather than connecting your own Canada Post account, see our [Canada Post from ShipStation guide](/apis/shipengine/docs/carriers/canadapost-from-shipengine).

## Requirements

| Property | Type | Required? | Description |
|  --- | --- | --- | --- |
| `nickname` | *string* | **required** | A nickname to identify this account in ShipStation API. |
| `username` | *string* | **required** | Your Canada Post account username. |
| `password` | *string* | **required** | Your Canada Post account password. |


### Connection Requirements

* You must have an active Commercial or Small Business account with Canada Post.
* To connect a Canada Post Commercial account, you must have created a Business Profile in Canada Post that uses your commercial contract number.


### Shipping Requirements

* Commercial accounts must manifest each days shipments and provide a printed copy of the manifest to the Canada Post driver or representative. Failure to manifest shipments may result in additional monthly invoice fees. (Small Business accounts have no manifest requirements.)


## Connect Account

You can connect a Canada Post account using the POST method to the `/v1/connections/carriers/` endpoint, or via the ShipStation API Dashboard.

For instructions on connecting via the dashboard, review our [Canada Post help article](https://help.shipengine.com/hc/en-us/articles/4406863384091).

### Connect via Endpoint

`carrier_name`: `canada_post`

**POST /v1/connections/carriers/:carrier_name**

Sample request:


```http
POST /v1/connections/carriers/canada_post HTTP/1.1
Host: api.shipengine.com
API-Key: __YOUR_API_KEY_HERE__
Content-Type: application/json

{
  "nickname": "My Canada Post account",
  "username": "123456789",
  "password": "pa55word"
}
```

A successful connection will return a response with the `carrier_id`, which you'll use for any requests for this account going forward.

## Rates

Canada Post supports [rate shopping](/apis/shipengine/docs/rates/rates) with ShipStation API.

## Service Details

Available Canada Post services are provided below. Please note that carriers may update their available services at any time. To ensure you are always using valid services, you can use the [list carrier services](/apis/shipengine/docs/reference/list-carrier-services) endpoint at any time.

### Domestic Services

| Service | API Code |
|  --- | --- |
| Regular Parcel (Carbon Neutral) | `regular_parcel` |
| Expedited Parcel (Carbon Neutral) | `expedited_parcel` |
| Xpresspost | `xpresspost` |
| Xpresspost Certified | `xpresspost_certified` |
| Priority | `priority` |
| Library Books | `library_books` |


### International Services

"USA" services ship from Canada to the US only.

| Service | API Code |
|  --- | --- |
| Expedited Parcel USA | `expedited_parcel_usa` |
| Priority Worldwide Envelope USA | `priority_worldwide_envelope_usa` |
| Priority Worldwide pak USA | `priority_worldwide_pak_usa` |
| Priority Worldwide Parcel USA | `priority_worldwide_parcel_usa` |
| Small Packet Air - USA | `small_packet_air_usa` |
| Tracked Packet - USA | `tracked_packet_usa` |
| Xpresspost USA | `xpresspost_usa` |
| Xpresspost International | `xpresspost_international` |
| International Parcel Air | `international_parcel_air` |
| International Parcel Surface | `international_parcel_surface` |
| Priority Worldwide Envelope Intl | `priority_worldwide_envelope_international			` |
| Priority Worldwide pak Intl | `priority_worldwide_pak_international			` |
| Priority Worldwide parcel Intl | `priority_worldwide_parcel_international			` |
| Small Packet International Air | `small_packet_international_air			` |
| Small Packet International Surface | `small_packet_international_surface` |
| Tracked Packet - International | `tracked_packet_international` |


### Return Services

Canada Post supports creating return labels for domestic services with Commercial accounts only. Return labels cannot be voided.

Review the [Return Shipping Labels page](/apis/shipengine/docs/shipping/returns) for details on creating return labels with ShipStation API.

> **NOTE:**
Small Business accounts cannot create return labels with ShipStation API.


### Packages

Canada Post does not specify [carrier package types](/apis/shipengine/docs/shipping/carrier-packaging). You can use [custom package types](/apis/shipengine/docs/shipping/custom-package-types) or the generic `package` package type.

### Adding Shipment Insurance

Canada Post does not support adding carrier insurance to shipments created in ShipStation API.

## Label Support

* Label sizes: 4" x 6"
* Label formats: PDF


### Label Reference Fields

Canada Post supports adding [custom label messages](/apis/shipengine/docs/labels/messages).

* Label Messages 1 & 2 print on the label.
* Label Message 3 can be used for submitting Cost Centre but does not print on label.


The following international services do not have a place for label messages to actually appear:

* Small Packet Air
* Small Packet Surface
* Tracked Packet International
* Tracked Packet USA


### Multi-Package Labels

Canada Post does not support creating [multi-package shipments](/apis/shipengine/docs/shipping/multi-package).

### Label Branding

Canada Post does not support [label branding](/apis/shipengine/docs/labels/branding).

### Voiding Labels

Canada Post supports voiding labels with ShipStation API. For Commercial accounts, voiding must be done before manifesting your shipments.

You must wait 60 minutes after label creation before you can void a label and voiding must be done within 15 days of label creation.

See our [Void a Label page](/apis/shipengine/docs/labels/voiding) for details about voiding labels with ShipStation API.

### Paperless Labels

Canada Post supports creating paperless labels for domestic services only.

See our [Paperless Labels page](/apis/shipengine/docs/labels/paperless) for details about creating paperless labels with ShipStation API.

### Customs Declarations

International labels will either include a CN22 or CN23 form depending on the declared value. If it's over $500, a separate CN23 form will be included with the label. Customs declarations forms for international shipments can be downloaded from the `forms_download` object in the label response.

The Canada Post API now has character limits for SKU and Customs Descriptions:

* SKU: 15 characters limit
* Custom Description: 45 characters limit.


When a customs description exceeds the limit, you will receive an error on your label request.

## Delivery Confirmation

| Confirmation Type | API Code | Description |
|  --- | --- | --- |
| Delivery | `Delivery` | Delivery confirmation is requested. |
| Signature | `Signature` | Signature is required for the shipment to be delivered. This signature may be a neighbor, building manager, or the recipient can authorize the release of the package (without being present). Canada Post will apply a signature confirmation type automatically on all return labels. |
| Proof of Age Required - 18 | `AdultSignature` | An adult signature is required for the shipment to be delivered. |
| Proof of Age Required - 19 | `DirectSignature` | A signature of somebody at the address is required. |


See our [Delivery Confirmation page](/apis/shipengine/docs/shipping/delivery-confirmation) for more details about using the `confirmation` property.

## Advanced Options

Canada Post supports certain [advanced options](/apis/shipengine/docs/carriers/advanced-options), which you can add to the `shipment` object when creating a shipment or label.

| Option | Type | Default Value | Description |
|  --- | --- | --- | --- |
| `bill_to_party` | string | `null` | Determines which party is paying for shipping costs. This field must be used in conjunction with the `bill_to_country_code`, `bill_to_postal_code`, and `bill_to_account` fields. Available values: `recipient`, `third_party`, `null` - shipping costs will be billed to the connected carrier account. |
| `collect_on_delivery` | Object | `null` | Defers payment to recipient when package is delivered (up to $5,000). See the [Collect on Delivery page](/apis/shipengine/docs/shipping/collect-on-delivery) for details about using this property. |
| `delivered_duty_paid` | *boolean* | `false` | Indicates the shipment is DDP (that is, the shipper is paying the duties/taxes for the shipment rather than the recipient). |
| `dry_ice` | *boolean* | `false` | Indicates the shipment includes dry ice. Used in conjunction with the `dry_ice_weight` object. |
| `non_machinable` | boolean | `false` | Indicates that the package cannot be processed through sorting machines. |


To ensure you always have the most up-to-date information about a carrier's advanced options, use the [list carrier options call](/apis/shipengine/docs/reference/list-carrier-options).

## Manifests

Manifesting is required for Commercial accounts (except return labels, which do not need to be manifested). See our [Manifests page](/apis/shipengine/docs/shipping/manifests) for more details about creating manifests with ShipStation API.

Small business accounts do not need to manifest shipments and will receive an error if attempting to do so.

## Scheduling Pickups

Canada Post does not support [scheduling pickups](/apis/shipengine/docs/shipping/pickups) using ShipStation API.

## Service Points (PUDO)

Canada Post does not support shipping to [service points](/apis/shipengine/docs/pick-up-drop-off/pudo-intro).

## Tracking

ShipStation API's integration with Canada Post supports receiving tracking updates. Review our ​[Track a Package guides​](/apis/shipengine/docs/tracking/tracking)​ for details on tracking with the ShipStation API.

## Disconnecting Your Canada Post Account

See the Disconnect section in our [Delete a Carrier page](/apis/shipengine/docs/reference/carriers/delete-carrier) for the process of deleting or disconnecting a carrier from ShipStation API.

> **NOTE:**
If you disconnect a carrier account and reconnect it, the account will have a new `carrier_id` in ShipStation API.