Last updated

Creating a Shipment

Creating an Extended Ocean shipment by using the Unified API endpoint allows you to add the shipment to Project44's tracking system which sources data from multiple freight forwarders and ocean carriers. You can then view and subscribe to the tracking data via APIs, Movement UI or Webhooks.

Create a simple extended ocean shipment

Simple extended ocean tracking involves creating a shipment with a single freight forwarder SCAC and a single shipment identifier. This is the most common use case and a bare minimum to get started with extended ocean visibility.

Requirements

After authentication, the following data points are required to create a shipment

  • One shipment identifier: HOUSE_BILL_OF_LADING or TRACKING_NUMBER
  • Exactly one freight forwarder SCAC. View the Freight Forwarder List for available SCACs.

Workflow

  1. Prepare a POST request to /api/v4/shipments/tracking.

  2. Add the shipment identifiers to the request schema. For example,

    {
  "identifiers": [
    {
      "type": "HOUSE_BILL_OF_LADING",
      "value": "string"
    },
    {
      "type": "FFW_SCAC",
      "value": "string"
    }
  ]
}

    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.

  3. Send the request and wait for the response. The expected response schema when you receive a 200 OK response is described below.

    {
  "id": "uuid",
  "identifiers": [
    {
      "type": "HOUSE_BILL_OF_LADING",
      "value": "string"
    },
    {
      "type": "FFW_SCAC",
      "value": "string"
    }
  ],
  "shipmentShareLink": "link",
  "createdDateTime": "YYYY-MM-DDTHH:mm:ssZ"
}
    • In this response you receive the identifiers used in the request plus the UUID (id).
    • 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.
    • Store the id. Use the id to get shipment tracking updates in the next step.

Asynchronous Tracking Process

1. Commence freight forwarder tracking

  • Once the request is received, Project44 will validate and subscribe to freight forwarder for the shipment using the provided identifiers.
  • If and when the freight forwarder is in the network and provides data, it will be processed and stored in Project44's system.
  • Along with shipment tracking data, the freight forwarder connection will also provide the ocean carrier data corresponding to the main ocean leg.
  • Freight forwarder connections also provide information into the containers associated with the shipment, which will be stored in Project44's system as related shipments.

Shipment won't ever track and remain in a pending state if the conditions mentioned in When Does P44 Initiate Tracking Extended Ocean Shipments? are not met.

2. Additional ocean carrier tracking

  • If the freight forwarder connection provides the ocean carrier data corresponding to the main ocean leg, and the container data, it will be ingested and stored in Project44's system.
  • If the ocean carrier discovered is in Project44's network, it will then subscribe to the ocean carrier for the shipment using the discovered identifiers using P2P Ocean Carrier Tracking Capability.

Ocean carrier tracking is only done for containers provided by the freight forwarder connection. If the freight forwarder connection does not provide container data, then the ocean carrier tracking will not be done.

Create an extended ocean shipment with freight forwarder and ocean carrier

This use case allows you to create a shipment with both a freight forwarder SCAC and an ocean carrier SCAC. This can be used if you have the ocean carrier SCAC available at the time of creating the shipment.

Requirements

After authentication, the following data points are required to create a shipment

  • One freight forwarder shipment identifier: HOUSE_BILL_OF_LADING or TRACKING_NUMBER
  • Exactly one freight forwarder SCAC. View the Freight Forwarder List for available SCACs.
  • One ocean carrier shipment identifier: BOOKING_NUMBER or BILL_OF_LADING
  • Exactly one ocean carrier SCAC. View the Ocean Carrier List for available SCACs.

