Code Samples for Contract Shipping:  REST  |  SOAP

Contract Shipping

For Canada Post commercial customers

i Use Contract Shipping web services if you are a Canada Post commercial customer with a parcel agreement. If you are a commercial customer, but do not have a parcel agreement, please contact your sales representative or call 1-866-757-5480.
If you are a Solutions for Small Business™ customer, see Non-Contract Shipping.

NEW: EU Customs Declaration changes in effect Sunday, October 1, 2023

There will be changes to the information required on Customs Declaration forms for all parcels being shipped to EU countries beginning October 1, 2023.

The EU Transportation and Customs authorities will now be leveraging Electronic Advanced Data (EAD), to make pre-departure decisions to determine if an item can be loaded on the aircraft for transport to the European Union.

When filling out the Customs Declaration form electronically (also known as the CN22, CN23 or CP72), the Customers must provide accurate and detailed data and ensure all mandatory fields are completed. Providing false or incomplete information, in any completed fields, including listing “N/A” or “0000000000,” may result in the parcel being rejected by foreign customs authorities.

For more information, please refer to the Frequently Asked Questions at: FAQ about new customs rules for EU shipping | Canada Post (canadapost-postescanada.ca)

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

Services Summary

Use the Shipping and Manifest services to create, manage and process shipments and manifests—including labeling and inducting parcels for delivery.

New to Canada Post? Read our backgrounder on shipping, manifests and mailing on behalf of customers.

Shipping and Manifest workflow and key services are shown below.

Contract Shipping Workflow

Shipping Service

Shipping service functionality is provided through the following calls.

  1. Create Shipment
    REST   |    SOAP
    Used to create a new shipping item, to request the generation of a softcopy image of shipping labels, and to provide links to these shipping labels and other information associated with the shipping item.
  2. Get Shipment
    REST   |    SOAP
    Used to retrieve the same links originally provided by create shipment (used for recovery).
  3. Get Artifact
    REST   |    SOAP
    Used to retrieve the rendered label(s) for a shipment created by a prior "create shipment" call. It can be called more than once to reprint a spoiled label. Once you have printed the shipping label, you must complete the shipment process by creating a manifest. See Manifest Service below.
  4. Get Shipment Price
    REST   |    SOAP
    Used to retrieve the shipment pricing in XML format for a shipment created by a prior "create
    shipment" call.
  5. Get Shipment Receipt
    REST   |    SOAP
    Used to get settlement information in XML format for a shipment where no manifest is required that was paid by credit card. The data in the response can be formatted to print a credit card receipt.
  6. Get Shipment Details
    REST   |    SOAP
    Used to retrieve the shipment details in XML format for a shipment created by a prior "create
    shipment" call.
  7. Get Shipment Public Key Info
    REST   |    SOAP
    Used to retrieve the details on the public key including expiry date, QR code, public URL (un-authenticated URL)
  8. Get Groups
    REST   |    SOAP
    Used to retrieve the list of unique group-id codes associated with a customer (or mailed-on-behalf-of customer) for which there are shipments created that have not yet been transmitted.
  9. Get Shipments
    REST   |    SOAP
    Used to retrieve links to all shipments associated with a specific group or manifest.
  10. Void Shipment
    REST   |    SOAP
    Used to indicate to Canada Post that a printed label has been spoiled or cancelled and that it will not be used and should not be transmitted or billed.
  11. Request Shipment Refund
    REST   |    SOAP
    Used to request a refund for a shipment that has already been transmitted and for which a label has been printed, but is spoiled and will not be used.

Manifest Service

After you create your shipment and print your shipping label, you must perform the following steps to complete the shipping process and produce a manifest.

