Last updated

Create an Ocean Shipment

Use the Project44 API to register an ocean shipment in the network and begin receiving tracking data. This guide walks you through creating a shipment with or without additional metadata such as attributes or container IDs. You can then view and subscribe to the tracking data via APIs, Movement UI or Webhooks.

After a shipment is created, Project44 validates the shipment and initiates tracking as part of an asynchronous process. If the discovered ocean carrier is within project44’s network, the system automatically subscribes to the carrier using Ocean Carrier Tracking Capability.

Basic Shipment Creation

To initiate tracking of an ocean shipment in Project44's network, you must provide at least one shipment identifier along with exactly one Carrier SCAC.

Prerequisites

Ensure you have the following:

BILL_OF_LADING or BOOKING_NUMBER is a unique identifier given to you by the Ocean carrier. It often contains multiple containers (each with their own Container ID) allowing you to track multiple containers with a single identifier.

Workflow

Complete these steps:

  1. Send a POST request to /api/v4/shipments/tracking.
  2. Include the identifiers in the request payload:
{
  "identifiers": [
    {
      "type": "BILL_OF_LADING",
      "value": "MEDUAB12345"
    },
    {
      "type": "CARRIER_SCAC",
      "value": "MSCU"
    }
  ]
}

This only shows the minimum required request schema. For the full request schema and descriptions for all fields and objects, please see our reference documentation.

  1. Submit the request.

Successful Response

A successful response will return a 200 OK status with the following structure:

{
  "id": "93294f58-f87a-48e0-9f68-7d3f6e0aaa2f",
  "identifiers": [
    {
      "type": "BILL_OF_LADING",
      "value": "MEDUAB12345"
    },
    {
      "type": "CARRIER_SCAC",
      "value": "MSCU"
    }
  ]
}

The response includes the same identifiers provided in the request—such as BILL_OF_LADING, BOOKING_NUMBER, along with the CARRIER_SCAC. It also returns a unique shipment identifier (id) and any associated container CONTAINER_IDs and their corresponding IDs. Once the shipment is registered in project44’s system, related shipments are automatically identified. These will appear in the relatedShipments array when you retrieve shipment details via a GET request.

ℹ️ Note: This is a sample response. Fields with null values are omitted. For a complete list of fields and possible values, refer to the reference documentation.

Save the id. You’ll need it to retrieve tracking updates for this shipment.

Create Shipment with Attributes

Please refer to the guide on Managing Shipment Attributes for more details.

Create an Ocean Shipment using only a Container ID

⚠️ Use this method only if you do not have a BILL_OF_LADING or BOOKING_NUMBER.

Not all carriers support shipment creation using only CONTAINER_ID.

Prerequisites

Ensure you have the following:

Workflow

Complete these steps:

  1. Prepare a POST request to /api/v4/shipments/tracking.
  2. Add the CONTAINER_ID to the identifier array in the request schema.
JSON
 {
  "identifiers": [
    {
      "type": "CONTAINER_ID",
      "value": "XYZA4743198"
    },
    {
      "type": "CARRIER_SCAC",
      "value": "MAEU"
    }
  ]
}

This only shows the minimum required request schema. For the full request schema and descriptions for all fields and objects, please see our reference documentation.

  1. Submit the request.

Successful Response

A successful response will return a 200 OK status with the following structure:

{
  "id": "53294f58-f87a-48e0-9f68-7d3f6e0aaa3g",
  "identifiers": [
    {
      "type": "CONTAINER_ID",
      "value": "XYZA4743198"
    },
    {
      "type": "CARRIER_SCAC",
      "value": "MAEU"
    }
  ]
}

You will receive the shipment ID, identifiers in the response.

  • This is an example of what could be returned in the response. Null fields will not show up in the response. Please refer to the reference data for more information on required and potential null fields.
  • Save the id. You’ll need it to retrieve tracking updates for this shipment.

Create an Ocean Shipment and Track Specific Containers

Only use this workflow if you want to track specific containers related to your shipment instead of all containers related to your shipment.

Prerequisites

