Identifiers Object

Most resources in your application support an identifiers property. This property is useful for storing any custom data that may be needed by your application.

For example, let's say that your backend API requires the shipTo address when scheduling a pickup for a shipment. You can see that the shipTo address is not included in the arguments passed to your schedulePickup method since most carriers will obtain that information from the generated label. It could be useful to store that information in the identifiers object for the shipment. Then when the shipment is sent to your schedulePickup method, you will have access to the shipTo details via the identifiers property.

Your application definition files, such as the definition for a delivery service or delivery confirmation also include the identifiers property. You can use this to store additional information about the service that may be needed later by your app when a delivery service is passed as an argument to one of your methods.

The identifiers object stores an array of key-value pair strings. Each string must be between 0 and 100 characters and must not contain newline characters or leading or trailing spaces.

Examples

Adding to an object returned from a method

This method uses the identifiers object to store data on a shipment that will be needed by another method when it receives the shipment as an argument.

const mapCreateShipmentResponse = (response) => {
  const {
      shipTo,
      consignmentNumber,
      label,
      rate
  } = response;
  return {
      trackingNumber: consignmentNumber,
      label: {
        type: 'label',
        size: '4x6',
        format: 'pdf',
        data: Buffer.from(label, 'base64'),
        referenceFields: []
      },
      charges: rate.charges,
      identifiers: {
        shipToName: (shipTo.name.given + ' ' + shipTo.name.family).trim(),
        shipToAddressLine1: shipTo.addressLines[0],
        shipToAddressLine2: shipTo.addressLines[1] ? shipTo.addressLines[1] : '',
        shipToAddressLine3: shipTo.addressLines[2] ? shipTo.addressLines[2] : '',
        shipToCityLocality: shipTo.cityLocality,
        shipToStateProvince: shipTo.stateProvince,
        shipToPostalCode: shipTo.postalCode,
        shipToCountry: shipTo.country,
        shipToCompany: shipTo.company
      }
    };
});

Using the identifiers within a method

This example uses the identifiers that were set by the createShipment method to access internal data needed by the cancelShipments method.

module.exports = async function cancelShipments(transaction, shipmentCancellations) {
 // STEP 2: Create the data that the carrier's API expects
  let data = {
    operation: "void_labels",
    session_id: transaction.session.id,
    cancellations: shipmentCancellations.map((cancellation) => {
      const { cancellationID, trackingNumber } = cancellation;
      return {
        cancellationID: cancellationID,
        internalReferenceID: cancellation.identifiers.internalReferenceID,
        trackingNumber: trackingNumber,
      };
    }),
  };
  // STEP 3: Call the carrier's API
  const response = await apiClient.request({ data });
  // STEP 4: Create the output data that ShipEngine expects
  return await formatCancellationResponse(response.data);
}

Using the identifiers in a Delivery Confirmation Definition

This example specifies an internal code for the delivery confirmation using the identifiers object. This property will be available whenever this delivery confirmation is passed as an argument to one of your methods.

{
  "id": "67ba25f0-6492-417f-be47-26f7763d7853",
  "name": "Authority To Leave",
  "identifiers": {
    "internalCode": "ATL"
  },
  "description": "The carrier has the authority to leave the package at a PPOP.",
  "type": "signature"
}