Contract Shipping

Code Samples for Contract Shipping: Java (.zip) | PHP (.zip) | C# (.zip)

Get Shipment Details – REST

Summary

Name: Get Shipment Details
Reason to Call: To retrieve an XML representation of the shipment details including tracking-pin.
Input: Invoke the link returned from Create Shipment or Get Shipment where rel= “details”
Output:

The information provided is

  • the tracking PIN of the shipping label
  • the final shipping point.
  • an XML structure with the original shipping input information that was used to create the shipment, and
  • the group-id that the original shipment was created under, when applicable.
Error Example: Invalid / expired link.
Typical Prior Call: Create Shipment
Typical Next Call: Get Artifact
Optional Next Call: Get Shipment Price (if that service has not already been called); or Create Shipment (to continue creating shipments)
Version history: Release notes
Get Shipment Details – Summary of Service

Get Shipment Details – Summary of Service

Request Details

Request – Structure for Get Shipment Details

Endpoint

Invoke the link returned from a prior call where rel= “details” (see Provided endpoints)

HTTP Headers

HTTP Header Variable

Value

Accept

application/vnd.cpc.shipment-v8+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

None

Request – Elements

The Get Shipment Details service does not require any input XML data.

Response Details

Response – Elements

The following table describes the top level view of the XML data in the response.

Get Shipment Details - Response Elements
Element Name Type Description

shipment-details

Complex

The top level element of the XML structure.

customer-request-id

Simple

Your unique transaction ID, if you supplied it in your request.

shipment-status

Simple

Valid values are:

  • created,
  • transmitted
  • suspended

Indicates the current status of the shipment.

final-shipping-point

Simple

This element is used for pricing purposes.

If you provided a requested-shipping-point element in your Create Shipment request, this is the Postal Code of the Canada Post facility that is closest to your pickup location.

If you provided a shipping-point-id in your Create Shipment request, this is the Postal Code of the deposit location you chose.

shipping-point-id

Simple

If you chose to deposit your shipments, this element contains the site number of the Canada Post facility you selected.

cpc-pickup-indicator

Simple

{true}

Returned if you requested your shipments be picked up.

tracking-pin

Simple

This is the tracking parcel identification number (PIN) for the shipment. The tracking PIN can be used as input to other parcel web service calls such as Get Tracking Details.

po-number

Simple

The Canada Post Purchase Order number; only applicable and returned on a shipment where no manifest is required for proof of payment.

destination

Complex

This element contains either one of the following:

  • The address of the mail recipient (for regular shipments)
  • The address of the Post Office where the shipment will be delivered to (for shipments sent using the Deliver to Post Office option)

recipient

Complex

This element appears in the response only if you selected the Deliver to Post Office (D2PO) option when you created the shipment. It contains the mail recipient’s address that you provided in the destination element in your request.

return-spec

Complex

This structure is identical to the corresponding structure in the request input to Create Shipment.

refund-request-info

Complex

This structure is present only if a refund request was submitted for this shipment.

service-ticket-date

Simple

Date when the refund request was submitted.

service-ticket-id

Simple

Service ticket number assigned to the refund request. Please use this number in any communications with Canada Post about the refund request.

The remaining elements are identical to the elements from the request (input) to Create Shipment (with the exception of requested-shipping-point). See Create Shipment - Request Elements.

Response – XML Diagram

The following diagram shows the top level structure of the XML response to this service.

Get Shipment Details – Structure of XML Response – Top Level
Get Shipment Details – Structure of XML Response – Top Level

Response – Possible Error Responses

No errors are expected for invocation of this link, but you will receive a 404 error if you invoke Get Shipment Details more than 90 days after the link was provided.

See HTTP status codes for more information.

Examples

Sample REST XML Request – Get Shipment Details

GET https://XX/rs/0001111111/0001111111/shipment/348821316871829846/details
Accept:application/vnd.cpc.shipment-v8+xml
Authorization:Basic s7HD7gwsennesc==

Note: the HTTP endpoint link and “Accept” value should not be hardcoded. Rather, these values are provided as outputs from the Create Shipment and Get Shipment services.

Sample REST XML Response – Get Shipment Details

<shipment-details>
<shipment-status>reconciled</shipment-status>
<final-shipping-point>K1G1C0</final-shipping-point>
<shipping-point-id>0015</shipping-point-id>
<tracking-pin>1234567890123456</tracking-pin>
<shipment-detail>
<group-id>bobo</group-id>
<requested-shipping-point>K1G1C0</requested-shipping-point>
<expected-mailing-date>2011-09-01</expected-mailing-date>
<delivery-spec>
<service-code>DOM.EP</service-code>
<sender>
<name>Bob</name>
<company>CGI</company>
<address-details>
<address-line-1>502 MAIN ST N</address-line-1>
<city>MONTREAL</city>
<prov-state>QC</prov-state>
<country-code>CA</country-code>
<postal-zip-code>H2B1A0</postal-zip-code>
</address-details>
</sender>
<destination>
<name>Jain</name>
<company>CGI</company>
<address-details>
<address-line-1>23 jardin private</address-line-1>
<city>Ottawa</city>
<prov-state>ON</prov-state>
<country-code>CA</country-code>
<postal-zip-code>K1K4T3</postal-zip-code>
</address-details>
</destination>
<options>
<option>
<option-code>DC</option-code>
</option>
</options>
<parcel-characteristics>
<weight>20.000</weight>
<dimensions>
<length>12</length>
<width>9</width>
<height>6</height>
</dimensions>
<unpackaged>true</unpackaged>
<mailing-tube>false</mailing-tube>
<oversized>false</oversized>
</parcel-characteristics>
<notification>
<email>john.doe@yahoo.com</email>
<on-shipment>true</on-shipment>
<on-exception>false</on-exception>
<on-delivery>true</on-delivery>
</notification>
<print-preferences>
<output-format>8.5x11</output-format>
</print-preferences>
<preferences>
<show-packing-instructions>true</show-packing-instructions>
<show-postage-rate>false</show-postage-rate>
<show-insured-value>true</show-insured-value>
</preferences>
<settlement-info>
<paid-by-customer>0001234567</paid-by-customer>
<contract-id>0012345678</contract-id>
<intended-method-of-payment>Account</intended-method-of-payment>
</settlement-info>
</delivery-spec>
</shipment-detail>
</shipment-details>