Contract Shipping

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

Get Shipments – SOAP

Summary

Name: Get Shipments
Reason to Call:
  • To retrieve the shipment IDs for a collection of shipments not yet transmitted (members of a group), or
  • To retrieve the shipment IDs for a collection of shipments that have been transmitted (members of a manifest).
  • To retrieve a list of shipments where no manifest is required.
Input: Mailed-by, locale (optional) and one of either:
  • group-id
  • manifest-id
  • no-manifest
Output:

A list of shipment IDs.

Error Example: Invalid manifest-id or invalid group-id
Typical Prior Call: Get Groups or Get Manifest
Typical Next Call: Get Shipment (repeat for every shipment of interest)

Optional next calls: Get Shipment Price, Get Shipment Details, Get Shipment Receipt, Refund Shipment

Version history: Release notes
Get Shipments – Summary of Service

Get Shipments – 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: GetShipments

SOAP Body

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

Get Shipments – Request Elements
Element Name Type Required / Optional Description

get-shipments-request

complex

required

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.

platform-id

simple

optional

Your customer number (for e-commerce platforms only).

provide-shipment-info

simple

optional

Reserved for internal use.

shipment-search-key

complex

required

Contains the key that will be used to search for matching shipments.

Only one of regular-shipping-parameters, no-manifest-shipping-parameters, tracking-pin or customer-request-id must be provided.

regular-shipping-parameters

complex

conditionally required

Contains the key (either the group-id or the manifest-id) that will be used to search for matching shipments.

Mutually exclusive with no-manifest-shipping-parameters, tracking-pin and customer-request-id.

group-id

simple

conditionally required

(character string up to 32 characters)

The identifier for the group for which shipments are to be returned.

This element is required if you want to get the list of non-transmitted shipments within a group.

Note: Only one of the child elements of regular-shipping-parameters must be provided.

manifest-id

simple

conditionally required

(Alphanumeric String – up to 32 letters/digits)

The identifier for the existing manifest for which information is being requested.

(Retrieve the manifest-id provided by previous calls to Transmit Shipments or Get Manifests. The output of those services will include a manifest-id element.)

Note: one of either group-id or manifest-id elements must be present, but never both.

no-manifest-shipping-parameters

complex

conditionally required

Contains the search key (no-manifest) that will be used to search for shipments where no manifest is required.

Mutually exclusive with regular-shipping-parameters, tracking-pin and customer-request-id.

no-manifest

complex

conditionally required

{true}

When set to true, this element indicates you want to search for a list of shipments for which no manifest is required.

Note: if the no-manifest-shipping-parameters structure is present, then this element is required.

date

simple

optional

The date from which you want the search to start for shipments sent with no manifest required. Defaults to current date if not present. Format: YYYYMMDD

limit

simple

optional

(1-5 digit numeric)

The maximum number of shipments sent with no manifest required you want to receive in the response. Defaults to 100 if not present.

maximum value = 99999

tracking-pin

simple

conditionally required

(Alphanumeric string – 11 to 16 letters/digits)

The tracking ID of the existing shipment for which information is being requested.

Note: As Small Packet shipments do not have a tracking-pin, you must search for them using the other search parameters.

Mutually exclusive with regular-shipping-parameters and no-manifest-shipping-parameters and customer-request-id.

Note: In the sandbox (development) environment, the same tracking PIN is always returned (123456789012), so this query would not return representative results in that environment.

customer-request-id

simple

conditionally required

(Alphanumeric string – up to 32 letters/digits)

The customer-provided request ID of the shipment for which information is being requested.

Mutually exclusive with regular-shipping-parameters, no-manifest-shipping-parameters and tracking-pin.

Request – XML Diagram

Response Details

Response – Elements

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

Get Shipments – Response Elements
Element Name Type Description

get-shipments- response

complex

The top level XML element for the response.

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

shipments

complex

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

shipment-id

simple

These elements are mutually exclusive with shipment-info and are not provided when provide-shipment-info = true is supplied.

May occur 0 … N times

A unique identifier for the shipment that can be used for future calls to Get Shipment or other services to obtain more details about the shipment.

shipment-info

complex

Reserved for internal use.

Response – XML Diagram

Get Shipments – Structure of the XML Response

Get Shipments – 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.

An HTTP return code of 202 (Accepted) is returned if a shipment was found for the customer-request-id provided but the creation process of that shipment has not completed yet. You can keep polling until the process completes.

Examples

Sample SOAP XML Request – Get Shipments (regular shipping parameters)

<get-shipments-request>
      <mailed-by>1111111</mailed-by>
      <mobo>1111111</mobo>
      <locale>EN</locale>
      <platform-id>1111111</platform-id>
      <shipment-search-key>
            <regular-shipping-parameters>
                    <manifest-id>347891314723499921</manifest-id>
            </regular-shipping-parameters>
      </shipment-search-key>
</get-shipments-request>

Sample SOAP XML Request – Get Shipments (no-manifest shipping parameters)

<get-shipments-response>
  <shipments>
    <shipment-info>
      <shipment-id>340531309186521749</shipment-id>
      <shipment-status>reconciled</shipment-status>
      <tracking-pin>1111111883561103</tracking-pin>
      <artifacts>
        <artifact type="label">
          <artifact-id>10238</artifact-id>
          <page-index>0</page-index>
        </artifact>
      </artifacts>
    </shipment-info>
    <shipment-info>
      <shipment-id>603571709483456045</shipment-id>
      <shipment-status>reconciled</shipment-status>
      <tracking-pin>1111111256706</tracking-pin>
      <artifacts>
        <artifact type="label">
          <artifact-id>10239</artifact-id>
          <page-index>0</page-index>
        </artifact>
      </artifacts>
    </shipment-info>
  </shipments>
</get-shipments-response>

Sample SOAP XML Response – Get Shipments

<get-shipments-response>
  <shipments>
    <shipment-id>340531309186521749</shipment-id>
    <shipment-id>603571709483456045</shipment-id>
  </shipments>
</get-shipments-response>