Last updated

Manage Shipment Time Windows

Project44 allows you to specify planned time windows for your shipment stops by providing ARRIVAL_AT_STOP events with PLANNED datetime values. This enables you to share expected arrival windows for each stop, which we may require to reliably provide shipment visibility, depending on the mode and type of shipment.

Prerequisites

Before managing shipment time windows, ensure you have the following:

  1. Authentication: Set up proper authentication to access project44's APIs.
  2. Stop IDs: Deterministic stop IDs for each stop you wish to assign a time window to.
  3. Event Data: The planned arrival window (planned start and potentially the planned end) for each stop.

To associate a time window with a specific stop, you must provide the stop's id. For best results, set deterministic stop IDs as described in the Manage Shipment Stops guide.

Specifying Time Windows During Shipment Creation

You can include planned time windows for stops when you first create a shipment. Add an events array to your shipment creation request payload, with an ARRIVAL_AT_STOP event for each stop. Provide at least the plannedDateTime (planned start) property and optionally the plannedEndDateTime (planned end) property.

Example:

{
  "identifiers": [
    {
      "type": "BILL_OF_LADING",
      "value": "BOL123456"
    },
    {
      "type": "CARRIER_SCAC",
      "value": "ABCD"
    }
  ],
  "events": [
    {
      "type": "ARRIVAL_AT_STOP",
      "plannedDateTime": "2024-07-01T08:00:00Z",
      "plannedEndDateTime": "2024-07-01T10:00:00Z",
      "stopId": "11111111-1111-1111-1111-111111111111"
    },
    {
      "type": "ARRIVAL_AT_STOP",
      "plannedDateTime": "2024-07-03T14:00:00Z",
      "plannedEndDateTime": "2024-07-03T16:00:00Z",
      "stopId": "22222222-2222-2222-2222-222222222222"
    }
  ],
  "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 Time Windows on an Existing Shipment (Partial Update)

To add or update planned time windows for stops on an existing shipment, use the POST method. Include the shipment's id or sufficient identifiers, and provide the updated events array. For each ARRIVAL_AT_STOP event, provide at least the plannedDateTime property and optionally the plannedEndDateTime property. Only the provided events will be updated or added; other shipment data will remain unchanged.

Note: By default, providing an event with the same type and stopId will store a newer revision of any previously existing event for that stop.

Example:

{
  "id": "<previously returned project44 master shipment UUID>",
  "identifiers": [
    {
      "type": "BILL_OF_LADING",
      "value": "BOL123456"
    },
    {
      "type": "CARRIER_SCAC",
      "value": "ABCD"
    }
  ],
  "events": [
    {
      "type": "ARRIVAL_AT_STOP",
      "plannedDateTime": "2024-07-01T09:00:00Z",
      "plannedEndDateTime": "2024-07-01T11:00:00Z",
      "stopId": "11111111-1111-1111-1111-111111111111"
    }
  ]
}

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

Updating Time Windows Using PUT (Full Replace)

You can also update time windows using the PUT endpoint. Be aware that this method will fully replace all customer-provided data for the shipment—not just the events. This means any stops, attributes, or identifiers you previously provided will also be overwritten by the new payload. When using PUT, be sure to include all relevant shipment data. For each ARRIVAL_AT_STOP event, provide at least the plannedDateTime property and optionally the plannedEndDateTime property.

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.

Example:

{
  "id": "<previously returned project44 master shipment UUID>",
  "identifiers": [
    {
      "type": "BILL_OF_LADING",
      "value": "BOL123456"
    },
    {
      "type": "CARRIER_SCAC",
      "value": "ABCD"
    }
  ],
  "events": [
    {
      "type": "ARRIVAL_AT_STOP",
      "plannedDateTime": "2024-07-01T08:00:00Z",
      "plannedEndDateTime": "2024-07-01T10:00:00Z",
      "stopId": "11111111-1111-1111-1111-111111111111"
    },
    {
      "type": "ARRIVAL_AT_STOP",
      "plannedDateTime": "2024-07-03T14:00:00Z",
      "plannedEndDateTime": "2024-07-03T16:00:00Z",
      "stopId": "22222222-2222-2222-2222-222222222222"
    }
  ],
  "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 PUT request to /api/v4/shipments/tracking.

Previous page
Next page