Have the following information available:

  • One of the following shipment Identifiers: BILL_OF_LADING or BOOKING_NUMBER.
  • Exactly one CARRIER_SCAC. View SCACs for in-network Ocean carriers.
  • One or more CONTAINER_ID for related containers.

Workflow

Complete these steps:

  1. Prepare a POST request to /api/v4/shipments/tracking.
  2. Add the shipment identifiers to the identifiers array in the request schema.
  3. Add the CONTAINER_IDs for each related container to the identifiers array in the request schema. The completed request schema should look like this:
JSON
{
  "identifiers": [
    {
      "type": "BILL_OF_LADING",
      "value": "123456789"
    },
    {
      "type": "CARRIER_SCAC",
      "value": "MSCU"
    },
    {
      "type": "CONTAINER_ID",
      "value": "PQRS7027376"
    },
    {
      "type": "CONTAINER_ID",
      "value": "GHJI7027376"
    }
  ]
}

This only shows the minimum required request schema. For the full request schema and descriptions for all fields and objects, please see our reference documentation.

  1. Submit the request.

Successful Response

A successful response will return a 200 OK status with the following structure:

JSON
{
  "id": "45294f58-f87a-48e0-9f68-7d3f6e0aaa5j",
  "identifiers": [
    {
      "type": "BILL_OF_LADING",
      "value": "123456789"
    },
    {
      "type": "CARRIER_SCAC",
      "value": "MSCU"
    },
    {
      "type": "CONTAINER_ID",
      "value": "PQRS7027376"
    },
    {
      "type": "CONTAINER_ID",
      "value": "GHJI7027376"
    }
  ]
}

The system asynchronously creates a related shipment for each container ID provided in the request. Once the related shipments are created, their details will be included in the relatedShipments array in the response. Example Response:

JSON
{
  "id": "45294f58-f87a-48e0-9f68-7d3f6e0aaa5j",
  "identifiers": [
    {
      "type": "BILL_OF_LADING",
      "value": "123456789"
    },
    {
      "type": "CARRIER_SCAC",
      "value": "MSCU"
    },
    {
      "type": "CONTAINER_ID",
      "value": "PQRS7027376"
    },
    {
      "type": "CONTAINER_ID",
      "value": "LMNO7027376"
    }
  ]
  "relatedShipments": [
    {
      "id": "609f4d0e-e75e-4eb8-ad7d-fd7e25f6f0a6",
      "identifiers": [
        {
          "type": "CONTAINER_ID",
          "value": "PQRS7027376"
        },
        {
          "type": "BILL_OF_LADING",
          "value": "123456789"
        },
        {
          "type": "CARRIER_SCAC",
          "value": "MSCU"
        }
      ]
    },
    {
      "id": "3dfaeff7-a92f-42e7-9bb9-6fb1e80059bb",
      "identifiers":  [
        {
          "type": "CONTAINER_ID",
          "value": "LMNO7027376"
        },
        {
          "type": "BILL_OF_LADING",
          "value": "123456789"
        },
        {
          "type": "CARRIER_SCAC",
          "value": "MSCU"
        }
      ]
    }
  ]
}

In this response you receive the identifiers used in the request (BILL_OF_LADING or BOOKING_NUMBER and CARRIER_SCAC) together with the Master Shipment ID (id) and all specified related container CONTAINER_IDs and ids.

This is an example of what could be returned in the response. Null fields will not show up in the response. Please refer to the reference data for more information on required and potential null fields.

Save the id. You’ll need it to retrieve tracking updates for this shipment.

Create Ocean Shipment via EDI

You can also create ocean shipments through Electronic Data Interchange (EDI). Project44 maintains robust EDI connectivity with leading ocean carriers, enabling shipment creation and milestone tracking via standardized formats such as EDIFACT and ANSI X12. To set up EDI integration with project44, please contact our Support Team.

Errors

If there was a problem with your request, you will receive one of the following error codes:

  • 400 Invalid request
  • 401 Invalid or missing credentials
  • 403 User not authorized to perform this operation

See Error Response Codes in the Appendix for more information on the meaning of these error codes.

Please refer to our Shipment Schema for more information on all fields and objects.

Previous page
Next page