Contract Shipping

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

Get Shipment Details – SOAP

Summary

Name: Get Shipment Details
Reason to Call: To retrieve an XML representation of the shipment details including tracking-pin.
Input: mailed-by; shipment-id; locale (optional)
Output:

  • 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.

Error Example: Invalid / expired shipment-id
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

Call Details

WSDL: shipment.wsdl
Endpoint (Development): https://ct.soa-gw.canadapost.ca/rs/soap/shipment/v8
Endpoint (Production): https://soa-gw.canadapost.ca/rs/soap/shipment/v8
Namespace: http://www.canadapost.ca/ws/soap/shipment/v8
Operation: GetShipmentDetails

SOAP Body

This section describes the XML input elements to this service. For the hierarchical structure, see the XML diagram.

Get Shipment Details – Request Elements
Element Name Type Required / Optional Description

get-shipment-details-request

complex

required

This is the top level XML element for the request input information.

mailed-by

simple

required

(1-10 digit numeric)

The 10-digit customer number of the mailed-by customer.

If the number provided has fewer than 10 digits, the system will add leading zeros.

mobo

simple

optional

(1-10 digit numeric)

The 10-digit customer number of the mailed-on-behalf-of customer.

If this element is missing, it will default to the mailed-by customer number.

If the number provided has fewer than 10 digits, the system will add leading zeros.

locale

simple

optional

Indicates your language preference for receiving error messages.

EN = English
FR = French

If no value is provided, the default language is English.

shipment-id

simple

required

(Alphanumeric String – up to 32 letters/digits)

An identification number representing the existing shipment for which information is being requested.

Note: Retrieve the shipment-id provided by previous calls to Create Shipment or Get Shipment. The output of those services will include a shipment-id element.

Request – XML Diagram

Get Shipment Details – Structure of the XML Request

Get Shipment Details – Structure of the XML Request

Response Details

Response – Elements

The following table describes the XML elements in the response to Get Shipment Details. For the hierarchy of the response, see the
XML diagram.

Get Shipment Details - Response Elements
Element Name Type Description

get-shipment-details-response

complex

The top level XML element for the response.

It will either contain the results of a successful completion, or the error structure.

shipment-details

complex

The XML element/structure containing the results of a successful completion of the service.

customer-request-id

simple

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

shipment-status

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 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). For a complete description of these elements, see Create Shipment Request Elements.

Response – XML Diagram

Get Shipment Details – Structure of the XML Response
Get Shipment Details – Structure of the XML Response

Response – Possible Error Responses

The response to error conditions for this web service follows the standard SOAP error response approach used for all Canada Post web services. For more information, see SOAP Fundamentals of Canada Post Web Services.

Examples

Sample SOAP XML Request – Get Shipment Details

<get-shipment-details-request>
<mailed-by>1111111</mailed-by>
<locale>EN</locale>
<shipment-id>340531309186521749</shipment-id>
</get-shipment-details-request>

Sample SOAP XML Response – Get Shipment Details

<get-shipment-details-response>
<shipment-details>
<shipment-status>created</shipment-status>
<final-shipping-point>J4W4T0</final-shipping-point>
<cpc-pickup-indicator>true</cpc-pickup-indicator>
<tracking-pin>1111111875783100</tracking-pin>
<shipment-detail>
<group-id>123456</group-id>
<expected-mailing-date>2011-09-29</expected-mailing-date>
<delivery-spec>
<service-code>DOM.EP</service-code>
<sender>
<name>John Doe</name>
<company>Canada Post Corporation</company>
<contact-phone>1-555-555-5555</contact-phone>
<address-details>
<address-line-1>2701 Riverside Drive</address-line-1>
<city>Ottawa</city>
<prov-state>ON</prov-state>
<country-code>CA</country-code>
<postal-zip-code>K1A0B1</postal-zip-code>
</address-details>
</sender>
<destination>
<name>John Doe</name>
<company>12345678 Ont. Limited</company>
<address-details>
<address-line-1>123 Any Street</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>15.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>this@that.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>0001111111</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>
</get-shipment-details-response>