Overview

Orders

Order represents a contract / intent of movement of goods from origin to destination. The Orders API provides visibility into your supply chain.

Loads

Load represents the actual movement of items on an order via a shipment. The Loads API provides visibility into order details as it travels between two stops. Loads can be visible across any mode of tracking, including Ocean, Air, Rail, TL, LTL, and Parcel.

The Orders API can be used in combination with the Loads API for a comparative view between contractual order dates and shipment delivery. Use these endpoints to create (POST), track (GET), update (PUT), or delete (DELETE) orders and loads.

Understanding relationship between Orders, Loads and Shipments

Before we dive into the specific APIs, it's important to know how does Orders relate to Loads and Shipments.

• An Order represents a contract / intent of movement of goods from an origin to destination.
• A Shipment represents an actual movement of freight from origin to destination. It has origin and destination, stop details, shipment identifiers etc.
• A Load represents the goods / items for one or multiple order(s) that are being shipped via a shipment.

Let's look at the below sequence of operations to understand more:

• A user creates an Order in their TMS which represents the set of goods/items that needs to be move from Origin to Destination

• Large orders with 1000s of goods / items would be carried via multiple loads and shipments

• User then creates all shipments that are required to fulfill the order. These shipments represent the physical movement of freight from origin to destination, but not the contents of the freight.

• User then creates all the loads necessary that are needed to ship the goods. These loads has details of the goods / items that are being shipped via the shipments created in the above step.

As you can see in the image below, load is the bridging entity between an order and a shipment

A load is linked to the shipment via the field masterShipmentId

A load is linked to order(s) via the items the load is carrying

Recommendation for Orders, Shipments and Loads integration

Below is sequence of operations recommended for integrating Orders, Shipments and Loads.

1. Create an Order.

POST /api/v4/inventory/orders
{
  "orderIdentifier": "PO123",
  "orderType": "PURCHASE_ORDER",
  "originLocation": { },
  "destinationLocation": { }
}

Response:
{
  "id": "<<ORDER-ID>>"
}

2. Create Items for the Order.

POST /api/v4/inventory/items
{
  "stockKeepingUnit": "SKU1",
  "orderIds": [
    "<<ORDER-ID>>"
  ],
  "inventoryDimensionalWeight": {
    "quantity": 100
  }
}

Response:
{
  "id": "<<ITEM-ID>>"
}

3. Create Shipment(s) for the Order. Use one the multiple APIs to create shipment(s).

POST /api/v4/shipments
{
  "identifiers": [
    {
      "type": "AIR_WAYBILL",
      "value": "string"
    }
  ],
  "routeInfo": {
    "stops": [
      {
        //STOP A Details
      },
      {
        //STOP B Details
      }
    ]
  }
}

Response:
{
  "id": "SHIPMENT-UUID",
  "routeInfo": {
    "stops": [
      {
        "id": "<<STOP_A_UUID>>"
        //More STOP_A details
      },
      {
      "id": "<<STOP_B_UUID>>"
        //More STOP_B details
      }
    ]
  }
}

4. Create Load.

POST /api/v4/loads
{
  "masterShipmentId": "SHIPMENT-UUID",
  "pickupStopReference": {
    "stopId": "<<STOP_A_UUID>>"
  },
  "deliveryStopReference": {
    "stopId": "<<STOP_B_UUID>>"
  },
  "items": [
    {
      "description": "SKU1",
      "orderIdentifierReferences": [
        {
          "orderType": "PURCHASE_ORDER",
          "orderIdentifier": "PO123"
        }
      ],
      "unitQuantity": 50
    }
  ]
}

Response:
{
  "id": "<<LOAD-UUID>>"
}

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
• 404 Not Found

Orders Operations

1. Get proper credentials.
2. Create an Order.
3. Get Order Information.
4. Update an Order.
5. Delete an Order.

Get Credentials

You must be provisioned with a tenant to have a client application within that tenant with the appropriate permissions to use any API within project44.

See here for more information on Authentication and Authorization.

Create an Order

Use the POST endpoint to create an Order.

• Required fields:

  • orderType

  • orderIdentifier

• Important fields:

  • orderTags

  • originLocation

  • destinationLocation

  • statusCode

  • supplierReadyDateTimeWindow

  • vendorLocation

• Deprecated fields:

  • relatedOrderIds
  • shipmentIds An order must be related to a shipment only via loads

A unique project44 ID is returned in the response after order creation. You can store this ID to use in future API calls.

Common Error Scenarios:

• orderTags list of size greater than 10 -> 400 error code
• Dates / date windows viz. orderSubmissionDateTime, supplierReadyDateTimeWindow, originalDeliveryDateTimeWindow are past the current date minus 1 year. -> 400 error code
• attributes list of size greater than 25 -> 400 error code
• dateTime attributes are not in the format yyyy-MM-dd'T'HH:mm:ssZ. Example 2019-11-14T12:30:00-0500 -> 400 error code.

Get Order Information

Use the GET endpoint to retrieve information about your Order.

Update an Order

Use the PUT endpoint to update an existing Order.

Common Error Scenarios:

• orderTags list of size greater than 10 -> 400 error code.
• Dates / date windows viz. orderSubmissionDateTime, supplierReadyDateTimeWindow, originalDeliveryDateTimeWindow are past the current date minus 1 year. -> 400 error code.
• attributes list of size greater than 25 -> 400 error code.
• dateTime attributes are not in the format yyyy-MM-dd'T'HH:mm:ssZ. Example 2019-11-14T12:30:00-0500 -> 400 error code.

Delete an Order

Use the DELETE endpoint to delete your Order.

Order Item Operations

An Item represents SKUs that need to moved as part of the order from order origin to the order destination.

Create an Item

Add items to an existing order

Common Error Scenarios:

• dateTime attributes are not in the format yyyy-MM-dd'T'HH:mm:ssZ. Example 2019-11-14T12:30:00-0500 -> 400 error code.

Update an Item

Use the PUT endpoint to update an existing Item. The item is updated asynchronously.

Common Error Scenarios:

• dateTime attributes are not in the format yyyy-MM-dd'T'HH:mm:ssZ. Example 2019-11-14T12:30:00-0500 -> 400 error code.

Delete an Item

Use the DELETE endpoint to delete an existing Item. The item is deleted asynchronously.

Load Operations

1. Get proper credentials.
2. Create a Load.
3. Get Load Information.
4. Update a Load.
5. Delete a Load.

Get Credentials

You must be provisioned with a tenant to have a client application within that tenant with the appropriate permissions to use any API within project44.

See here for more information on Authentication and Authorization.

Create a Load

Use the POST endpoint to create a Load. Load can and preferably should be created with masterShipmentId as shipment reference, but it is possible to create load with other shipment identifiers like BOL, AWB etc.

Important fields:

• items

• pickupStopReference.stopId - Essential for accurate ETA computation.

• deliveryStopReference.stopId- Essential for accurate ETA computation.

Get Load Information by Master Shipment ID

Use the GET endpoint to retrieve information about a Load by master shipment ID.

Get Load Information by Load ID

Use the GET endpoint to retrieve information about a Load by Load id.

Update a Load

Use the PUT endpoint to update a Load.

Delete a Load

Use the DELETE endpoint to delete a Load.