Pickup

Update Pickup Request – REST

Summary

Name: Update Pickup Request
Reason to Call: To modify a pickup request (e.g. contact, pickup times, etc.)
Input: Pickup request details (same data as Create Pickup Request)
Output: Success flag
Version history: Release notes
Update Pickup Request – Summary of Service

Update Pickup Request – Summary of Service

Request Details

Request – Structure for Update Pickup Request

Endpoint

Invoke the link returned from a prior call to Create Pickup Request or Get Pickup Requests where rel= “self” (see Provided endpoints)

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 Update Pickup Request. For the hierarchical structure of the inputs, see the XML diagram.

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

pickup-request-update

Complex

Required

The top level XML element for the request input information.

All data provided in this update will override the data in your original Create Pickup Request call.

Note: you cannot change the pickup-type, pickup-location and payment-info. If you need to change these elements, cancel your pickup instead and create a new one.

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=false). Must not be supplied if business-address = 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=false). Must not be supplied if business-address = true.

city

Simple

Required

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

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

province

Simple

Required

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

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

postal-code

Simple

Required

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

Required for third-party pickups (business-address=false). Must not be supplied if business-address = 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)
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)
For on-demand pickup, this is the expected number of items to be picked up. For scheduled pickups, its the average number of items you expect for each pickup.

pickup-times

Complex

Required

Structure containing the date and time range in which the pickup is to be done.
Only one of the child structures (on-demand-pickup-time or scheduled-pickup-times) must be provided.

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:ss 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:ss 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).

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 and request a pickup at an alternate address (i.e. third-party pickup), it will be charged to the default credit card in your online profile.

Request – XML Diagram

Update Pickup Request – Structure of the XML Request
Update Pickup Request – Structure of the XML Request

Response Details

Response – Elements

The Update Pickup Request service does not respond with any XML data, but a successful operation is indicated through an HTTP response code of 204. A 400 series HTTP response code indicates an error.

Response – Possible Error Responses

In addition to the errors below, you can also receive a 404 error if you submit an invalid request-id or if the pickup request has been cancelled.

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.

11011

You need a parcels agreement to request scheduled pickups.

11015

Missing preferred time. Please correct your request.

11012

Request ID not found. Please verify.

11016

Your closing time cannot be before your preferred pickup time.

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 – Update Pickup Request

PUT https://ENV/enab/001102159/pickuprequest/0074698052
Accept  application/vnd.cpc.pickuprequest+xml
Authorization:Basic s7HD7gwsennesc==
<pickup-request-update>
  <contact-info>
    <contact-name>Jane Doe</contact-name>
    <email>john.doe@canadapost.ca</email>
    <contact-phone>800-555-1212</contact-phone>
    <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>
    <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-update>

Sample REST XML Response – Update Pickup Request

The service does not respond with any XML elements unless an error occurs in which case the standard error response is provided.