Pickup

Create Pickup Request – REST

Summary

Name: Create Pickup Request
Reason to Call: To create a request for a one-time on-demand pickup.
Input: Pickup details
Output: Pickup request ID and links
Typical Prior Call: Get Pickup Availability
Typical Next Call: Get Pickup Request Details
Version history: Release notes
Create Pickup Request – Summary of Service

Create Pickup Request – Summary of Service

Request Details

Request – Structure for Create Pickup Request

Endpoint

POST https://XX/enab/{customer}/pickuprequest

Replace... With...

XX (Development)

ct.soa-gw.canadapost.ca

XX (Production)

soa-gw.canadapost.ca

{customer}

your customer number

HTTP Headers

HTTP Header Variable

Value

Accept

application/vnd.cpc.pickuprequest+xml (Note: */* in place of the header value will return an error)

Content-Type

application/vnd.cpc.pickuprequest+xml (Note: */* in place of the header value will return an error)

Authorization

Basic {Base64 encoding of userid:password}

Accept-language

en-CA or fr-CA

Body

<?xml version="1.0" encoding="utf-8"?>
<pickup-request-details xmlns="http://www.canadapost.ca/ws/pickuprequest”>
xxx
</pickup-request-details>

Request – Elements

The table below describes the XML input elements for Create Pickup Request. For the hierarchical structure of the inputs, see the XML diagram.

Create Pickup Request – Request Elements
Element Name Type Required/Optional Description/Size/Format

pickup-request-details

Complex

Required

The top level XML element for the request input information.

pickup-type

Simple

Required

Type of pickup requested:

  • Ondemand – for an on-demand (one-time) pickup

pickup-location

Complex

Required

Structure containing the address where the pickup is to occur.

business-address-flag

Simple

Required

{true}, {false}
True indicates that the pickup (or pickups) is at the business address specified in your Canada Post profile. (You can sign in to your profile to check the address we have on file for you.)
False indicates that the pickup is at an alternate address. You must specify the alternate address. Please note the following:

  • On-demand pickups at an alternate address can only be paid for by credit card.

alternate-address

Complex

Conditionally required

Address for third-party pickup.
Required for third-party pickups (business-address-flag=false). Must not be supplied if business-address-flag = true.

company

Simple

Required

(Character string up to 35 characters)
Company name of the organization requesting the pickup.

Required for third-party pickups (business-address-flag=false). Must not be supplied if business-address-flag = true.

address-line-1

Simple

Required

(Character string up to 35 characters)
Street address of your pickup location

Required for third-party pickups (business-address-flag=false). Must not be supplied if business-address-flag = true.

city

Simple

Required

(Character string up to 35 characters)
City of pickup location.

Required for third-party pickups (business-address-flag=false). Must not be supplied if business-address-flag = true.

province

Simple

Required

(2 characters)
Province of pickup location.
Use standard 2-character Canadian province codes.

Required for third-party pickups (business-address-flag=false). Must not be supplied if business-address-flag = true.

postal-code

Simple

Required

(6-character alphanumeric)
Postal Code of pickup location in format A9A9A9

Required for third-party pickups (business-address-flag=false). Must not be supplied if business-address-flag = true.

contact-info

Complex

Required

Structure containing the contact for questions or inquiries.

contact-name

Simple

Required

(Character string  up to 45 characters)
Contact name for the pickup.

email

Simple

Required

(Character string up to 60 characters)
Must be a valid email address.
Pattern is (['_A-Za-z0-9\-\+]+)(\.['_A-Za-z0-9\-\+]+)*@([A-Za-z0-9\-]+)(\.[A-Za-z0-9\-]+)*(\.[A-Za-z]{2,5})
Email address to receive status updates regarding your pickup request.

contact-phone

Simple

Required

(Character string up to 16 numeric characters)
Contact phone number for the pickup.
Format 999-999-9999

telephone-ext

Simple

Optional

(up to 6 numeric digits)
Telephone extension.

receive-email-updates-flag

Simple

Optional

{true, false}
True indicates that you wish to receive status updates about the request.
Defaults to False

location-details

Complex

Required

Structure containing characteristics of the physical location where pickup is to occur.

five-ton-flag

Simple

Optional

{true, false}
True identifies that a 5-ton truck is needed.
Only applicable to an on-demand pickup request.
Defaults to False

loading-dock-flag

Simple

Optional

{true, false}
True identifies that there is a loading dock at the location.
Defaults to False

pickup-instructions

Simple

Required

(Character string  up to 132 characters, but truncates to 40)
Instructions for the driver (e.g., use back door, use side entrance, bring a dolly)