Workflow

  1. Prepare a POST request to /api/v4/shipments/tracking.

  2. Add the shipment identifiers to the request schema. For example,

    {
  "identifiers": [
    {
      "type": "HOUSE_BILL_OF_LADING",
      "value": "string"
    },
    {
      "type": "FFW_SCAC",
      "value": "string"
    },
    {
      "type": "BOOKING_NUMBER",
      "value": "string"
    },
    {
      "type": "CARRIER_SCAC",
      "value": "string"
    }
  ]
}

    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.

  3. Send the request and wait for the response. The expected response schema when you receive a 200 OK response is described below.

    {
  "id": "uuid",
  "identifiers": [
    {
      "type": "HOUSE_BILL_OF_LADING",
      "value": "string"
    },
    {
      "type": "FFW_SCAC",
      "value": "string"
    },
    {
      "type": "BOOKING_NUMBER",
      "value": "string"
    },
    {
      "type": "CARRIER_SCAC",
      "value": "string"
    }
  ],
  "shipmentShareLink": "link",
  "createdDateTime": "YYYY-MM-DDTHH:mm:ssZ"
}
    • In this response you receive the identifiers used in the request plus the UUID (id).
    • 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.
    • Store the id. Use the id to get shipment tracking updates in the next step.

Asynchronous Tracking Process

1. Commence freight forwarder tracking

  • Once the request is received, Project44 will validate and subscribe to freight forwarder for the shipment using the provided identifiers.
  • If and when the freight forwarder is in the network and provides data, it will be processed and stored in Project44's system.
  • Freight forwarder connections also provide information into the containers associated with the shipment, which will be stored and tracked separately in Project44's system as related shipments.

Shipment won't ever track and remain in a pending state if the conditions mentioned in When Does P44 Initiate Tracking Extended Ocean Shipments? are not met.

2. Commence ocean carrier tracking

  • If the freight forwarder connection provides the container data associated with the shipment, it will be ingested and stored in Project44's system.
  • Once the container data is stored, if the ocean carrier provided is in Project44's network, system will then subscribe to the ocean carrier with the identifier given using P2P Ocean Carrier Tracking Capability.

Ocean carrier tracking is only done for containers provided by the freight forwarder connection. If the freight forwarder connection does not provide container data, then the ocean carrier tracking will not be done.

Create an extended ocean shipment with associated containers

This use case allows you to create a shipment while specifying the containers associated with the shipment. This is useful if you have the container numbers available at the time of creating the shipment.

This use case is particularly advantageous as the ocean carrier tracking will be commenced for the containers provided from the start, and the shipment will receive updates with very minimal delay.

Requirements

After authentication, the following data points are required to create a shipment

  • One freight forwarder shipment identifier: HOUSE_BILL_OF_LADING or TRACKING_NUMBER
  • Exactly one freight forwarder SCAC. View the Freight Forwarder List for available SCACs.
  • One ocean carrier shipment identifier: BOOKING_NUMBER or BILL_OF_LADING
  • Exactly one ocean carrier SCAC. View the Ocean Carrier List for available SCACs.
  • At least one container number.

Workflow

  1. Prepare a POST request to /api/v4/shipments/tracking.

  2. Add the shipment identifiers and containers to the request schema. For example,

    {
  "identifiers": [
    {
      "type": "HOUSE_BILL_OF_LADING",
      "value": "string"
    },
    {
      "type": "FFW_SCAC",
      "value": "string"
    },
    {
      "type": "BOOKING_NUMBER",
      "value": "string"
    },
    {
      "type": "CARRIER_SCAC",
      "value": "string"
    }
  ],
  "relatedShipments": [
    {
      "identifiers": [
        {
          "type": "CONTAINER_NUMBER",
          "value": "container 1"
        }
      ]
    },
    {
      "identifiers": [
        {
          "type": "CONTAINER_NUMBER",
          "value": "container 2"
        }
      ]
    }
  ]
}

    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.

  3. Send the request and wait for the response. The expected response schema when you receive a 200 OK response is described below.

    {
  "id": "uuid",
  "identifiers": [
    {
      "type": "HOUSE_BILL_OF_LADING",
      "value": "string"
    },
    {
      "type": "FFW_SCAC",
      "value": "string"
    },
    {
      "type": "BOOKING_NUMBER",
      "value": "string"
    },
    {
      "type": "CARRIER_SCAC",
      "value": "string"
    }
  ],
  "relatedShipments": [
    {
      "id": "uuid",
      "identifiers": [
        {
          "type": "CONTAINER_NUMBER",
          "value": "container 1"
        }
      ],
      "shipmentShareLink": "link",
      "createdDateTime": "YYYY-MM-DDTHH:mm:ssZ"
    },
    {
      "id": "uuid",
      "identifiers": [
        {
          "type": "CONTAINER_NUMBER",
          "value": "container 2"
        }
      ],
      "shipmentShareLink": "link",
      "createdDateTime": "YYYY-MM-DDTHH:mm:ssZ"
    }
  ],
  "shipmentShareLink": "link",
  "createdDateTime": "YYYY-MM-DDTHH:mm:ssZ"
}
    • In this response you receive the identifiers used in the request plus the UUID (id) for the main shipment and the related shipments.
    • 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.
    • Store the id for the main shipment and the related shipments. Use the id to get shipment tracking updates in the next step.

