Manage Shipment Attributes

Project44 provides the ability to easily add your own custom attributes to your shipments for simple recognition and reconciliation. Custom attributes are surfaced on our Movement UI and as part of the webhook shipment payload.

Prerequisites

Before adding a shipment attribute, ensure you have the following:

1. Authentication: Set up proper authentication to access project44's APIs.
2. Attribute Key: Before you can add a custom attribute to a shipment, you must first create the attribute key ( definition) using the Create Shipment Attribute Definition API. This step must be performed once per unique attribute name.
3. Attributes: The new or updated attributes you want to associate with the shipment.

Providing Attributes during Shipment Creation

You can include custom attributes when you first create a shipment. Simply add the attributes array to your shipment creation request payload. This allows you to associate custom data with the shipment from the very beginning.

Example:

{
  "identifiers": [
    {
      "type": "BILL_OF_LADING",
      "value": "BOL123456"
    },
    {
      "type": "CARRIER_SCAC",
      "value": "ABCD"
    }
  ],
  "attributes": [
    {
      "name": "priority",
      "values": ["high"]
    },
    {
      "name": "customerReference",
      "values": ["REF12345"]
    }
  ]
}

Send this payload in a POST request to /api/v4/shipments/tracking.

Appending Attributes to an Existing Shipment

To add or update attributes for a shipment that already exists, use the POST method. This will update the shipment with the new or modified attributes. You must include the shipment's id or sufficient identifiers to uniquely identify the shipment.

Example:

{
  "id": "<previously returned project44 master shipment UUID>",
  "identifiers": [
    {
      "type": "BILL_OF_LADING",
      "value": "BOL123456"
    },
    {
      "type": "CARRIER_SCAC",
      "value": "ABCD"
    }
  ],
  "attributes": [
    {
      "name": "priority",
      "values": ["urgent"]
    },
    {
      "name": "customerReference",
      "values": ["REF67890"]
    }
  ]
}

Send this payload in a POST request to /api/v4/shipments/tracking.

Updating Attributes on an Existing Shipment (Full Replace)

You can also update attributes on an existing shipment using the PUT endpoint. However, be aware that this method will fully replace all customer-provided data for the shipment—not just the attributes. This means any stops, events, or identifiers you previously provided will also be overwritten by the new payload.

Example:

{
  "id": "<previously returned project44 master shipment UUID>",
  "identifiers": [
    {
      "type": "BILL_OF_LADING",
      "value": "BOL123456"
    },
    {
      "type": "CARRIER_SCAC",
      "value": "ABCD"
    }
  ],
  "attributes": [
    {
      "name": "priority",
      "values": ["critical"]
    },
    {
      "name": "customerReference",
      "values": ["REF99999"]
    }
  ]
}

Send this payload in a PUT request to /api/v4/shipments/tracking.