`trackShipment()`

This method returns tracking information for a shipment, including each of the tracking events that have occurred for the shipment.

Most carrier applications should implement this method, unless you don't support tracking shipments.

Syntax

module.exports = async function trackShipment(transaction, shipment) {
  // Your code here
}

import { Transaction, TrackingCriteria, TrackingInfo } from "@shipengine/connect";
export default async function trackShipment(
  transaction: Transaction,
  shipment: TrackingCriteria
): Promise<TrackingInfo> {
  // Your code here
}

Parameters

`transaction`

A transaction object containing information about the transaction and session state.

`shipment`

An object containing information about which shipment to track.

Name	Type	Description
`trackingNumber`	string	The master tracking number for the entire shipment. For single-piece shipments, this will be the same as the package tracking number. For multi-piece shipments, this may be a separate tracking number, or the same tracking number as one of the packages. This string will not contain newline characters.
`identifiers`	identifiers object	Your own identifiers for this shipment.
`returns`	object	An object that indicates whether or not this shipment is a return shipment.
`returns.isReturn`	boolean	Indicates whether or not this shipment is a return shipment.
`metadata`	object	Custom data about this shipment that was persisted by ShipEngine Connect. Must be JSON serializable.

Return Value

`trackingInfo`

An object with tracking information for the specified shipment.

Name	Type	Required?	Description
`events`	object[]	✔	The events and status changes that have occurred for this shipment.
`events[].name`	string		The user-friendly name of the event (e.g. "Arrived at Warehouse", "Delivered"). This string must not contain newline characters.
`events[].dateTime`	date/time object, or Date object object, or a string representing the date and time in ISO format.	✔	The date/time that this event occurred.
`events[].status`	string	✔	The status of the shipment. Value values include the following: `accepted` - The shipment has been accepted by a drop-off facility or picked up by the carrier. `in_transit` - The shipment is in transit. `delivery_attempted` - The delivery was attempted but was unsuccessful. This could happen if a signature is required for delivery confirmation and no one is home when the delivery is attempted, for example. `delivered` - The shipment has been delivered. `exception` - There was an error is tracking the shipment.
`events[].isError`	boolean		Indicates whether this event represents an error state, such as a lost package or failed delivery.
`events[].code`	string		The carrier's event or status code. This string must not contain newline characters.
`events[].description`	string		The carrier's description of the event or status code. This description should not be specific to this particular shipment. This string must not contain newline characters.
`events[].address`	address object		The address (or as much of it as is known) where the event occurred. This property uses an address object, but all of its properties are optional in this case.
`events[].signer`	object or string		The name of the person who signed or approved this event. This is usually only relevant for the "Delivered" event. This property can take a string or object. If passing an object, use the properties described below. This property is not required. If it is provided, it must contain all of its required properties, listed below.
`events[].signer.title`	string		The title of the contact (eg "Mr", "Mrs", "Dr"). This string must not contain newline characters.
`events[].signer.given`	string	✔	The first name of the signer. This string must not contain newline characters.
`events[].signer.middle`	string		The middle name of the signer. This string must not contain newline characters.
`events[].signer.family`	string		The last name or family name of the signer. This string must not contain newline characters.
`events[].signer.suffix`	string		The suffix of the signer (eg "Sr", "Jr", "IV"). This string must not contain newline characters.
`trackingNumber`	string		The master tracking number for the entire shipment. For single-piece shipments, this will be the same as the package tracking number. For multi-piece shipments, this may be a separate tracking number, or the same tracking number as one of the packages. This string contain no newline characters.
`identifiers`	identifiers object		Your own identifiers for this shipment.
`deliveryDateTime`	date/time object, or Date object object, or a string representing the date and time in ISO format.		The date and time that the shipment is now expected to be delivered. Once the shipment has been delivered, this is the actual delivery date/time.
`packages`	object[]		The list of packages in the shipment. This property is not required. If it is provided, it must contain all of its required properties, listed below.
`packages[].packaging`	object or string		The actual packaging that was used, as determined by the carrier. This property accepts an object or a string representing the `code`. If an object is provided, it will have the following properties.
`packages[].packaging.id`	UUID	✔	UUID that uniquely identifies the object. This is the UUID you used in the Packaging Definition file for this packaging.
`packages[] .packaging .identifiers`	identifiers object		Your own identifiers for this packaging.
`packages[].packaging.code`	string		Optional code used to map to what the carrier uses to identify the packaging. The value `custom` indicates user-defined packaging. Some of our products allow users to enter custom packaging instead of one of your app's pre-defined packaging types.
`packages[].dimensions`	object		The dimensions for the package. This property is not required. If it is provided, it must contain all of its required properties, listed below.
`packages[] .dimensions .length`	number	✔	The length of the package. This value may contain decimals.
`packages[] .dimensions .width`	number	✔	The width of the package. This value may contain decimals.
`packages[] .dimensions .height`	number	✔	The height of the package. This value may contain decimals.
`packages[] .dimensions .unit`	string	✔	The unit of measurement for the dimensions. Valid values include the following: `in` - inches `cm` - centimeters
`packages[].weight`	object		The weight of the package. This property is not required. If it is provided, it must contain all of its required properties, listed below.
`packages[].weight.value`	number	✔	The weight value for this package. This value may not contain decimals.
`packages[].weight.unit`	string	✔	The unit of measure for this weight. Valid values include the following: `g` - grams `oz` - ounces `kg` - kilograms `lb` - pounds
`notes`	object[]		An array of objects containing additional information about this shipment. This property is not required. If it is provided, it must contain all of its required properties, listed below.
`notes[].type`	notes type string	✔	The type for this note.
`notes[].text`	string	✔	The note text itself.

Example

module.exports = async function trackShipment(transaction, trackingCriteria) {
  // STEP 1: Validation
  // STEP 2: Create the data that the carrier"s API expects
  const { trackingNumber, returns } = trackingCriteria;
  const data = {
    operation: "location_history",
    trackingNumber,
    isReturn: returns.isReturn
  };
  // STEP 3: Call the carrier"s API
  const response = await apiClient.request({ data });
  // STEP 4: Create the output data that ShipEngine expects
  return await formatTrackingResponse(response.data);
}

import {
  Transaction,
  TrackingCriteria,
  TrackingInfo
} from "@shipengine/connect";
export default async function trackShipment(
  transaction: Transaction, trackingCriteria: TrackingCriteria): Promise<TrackingInfo> {
  // STEP 1: Validation
  // STEP 2: Create the data that the carrier"s API expects
  const { trackingNumber, returns } = trackingCriteria;
  const data = {
    operation: "location_history",
    trackingNumber,
    isReturn: returns.isReturn
  };
  // STEP 3: Call the carrier"s API
  const response = await apiClient.request({ data });
  // STEP 4: Create the output data that ShipEngine expects
  return await formatTrackingResponse(response.data);
}