Integrating parcel pickup web services into an ecommerce platform

One of the service offerings in the Canada Post Developer Program is parcel pickup web services. You can integrate these services into your ecommerce solution to enable easy requests for on-demand pickups. Pickup web services are particularly ideal for Ship from Store applications. Our API allows you to provide an integrated version of the on-demand pickup functionality found in our pickup tool.

How pickup web services work

You can request a pickup at your business location or a third-party location. To use third-party pickup you must be a commercial customer with third-party pickup specified in your contract.

Follow these steps to request a pickup:
  1. Determine if pickup is available at your location Use our online tool or integrate the web service into your solution: REST | SOAP. You can also use it to find cut-off times.
  2. Request a pickup Request a pickup using our Create Pickup Request web service: REST | SOAP. Among other elements, your request will include the following:
    • Pickup location: specify whether the pickup is at the business address we have on file for you or at an alternate/third-party location (third-party pickups are still billed to you).
    • Pickup date: request a pickup up the day you need it, up to 30 days in advance if you have a parcel agreement, or up to 5 days in advance if you don’t.

    • On-demand pickup time: your preferred time must be between noon and 4 pm. For same-day pickups, you must submit the request at least one hour before your desired pickup time. Your closing time must be at least an hour after the preferred time. See the full list of request elements in the Create Pickup Request web service: REST | SOAP.

  3. Get a reply The reply to a successful pickup request will provide you with a request ID number and a status of pending. If you request a same-day pickup after the cut-off times for that day, you’ll receive an error.

Ship from Store considerations

For Ship from Store applications, we recommend you design your solution so every store outlet has its own Canada Post customer number. This allows each store to easily request a pickup at their own location. Consider adding the pickup request function into your admin panel to allow store staff to quickly and easily request a pickup.

The illustrations below show a sample admin panel interface. As you can see, most fields are pre-populated for the convenience of store staff.

Admin panel interface showing Ship from Store orders.
Admin panel interface showing a pickup request.

Additional pickup web services

Once you have successfully requested a pickup, the following pickup web services are available:

  • Get Pickup Request Details Use the request-id from the response of your Create Pickup Request to get a summary of all the information about a specific pickup.
  • Update Pickup Request Modify the details of an existing pickup request, such as the contact details or pickup time. If you need to change your pickup location or your payment information, however, cancel your pickup request and create a new one.
  • Cancel Pickup Request Cancel an existing pickup request. Please note that if you cancel a request at your default business address, you will not be able to recreate another request in that same timeslot. Please use Update Pickup Request or request a different time.
  • Get Pickup Requests Retrieve all of your open pickup requests and their statuses.

How payment works

If you are a commercial customer with Canada Post and have a parcels agreement, pickups at your business location will be billed to your account. If you request a pickup at a third-party location, it will also be charged to you, but to the default credit card in your Canada Post profile.

If you do not have a parcels agreement, pickup fees will be charged to the default credit card in your profile.

Tips for testing in our development environment

Use our sandbox/development environment to validate your schema. Please note however that all responses are stubbed. This means you can test that the format of your request is valid, but the data in our response is static – it will always be the same regardless of the data in your request.

Test values

For pickup webs services that require a request ID, use the following test value: 0074698052

In the Create Pickup Request, to test a backend error, in the pickup-location structure set the postal-code element to A9A9A9. Error 11000 will be returned. No other error message will be returned in the development environment – for example, your contract number will not be verified for existence or validity.

Still need help?