Asynchronous Tracking Process

1. Commence freight forwarder tracking

  • Once the request is received, Project44 will validate and subscribe to freight forwarder for the shipment using the provided identifiers.
  • If and when the freight forwarder is in the network and provides data, it will be processed and stored in Project44's system.
  • Freight forwarder connections also provide information into the containers associated with the shipment, which will be stored and tracked separately in Project44's system as related shipments.

Shipment won't ever track and remain in a pending state if the conditions mentioned in When Does P44 Initiate Tracking Extended Ocean Shipments? are not met.

2. Commence ocean carrier tracking

Ocean carrier tracking is only done for containers provided during shipment creation or added later via freight forwarder connection.

Create an extended ocean shipment and track only specific containers

This use case allows you to track only specific containers associated with the shipment. This is useful if you have the container numbers available at the time of creating the shipment and want to track only those containers, avoiding the discovery of additional containers via the freight forwarder connection.

Requirements

After authentication, the following data points are required to create a shipment

  • One freight forwarder shipment identifier: HOUSE_BILL_OF_LADING or TRACKING_NUMBER
  • Exactly one freight forwarder SCAC. View the Freight Forwarder List for available SCACs.

Workflow

  1. Prepare a POST request to /api/v4/shipments/tracking.

  2. Add the shipment identifiers and containers to the request schema. For example,

    {
  "identifiers": [
    {
      "type": "HOUSE_BILL_OF_LADING",
      "value": "string"
    },
    {
      "type": "FFW_SCAC",
      "value": "string"
    },
    {
      "type": "CONTAINER_NUMBER",
      "value": "container 1"
    },
    {
      "type": "CONTAINER_NUMBER",
      "value": "container 2"
    }
  ]
}

    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.

  3. Send the request and wait for the response. The expected response schema when you receive a 200 OK response is described below.

    {
  "id": "uuid",
  "identifiers": [
    {
      "type": "HOUSE_BILL_OF_LADING",
      "value": "string"
    },
    {
      "type": "FFW_SCAC",
      "value": "string"
    },
    {
      "type": "CONTAINER_NUMBER",
      "value": "container 1"
    },
    {
      "type": "CONTAINER_NUMBER",
      "value": "container 2"
    }
  ],
  "shipmentShareLink": "link",
  "createdDateTime": "YYYY-MM-DDTHH:mm:ssZ"
}
    • In this response you receive the identifiers used in the request plus the UUID (id).
    • 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.
    • Store the id. Use the id to get shipment tracking updates in the next step.

Asynchronous Tracking Process

1. Commence freight forwarder tracking

  • Once the request is received, Project44 will validate and subscribe to freight forwarder for the shipment using the provided identifiers.
  • If and when the freight forwarder is in the network and provides data, it will be processed and stored in Project44's system.
  • Freight forwarder connections also provide information into the containers associated with the shipment, which will be stored and tracked separately in Project44's system as related shipments.
  • Only the containers provided in the request will be tracked. If the freight forwarder connection discovers additional containers, they will not be created and tracked.

Shipment won't ever track and remain in a pending state if the conditions mentioned in When Does P44 Initiate Tracking Extended Ocean Shipments? are not met.

2. Commence ocean carrier tracking

  • If the ocean carrier provided is in Project44's network, system will then subscribe to the ocean carrier with the identifier given using P2P Ocean Carrier Tracking Capability.
  • Ocean carrier tracking is only done for containers provided during shipment creation.
Previous page
Next page