Last updated

Manage Shipment Stops

Project44 allows you to provide your own stops (such as ORIGIN and DESTINATION) giving you control over how your shipment is rendered and where tracking should start and end. This is especially useful for reconciliation, reporting, and ensuring consistency across your systems.

Prerequisites

Before managing shipment locations, ensure you have the following:

  1. Authentication: Set up proper authentication to access project44's APIs.
  2. Stop Data: The location details (address, type, etc.) you want to associate with the shipment.

In most cases, you are not expected to provide route segments or intermediate stops along the route. These will be automatically discovered and tracked by project44's systems as part of our shipment visibility services. You should generally only provide the primary stops with typess ORIGIN and DESTINATION.

Adding Stops During Shipment Creation

You can include custom stops when you first create a shipment. Simply add the stops array to your shipment creation request payload. While stop IDs are not required at creation, it is highly advisable to provide deterministic stop IDs ( e.g., all 1's for ORIGIN, all 2's for DESTINATION) to make future updates to stops easier and more reliable.

Example:

{
  "identifiers": [
    {
      "type": "BILL_OF_LADING",
      "value": "BOL123456"
    },
    {
      "type": "CARRIER_SCAC",
      "value": "ABCD"
    }
  ],
  "stops": [
    {
      "id": "11111111-1111-1111-1111-111111111111",
      "type": "ORIGIN",
      "location": {
        "address": {
          "street": "123 Main St",
          "city": "Chicago",
          "state": "IL",
          "postalCode": "60601",
          "country": "US"
        }
      }
    },
    {
      "id": "22222222-2222-2222-2222-222222222222",
      "type": "DESTINATION",
      "location": {
        "address": {
          "street": "456 Market St",
          "city": "San Francisco",
          "state": "CA",
          "postalCode": "94105",
          "country": "US"
        }
      }
    }
  ]
}

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

Updating Stop Locations on an Existing Shipment (Partial Update)

To add or update stops for a shipment that already exists, use the POST method. This will update the shipment with the new or modified stops. You must include the shipment's id or sufficient identifiers to uniquely identify the shipment. If you provided deterministic stop IDs at creation, use the same IDs to update the corresponding stops.

Example:

{
  "id": "<previously returned project44 master shipment UUID>",
  "identifiers": [
    {
      "type": "BILL_OF_LADING",
      "value": "BOL123456"
    },
    {
      "type": "CARRIER_SCAC",
      "value": "ABCD"
    }
  ],
  "stops": [
    {
      "id": "11111111-1111-1111-1111-111111111111",
      "type": "ORIGIN",
      "location": {
        "address": {
          "street": "789 New St",
          "city": "Chicago",
          "state": "IL",
          "postalCode": "60602",
          "country": "US"
        }
      }
    }
  ]
}

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

Updating Stops Using PUT (Full Replace)

You can also update stops on an existing shipment using the PUT endpoint. Be aware that this method will fully replace all customer-provided data for the shipment—not just the stops. This means any attributes, events, or identifiers you previously provided will also be overwritten by the new payload. When using PUT, stop IDs are not required, but if you omit them, new IDs will be generated and you may lose the ability to reference or update those stops deterministically in the future.

Example:

{
  "id": "<previously returned project44 master shipment UUID>",
  "identifiers": [
    {
      "type": "BILL_OF_LADING",
      "value": "BOL123456"
    },
    {
      "type": "CARRIER_SCAC",
      "value": "ABCD"
    }
  ],
  "stops": [
    {
      "type": "ORIGIN",
      "location": {
        "address": {
          "street": "123 Main St",
          "city": "Chicago",
          "state": "IL",
          "postalCode": "60601",
          "country": "US"
        }
      }
    },
    {
      "type": "DESTINATION",
      "location": {
        "address": {
          "street": "456 Market St",
          "city": "San Francisco",
          "state": "CA",
          "postalCode": "94105",
          "country": "US"
        }
      }
    }
  ]
}

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

Using the PUT method on /api/v4/shipments/tracking will override all customer-provided data for the shipment, including stops, attributes, events, and identifiers. Only use this method if you intend to fully replace the shipment's data.

Previous page
Next page