Developer Program

Ready to join the Developer Program? Join NOW FREE

Resources

Contract Shipping

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

Get Shipments – REST

Summary

Name:	Get Shipments
Reason to Call:	To retrieve links to a collection of shipments not yet transmitted (members of a group). To retrieve the link to a specific shipment To retrieve links to a collection of shipments that has been transmitted (members of a manifest). To retrieve a list of shipments where no manifest is required.
Input:	Invoke the link returned from a prior call.
Output:	A list of links to individual shipment resources.
Error Example:	Invalid / expired link.
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

Request Details

Request – Structure for Get Shipments

Endpoint

Invoke the link returned from a prior call to Get Groups where rel=”group”

Invoke the link returned from a prior call to Get Manifest where rel=”manifestShipments”

(see Provided endpoints)

GET https://XX/rs/{mailed by customer}/{mobo}/shipment?trackingPIN={tracking-pin}

GET https://XX/rs/{mailed by customer}/{mobo}/shipment?requestId={customer-request-id}

GET https://XX/rs/{mailed by customer}/{mobo}/shipment?noManifest=true&date=YYYYMMDD&limit={number}

HTTP Headers

HTTP Header Variable	Value
Accept	from media-type in original link (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 Shipments service does not require any input XML data but the query string defines the type of search:

By group-id (shipments not yet transmitted in that group).
By manifest (shipments in that manifest).
By tracking-pin (specific shipment). 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.
By customer-request-id (specific shipment).
By shipments where no manifest is required, which require you to pass a {noManifest=true} parameter to identify this type of request, and optionally some filtering parameters:
- Date in yyyymmdd format (defaults to the current date when parameter is not supplied).
- Limit – the maximum number of links to include in response, from most recent to oldest. (e.g.; limit=1 would return only the most recent shipment). Defaults to 100 when parameter is not supplied. Limited to 99,999 if a number larger than that value is supplied.

Response Details

Response – Elements

The Get Shipments response can contain multiple shipments, and either a link to Get Shipment for each or the same response as Get Shipment for each.

For a detailed view of the hierarchy of the response, see the diagram below.

Get Shipments – Detailed View of Response Elements
Element Name	Type	Description
shipments	Complex	This is the top level XML element of the response structure.
link	Simple	These elements are mutually exclusive with shipment-info and will not be provided if provideShipmentInfo = true is supplied. The top level shipments structure contains a number of link elements. See Provided endpoints for a description of link attributes. The href attribute can be used as an endpoint to the Get Shipment service for the shipment. See Get Shipment for information on how to invoke that service. The href attribute can also be used to delete the shipment via an invocation of the Void Shipment service. See Void Shipment for information on how to invoke that service.
shipment-info	Complex	Reserved for internal use.

Response – XML Diagram

The following diagram shows the top level response. Note that the attribute “index" shown in the diagram is not used in the Get Group Shipments or Get Manifest Shipments services.

Get Group Shipments / Get Manifest Shipments – Structure of XML Response

Response – Possible Error Responses

An HTTP return code of 404 (Not found) is returned if no shipment was found. This means:

The group or manifest no longer exists. This can occur because groups that become empty after transmit are deleted after 24 hours. Manifests and their associated shipments are deleted after 90 days.
No shipment where no manifest is required was found for the parameters specified.

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.

Other possible error messages for this service include the following:

Code	Description
9183	Only one of the search parameters must be provided.
9185	Limit and Date only apply to noManifest=true requests.

Examples

Sample REST XML Request – Get Group Shipments / Get Manifest Shipments


  GET https://XX/rs/23243/234243/shipment?groupId=2342423

    Accept:application/vnd.cpc.shipment-v8+xml

    Authorization:Basic s7HD7gwsennesc==

Sample REST XML Response – Get Group Shipments / Get Manifest Shipments


  
  
<shipments>

     <link rel="shipment" href="https://XX/rs/1111111111/222222222/shipment/33333333333" media-type="application/vnd.cpc.shipment-v8+xml"></link>

      <link rel="shipment" href="https://XX/rs/1111111111/222222222/shipment/44444444" media-type="application/vnd.cpc.shipment-v8+xml"></link>

    
    </shipments>

Sign in