items-characteristics

Complex

Optional

Structure to identify that items for pickup have special processing needs.
Only applicable to on-demand pickups.

priority-flag

Simple

Optional

{true, false}
Identifies that Priority items could be available for pickup.
Defaults to False

returns-flag

Simple

Optional

{true, false}
Identifies that returned items could be available for pickup.
Defaults to False

heavy-item-flag

Simple

Optional

{true, false}
Identifies that some the items to pick up may have a weight greater than 23 kg (50 lbs.)
Defaults to False

pickup-volume

Simple

Required

(Character string up to 40 characters)
The expected number of items to be picked up. You can also include additional details, such as “50 parcels and 10 packets”.

pickup-times

Complex

Required

Structure containing the date and time range in which the pickup is to be done.

on-demand-pickup-time

Complex

Conditionally required

Structure containing the details for an on-demand pickup request.
Mandatory for an on-demand pickup request; must not be provided otherwise.

date

Simple

Required

(YYYY-MM-DD format)
Date you would like the on-demand pickup. The date cannot be more than 5 days in the future, unless you have a parcels agreement, in which case it can be up to 30 days.

 preferred-time

Simple

Required

(hh:mm format)
The preferred time for the on-demand pickup. Must be between noon (12:00) and 4 p.m. (16:00), in 15-minute intervals (i.e. minutes must be 00, 15, 30 or 45).

closing-time

Simple

Required

(hh:mm format)
The latest time for the on-demand pickup. Must be a minimum of one hour after preferred-time, in 15-minute intervals (i.e. minutes must be 00, 15, 30 or 45).

scheduled-pickup-times

Not used. Request a scheduled pickup using our online tool.

payment-info

Complex

Optional

Structure containing details on payment.

contract-id

Simple

Optional

(Up to 10 numeric digits)
Your parcels agreement number, if applicable.

method-of-payment

Simple

Optional

For future use only.

In the initial release, the system will determine the method of payment:

  • If you do not have a parcels agreement, fees will be charged to the default credit card in your online profile (or the request rejected if you do not have a default credit card on file).
  • If you have a parcels agreement and request a pickup at your main address (on demand), it will be billed to your account (unless your account is blocked, in which case the default credit card in your online profile would be used, or the request rejected if you do not have a default credit card on file).
  • If you have, or have authority to use, a parcels agreement with third-party pickup activated and request a pickup at an alternate address, it will be billed to your account (unless your account is blocked, in which case the default credit card in your online profile would be used, or the request rejected if you do not have a default credit card on file).

Request – XML Diagram

Create Pickup Request – Structure of the XML Request
Create Pickup Request – Structure of the XML Request

Response Details

Response – Elements

The table below describes the XML fields in the response. For the hierarchy of the response, see the XML diagram.

Create Pickup Request – Response Elements
Element Name Type Description

pickup-request-info

Complex

The top level XML element for the response that contains the information about the pickup request.

pickup-request-header

Complex

Basic information about the request.

request-id

Simple

The ID number for the pickup request.

request-status

Simple

Status of the request.
Active will always be the status of a successful Create Pickup Request. See the response of Get Pickup Request Details for other possible statuses after creation.

 pickup-type

Simple

The type of pickup you requested: OnDemand.

request-date

Simple

Date the pickup request was created.

pickup-request-price

Complex

Only provided for on-demand pickup requests.

pre-tax-amount

Simple

Base charges for the pickup.

gst-amount

Simple

Goods and services tax amount.

pst-amount

Simple

Provincial sales tax amount.

hst-amount

Simple

Harmonized sales tax amount.

due-amount

Simple

Total charges.

cc-receipt-details

Complex

This structure contains details for a credit card receipt. These details are provided only for on-demand pickup requests paid by credit card.  

merchant-name

Simple

Will have the value: "Canada Post"

merchant-url

Simple

Will have the value: "www.canadapost.ca"

name-on-card

Simple

The name on the default credit card stored by Canada Post, if supplied.

auth-code

Simple

The authorization code received from the credit card issuer.

auth-timestamp

Simple

The date and time that the credit card company authorized the transaction.

card-type

Simple

The type of credit card used for the purchase.

charge-amount

Simple

The amount authorized by the credit card issuer.

currency

Simple

The currency of the transaction: CAD.

transaction-type

Simple

Will have the value: "Sale".

links

Complex

Structure containing links to information related to the pickup request.

link

Complex