Important: If you do not create a manifest, we will bill you for all unpaid shipments and apply a per-item surcharge. Learn more about unpaid shipments.

  1. Perform a Transmit Shipments call – This sends shipment data for billing and tracking to Canada Post and provides the information in the response that you need to call Get Manifest to create your manifest (your hard-copy proof of payment required for all shipments for pickup or drop-off to Canada Post). You must produce this manifest every time that you have shipments for deposit or pickup.
  2. Perform a Get Manifest call – The information in the response from Get Manifest will allow you to make a call to Get Artifact to retrieve your manifest. A successful call to Get Manifest is your confirmation that a manifest has been successfully created.
  3. Note: Depending on the number of shipments in your Transmit Shipments request, there may be a delay before we can provide a successful Get Manifest response. If you receive error 9153 in the response to your call to Get Manifest, please pause and then continue to call Get Manifest until you receive a successful response. Allow for pauses as required.

  4. Perform a Get Artifact call – The information in the response from Get Artifact allows you to retrieve and print your manifest to provide with your shipments at pickup or drop-off time.
Send a sample Transmit Shipments REST request.

i Conduct your testing in the development environment. You will be billed for any manifests you submit through a Transmit Shipments call in the production environment.

Manifest service functionality is provided through the following calls.

Note: Read about the requirements and procedure for cancelling a manifest.

  1. Transmit Shipments
    REST   |    SOAP
    A mandatory web service call that must be performed to trigger the billing process. After a call to Transmit Shipments, you must successfully perform a call to Get Manifest to ensure that your shipments were successfully transmitted and that a manifest is created. If you do not create a manifest, we will bill you for all unpaid shipments and apply a per-item surcharge. Learn more about unpaid shipments. Transmit Shipments is used to specify shipments to be included in a manifest. Inclusion in a manifest is specified by group. Specific shipments may be excluded if desired.
  2. Get Manifest
    REST   |    SOAP
    A mandatory call that must be made following a Transmit Shipments request. A successful call to Get Manifest allows you to confirm that a manifest has been successfully created. You can also use Get Manifest to retrieve detailed information (details, artifacts and shipments) associated with a given manifest. If you receive error 9153 in the response to your call to Get Manifest, please pause and then continue to call Get Manifest until you receive a successful response.
  3. Get Artifact
    REST   |    SOAP
    Used to retrieve the rendered manifest document(s). You must provide a hard copy of the manifest every time that you have shipments for deposit or pick up. May be called more than once to perform a reprint.
  4. Get Manifest Details
    REST   |    SOAP
    Used to retrieve XML showing all the cost details associated with a manifest. If the manifest was paid by credit card, all the elements necessary to print a hard copy credit card receipt are provided.
  5. Get Manifests
    REST   |    SOAP
    Used to retrieve a list of manifests (within a given date range) that were previously transmitted.

Customer Information Services

Customer information services provide information on the relationships between customer numbers and allowable methods of payment.

The general flow of use of these services is as follows:

Customer Information Services Workflow

Terminology

A parcel can have up to three different customer numbers associated with it, as shown in the following table:

Type of Customer Number Description

Mailed-by

The customer number of the Canada Post customer who is preparing/mailing the parcel.

MoBo

The customer number of the owner of the mail. This is commonly the same as mailed-by customer number. However, it will be a different number in situations where the mailed-by customer is preparing/mailing parcels on behalf of another customer.

Payer

The customer number of the Canada Post customer who is paying for the shipping. This is commonly the same as either the mailed-by customer number or the MoBo customer number. However, it will be a different number in situations where another party is paying for the shipping.

Customer Information Services is provided through two service calls.

  1. Get Customer Information
    REST   |    SOAP
    Retrieves general information about a Canada Post customer, including contract number, the valid payers, the allowed methods of payment for each payer and links to mailed-on-behalf-of customers (if they exist), both past and present.

    (The customer is identified by the mailed-by customer number.)

  2. Get MOBO Customer Information
    REST   |    SOAP
    Retrieves general information about a Canada Post mailed-on-behalf-of (mobo) customer including contract number, the valid payers and the allowed methods of payment for each payer.

    (The mobo customer is identified by the mailed-on-behalf-of customer number)