Use these links to retrieve different results of the Create Pickup Request service, and/or invoke different additional functions on the pickup request. Each link represents a link to one of the web services.
May occur 1 .. N times
(Note: The link element is "complex" because it contains a number of attributes. It does not contain any sub-elements).
The following links will be returned and each will have a unique rel type:

  1. rel="self"

This link represents the pickup request just created. The href attribute can be used as an endpoint to the Update Pickup Request service.

  1. rel = "details"

This link provides additional details about the pickup request that are not returned in the Create Pickup Request response. The href attribute is an endpoint to the Get Pickup Request Details service to retrieve that additional information.

Response – XML Diagram

Create Pickup Request - Structure of the XML Response
Create Pickup Request - Structure of the XML Response

Response – Possible Error Responses

Code Description

11000

Address is incomplete (missing unit number for example).

11001

The contract number is not found or invalid.  Note that you must use a parcels agreement.

11002

There is already a pickup request within one hour of this one.

11003

Pickup cannot be done on the date requested (may be in the past, invalid or not a business day).

11005

Customer number not valid. Please correct or contact Canada Post for details.

11009

Pickup is not available for the postal code you provided.

11010

You must have a credit card on file when paying by this method of payment.

11015

Missing preferred time. Please correct your request.

11016

Your closing time cannot be before your preferred pickup time.

11018

Payment approval failed. Please try later or contact the Credit Management Group at 1-800-267-7651.

11020

The transaction could not be authorized.  Please verify your credit card.

11021

Pickup cannot be done at the time requested as it is outside pickup hours of {0} to {1}.

11022

It is too late to request a pickup today; the cut-off time was {0}.

11111

System error. Please try later or contact the Canada Post helpdesk.

See also HTTP status codes and Error messages and mitigation strategies.

Examples

Sample REST XML Request – Create Pickup Request

<pickup-request-details>
  <pickup-type>OnDemand</pickup-type>
  <pickup-location>
    <business-address-flag>false</business-address-flag>
    <alternate-address>
      <company>Jim Duggan</company>
      <address-line-1>2271 Herring Cove</address-line-1>
      <city>Halifax</city><province>NS</province>
      <postal-code>B3L2C2</postal-code>
    </alternate-address>
  </pickup-location>
  <contact-info>
    <contact-name>John Doe</contact-name>
    <email>john.doe@canadapost.ca</email>
    <contact-phone>800-555-1212</contact-phone>
    <opt-out-email-updates-flag>true</opt-out-email-updates-flag>
    <receive-email-updates-flag>true</ receive-email-updates-flag>
  </contact-info>
  <location-details>
    <five-ton-flag>false</five-ton-flag>
    <loading-dock-flag>true</loading-dock-flag>
    <pickup-instructions>Door at Back</pickup-instructions>
  </location-details>
  <items-characteristics>
    <pww-flag>true</pww-flag>
    <priority-flag>false</priority-flag>
    <returns-flag>true</returns-flag>
    <heavy-item-flag>true</heavy-item-flag>
  </items-characteristics>
  <pickup-volume>50</pickup-volume>
  <pickup-times>
    <on-demand-pickup-time>
      <date>2015-01-28</date>
      <preferred-time>15:00</preferred-time>
      <closing-time>17:00</closing-time>
    </on-demand-pickup-time>
  </pickup-times>
</pickup-request-details>

Sample REST XML Response – Create Pickup Request

<pickup-request-info>
  <pickup-request-header>
    <request-id>0074698052</request-id>
    <request-status>Active</request-status>
    <pickup-type>OnDemand</pickup-type>
    <request-date>2015-01-01</request-date>
  </pickup-request-header>
  <pickup-request-price>
    <pre-tax-amount>3.50</pre-tax-amount>
    <hst-amount>0.46</hst-amount>
    <due-amount>3.96</due-amount>
  </pickup-request-price>
  <links>
    <link rel="self" href="https://ct.soa-gw.canadapost.ca/enab/1234567/pickuprequest/0074698052" media-type="application/vnd.cpc.pickuprequest+xml"></link>
    <link rel="details" href="https://ct.soa-gw.canadapost.ca/enab/1234567/pickuprequest/0074698052/details" media-type="application/vnd.cpc.pickuprequest+xml"></link>
  </links>
</pickup-request-info>

Development (Sandbox) Environment XML Response – Create Pickup Request

The response is stubbed (static) in the development environment, so you will always receive the same response regardless of the data in your request. Please note, however, that the request-ids in the development environment are as follows:

  • On-demand pickups: 0074698052

To test a backend error (i.e. schema validations are all done in the development environment), 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.