Parcel
6 min
Create Load API allows authorized users to create a new load for tracking. It is ideally called after the carrier has accepted the tender for the load. This example is for Parcel loads.
⚠️ Important Update:
The Pallets structure is being deprecated. Please transition to for product details. Learn more
This API is called after the carrier has accepted the tender for the load. FourKites does not limit customers from creating more than one load with the same load number or PRO number -- creation of more than one load with the same load or PRO number will cause duplication of loads, which will end up affecting the tracking performance. Customers are advised to handle this on their side. To learn more about Idempotency Protection, refer here.
If you receive a server error (5xx error code), please try again a few times. It's best to wait a little longer between each retry attempt. Try at least 3-5 times before giving up, as many server issues resolve themselves quickly.
Supporting Document: Create Shipment
Rate Limit
1 request per second
Format Supported
JSON
Authenticated Resource
API Key
For more information on Authentication, click here.
FourKites does not limit customers from creating more than one load with the same load number or PRO number. When making POST requests to create a load, please ensure that it is the first time that specific load number has been used to create a load. If multiple POST requests are made with the same data, FourKites will generate duplicate loads
Production
POST
https://api.fourkites.com/api/v1/tracking
import http.client
import json
conn = http.client.HTTPSConnection("api.fourkites.com")
payload = json.dumps({
"additionalData": {
"modeDetails": {
"shipperModes": "Parcel"
}
},
"load": {
"carrier": "cc79",
"haulType": [
"outbound_load"
],
"simultaneousTrackingReferenceNumber": "123456",
"simultaneousTrackingSequenceNumber": 1,
"masterSequenceNumber": "1",
"masterReferenceNumber": "83456",
"loadNumber": "ParcelTestNew",
"priority": "normal",
"trackingNumber": "1122334455",
"referenceNumbers": [
"XXX:11223344,11334455",
"YYY:123,54321",
"ZZZZ:C3212",
"Z1234",
"SCAC:XXXX"
],
"relayLoad": False,
"stops": [
{
"addressLine1": "500 West Madison Street",
"addressLine2": "Suite 3300",
"city": "Chicago",
"country": "US",
"name": "FourKites HQ",
"postalCode": "60611",
"referenceNumbers": [
"XXX:111",
"YYY:13445345",
"1232432",
"YY:F3234234"
],
"sequence": 1,
"state": "LA",
"stopReferenceId": "X12",
"stopType": "pickup",
"unloadTimeInMinutes": 120,
"timeInUtc": True,
"customer": {
"id": None,
"poNumbers": [
"04112024"
],
"pointOfContact": {
"email": "[email protected]",
"phone": "545454"
}
},
"earliestAppointmentTime": "2024-04-21T19:16:15",
"latestAppointmentTime": "2024-04-21T19:16:15",
"earliestWantTime": "2024-04-21T16:31:29",
"latestWantTime": "2024-04-21T16:31:29",
"pallets": [
{
"parts": [
{
"quantity": "XXX-YYY",
"shipperPartNumber": "1123",
"weight": "7.998"
},
{
"quantity": "YYY-ZZZ",
"shipperPartNumber": "33221",
"weight": "36.800"
}
]
}
],
"productLineItems": [
{
"productId": "0123456",
"productName": "Parcel Item",
"productDescription": "Parcel shipment item",
"productCategory": "General Merchandise",
"quantity": 5,
"measurementUnitCode": "PCE",
"netWeight": 44.8,
"weightUnit": "KGM",
"unitCost": 25,
"currencyCode": "USD",
"extendedCost": 125,
"freightCost": 10,
"bestBeforeDate": "2024-04-25T00:00:00Z",
"additionalCharges": 5,
"tariffCost": 2.5,
"fourKitesCalculatedTariffCost": 2.5,
"totalLandedCost": 132.5,
"countryOfOrigin": "US",
"harmonizedSystemCode": "4819500000",
"commodityTypeCode": "GENERAL_MERCHANDISE",
"htsusCode": "4819500000",
"orderNumber": "04112024",
"deliveryNumber": "DN-X12",
"handlingUnitId": "1123",
"barcode": "1123",
"containerType": "box",
"gtin": "00012345678905",
"customerPartNumber": "1123",
"supplierPartNumber": "1123",
"manufacturerPartNumber": "MFG-1123",
"itemNumber": "ITM-1123",
"productUpc": "012345678905",
"deliveryReferences": [
"YYY:13445345"
],
"orderReferences": [
"1232432"
],
"brandName": "Generic Merchandise Co",
"minimumTemperature": 0,
"maximumTemperature": 0,
"temperatureUnitCode": "cel",
"labelIdentifier": "LBL-1123",
"productTrackingNumber": "1122334455",
"deviceType": "RFID_TAG"
}
]
},
{
"addressLine1": "123 AB Avenue",
"addressLine2": "",
"city": "Los Angeles",
"country": "US",
"customer": {
"id": 1453242,
"poNumbers": [
"123413",
"123123"
],
"pointOfContact": {
"email": "[email protected]",
"phone": "1234456734"
}
},
"earliestAppointmentTime": "2024-04-22T19:16:15",
"latestAppointmentTime": "2024-04-22T19:16:15",
"earliestWantTime": "2024-04-22T16:31:29",
"latestWantTime": "2024-04-22T16:31:29",
"name": "XXXX, YY ZZ",
"pallets": [
{
"billOfLading": 43489495,
"number": "00001",
"parts": [
{
"quantity": "YYYYY-XXXXX",
"shipperPartNumber": "1234R",
"weight": "7.998"
},
{
"quantity": "ZZZZ-XXXX",
"shipperPartNumber": "1E2312",
"weight": "36.800"
}
]
}
],
"postalCode": "12341",
"referenceNumbers": [
"XXX:1223",
"YYY:123123",
"324234234",
"YY:D32412234"
],
"sequence": 2,
"state": "LA",
"stopReferenceId": "X12",
"stopType": "delivery",
"unloadTimeInMinutes": 120,
"timeInUtc": True,
"productLineItems": [
{
"productId": "0123456",
"productName": "Parcel Item",
"productDescription": "Parcel shipment item",
"productCategory": "General Merchandise",
"quantity": 5,
"measurementUnitCode": "PCE",
"netWeight": 44.8,
"weightUnit": "KGM",
"unitCost": 25,
"currencyCode": "USD",
"extendedCost": 125,
"freightCost": 10,
"additionalCharges": 5,
"tariffCost": 2.5,
"fourKitesCalculatedTariffCost": 2.5,
"totalLandedCost": 132.5,
"countryOfOrigin": "US",
"harmonizedSystemCode": "4819500000",
"commodityTypeCode": "GENERAL_MERCHANDISE",
"htsusCode": "4819500000",
"orderNumber": "123413",
"deliveryNumber": "DN-X12-2",
"handlingUnitId": "00001",
"barcode": "1234R",
"containerType": "box",
"gtin": "00012345678912",
"customerPartNumber": "1234R",
"supplierPartNumber": "1234R",
"manufacturerPartNumber": "MFG-1234R",
"itemNumber": "ITM-1234R",
"productUpc": "012345678912",
"deliveryReferences": [
"YYY:123123"
],
"orderReferences": [
"324234234"
],
"brandName": "Generic Merchandise Co",
"minimumTemperature": 0,
"maximumTemperature": 0,
"temperatureUnitCode": "cel",
"labelIdentifier": "LBL-1234R",
"productTrackingNumber": "1122334455",
"deviceType": "QR_CODE"
}
]
}
]
}
})
headers = {
'Content-Type': 'application/json',
'apikey': 'REPLACE_KEY_VALUE'
}
conn.request("POST", "/api/v1/tracking", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))Staging
POST
https://api-staging.fourkites.com/api/v1/tracking
import http.client
import json
conn = http.client.HTTPSConnection("api-staging.fourkites.com")
payload = json.dumps({
"additionalData": {
"modeDetails": {
"shipperModes": "Parcel"
}
},
"load": {
"carrier": "cc79",
"haulType": [
"outbound_load"
],
"simultaneousTrackingReferenceNumber": "123456",
"simultaneousTrackingSequenceNumber": 1,
"masterSequenceNumber": "1",
"masterReferenceNumber": "83456",
"loadNumber": "ParcelTestNew",
"priority": "normal",
"trackingNumber": "1122334455",
"referenceNumbers": [
"XXX:11223344,11334455",
"YYY:123,54321",
"ZZZZ:C3212",
"Z1234",
"SCAC:XXXX"
],
"relayLoad": False,
"stops": [
{
"addressLine1": "500 West Madison Street",
"addressLine2": "Suite 3300",
"city": "Chicago",
"country": "US",
"name": "FourKites HQ",
"postalCode": "60611",
"referenceNumbers": [
"XXX:111",
"YYY:13445345",
"1232432",
"YY:F3234234"
],
"sequence": 1,
"state": "LA",
"stopReferenceId": "X12",
"stopType": "pickup",
"unloadTimeInMinutes": 120,
"timeInUtc": True,
"customer": {
"id": None,
"poNumbers": [
"04112024"
],
"pointOfContact": {
"email": "[email protected]",
"phone": "545454"
}
},
"earliestAppointmentTime": "2024-04-21T19:16:15",
"latestAppointmentTime": "2024-04-21T19:16:15",
"earliestWantTime": "2024-04-21T16:31:29",
"latestWantTime": "2024-04-21T16:31:29",
"pallets": [
{
"parts": [
{
"quantity": "XXX-YYY",
"shipperPartNumber": "1123",
"weight": "7.998"
},
{
"quantity": "YYY-ZZZ",
"shipperPartNumber": "33221",
"weight": "36.800"
}
]
}
],
"productLineItems": [
{
"productId": "0123456",
"productName": "Parcel Item",
"productDescription": "Parcel shipment item",
"productCategory": "General Merchandise",
"quantity": 5,
"measurementUnitCode": "PCE",
"netWeight": 44.8,
"weightUnit": "KGM",
"unitCost": 25,
"currencyCode": "USD",
"extendedCost": 125,
"freightCost": 10,
"bestBeforeDate": "2024-04-25T00:00:00Z",
"additionalCharges": 5,
"tariffCost": 2.5,
"fourKitesCalculatedTariffCost": 2.5,
"totalLandedCost": 132.5,
"countryOfOrigin": "US",
"harmonizedSystemCode": "4819500000",
"commodityTypeCode": "GENERAL_MERCHANDISE",
"htsusCode": "4819500000",
"orderNumber": "04112024",
"deliveryNumber": "DN-X12",
"handlingUnitId": "1123",
"barcode": "1123",
"containerType": "box",
"gtin": "00012345678905",
"customerPartNumber": "1123",
"supplierPartNumber": "1123",
"manufacturerPartNumber": "MFG-1123",
"itemNumber": "ITM-1123",
"productUpc": "012345678905",
"deliveryReferences": [
"YYY:13445345"
],
"orderReferences": [
"1232432"
],
"brandName": "Generic Merchandise Co",
"minimumTemperature": 0,
"maximumTemperature": 0,
"temperatureUnitCode": "cel",
"labelIdentifier": "LBL-1123",
"productTrackingNumber": "1122334455",
"deviceType": "RFID_TAG"
}
]
},
{
"addressLine1": "123 AB Avenue",
"addressLine2": "",
"city": "Los Angeles",
"country": "US",
"customer": {
"id": 1453242,
"poNumbers": [
"123413",
"123123"
],
"pointOfContact": {
"email": "[email protected]",
"phone": "1234456734"
}
},
"earliestAppointmentTime": "2024-04-22T19:16:15",
"latestAppointmentTime": "2024-04-22T19:16:15",
"earliestWantTime": "2024-04-22T16:31:29",
"latestWantTime": "2024-04-22T16:31:29",
"name": "XXXX, YY ZZ",
"pallets": [
{
"billOfLading": 43489495,
"number": "00001",
"parts": [
{
"quantity": "YYYYY-XXXXX",
"shipperPartNumber": "1234R",
"weight": "7.998"
},
{
"quantity": "ZZZZ-XXXX",
"shipperPartNumber": "1E2312",
"weight": "36.800"
}
]
}
],
"postalCode": "12341",
"referenceNumbers": [
"XXX:1223",
"YYY:123123",
"324234234",
"YY:D32412234"
],
"sequence": 2,
"state": "LA",
"stopReferenceId": "X12",
"stopType": "delivery",
"unloadTimeInMinutes": 120,
"timeInUtc": True,
"productLineItems": [
{
"productId": "0123456",
"productName": "Parcel Item",
"productDescription": "Parcel shipment item",
"productCategory": "General Merchandise",
"quantity": 5,
"measurementUnitCode": "PCE",
"netWeight": 44.8,
"weightUnit": "KGM",
"unitCost": 25,
"currencyCode": "USD",
"extendedCost": 125,
"freightCost": 10,
"additionalCharges": 5,
"tariffCost": 2.5,
"fourKitesCalculatedTariffCost": 2.5,
"totalLandedCost": 132.5,
"countryOfOrigin": "US",
"harmonizedSystemCode": "4819500000",
"commodityTypeCode": "GENERAL_MERCHANDISE",
"htsusCode": "4819500000",
"orderNumber": "123413",
"deliveryNumber": "DN-X12-2",
"handlingUnitId": "00001",
"barcode": "1234R",
"containerType": "box",
"gtin": "00012345678912",
"customerPartNumber": "1234R",
"supplierPartNumber": "1234R",
"manufacturerPartNumber": "MFG-1234R",
"itemNumber": "ITM-1234R",
"productUpc": "012345678912",
"deliveryReferences": [
"YYY:123123"
],
"orderReferences": [
"324234234"
],
"brandName": "Generic Merchandise Co",
"minimumTemperature": 0,
"maximumTemperature": 0,
"temperatureUnitCode": "cel",
"labelIdentifier": "LBL-1234R",
"productTrackingNumber": "1122334455",
"deviceType": "QR_CODE"
}
]
}
]
}
})
headers = {
'Content-Type': 'application/json',
'apikey': 'REPLACE_KEY_VALUE'
}
conn.request("POST", "/api/v1/tracking", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))Azure - Production
POST
https://api.ng.fourkites.com/api/v1/tracking
import http.client
import json
conn = http.client.HTTPSConnection("api.ng.fourkites.com")
payload = json.dumps({
"additionalData": {
"modeDetails": {
"shipperModes": "Parcel"
}
},
"load": {
"carrier": "cc79",
"haulType": [
"outbound_load"
],
"simultaneousTrackingReferenceNumber": "123456",
"simultaneousTrackingSequenceNumber": 1,
"masterSequenceNumber": "1",
"masterReferenceNumber": "83456",
"loadNumber": "ParcelTestNew",
"priority": "normal",
"trackingNumber": "1122334455",
"referenceNumbers": [
"XXX:11223344,11334455",
"YYY:123,54321",
"ZZZZ:C3212",
"Z1234",
"SCAC:XXXX"
],
"relayLoad": False,
"stops": [
{
"addressLine1": "500 West Madison Street",
"addressLine2": "Suite 3300",
"city": "Chicago",
"country": "US",
"name": "FourKites HQ",
"postalCode": "60611",
"referenceNumbers": [
"XXX:111",
"YYY:13445345",
"1232432",
"YY:F3234234"
],
"sequence": 1,
"state": "LA",
"stopReferenceId": "X12",
"stopType": "pickup",
"unloadTimeInMinutes": 120,
"timeInUtc": True,
"customer": {
"id": None,
"poNumbers": [
"04112024"
],
"pointOfContact": {
"email": "[email protected]",
"phone": "545454"
}
},
"earliestAppointmentTime": "2024-04-21T19:16:15",
"latestAppointmentTime": "2024-04-21T19:16:15",
"earliestWantTime": "2024-04-21T16:31:29",
"latestWantTime": "2024-04-21T16:31:29",
"pallets": [
{
"parts": [
{
"quantity": "XXX-YYY",
"shipperPartNumber": "1123",
"weight": "7.998"
},
{
"quantity": "YYY-ZZZ",
"shipperPartNumber": "33221",
"weight": "36.800"
}
]
}
]
},
{
"addressLine1": "123 AB Avenue",
"addressLine2": "",
"city": "Los Angeles",
"country": "US",
"customer": {
"id": 1453242,
"poNumbers": [
"123413",
"123123"
],
"pointOfContact": {
"email": "[email protected]",
"phone": "1234456734"
}
},
"earliestAppointmentTime": "2024-04-22T19:16:15",
"latestAppointmentTime": "2024-04-22T19:16:15",
"earliestWantTime": "2024-04-22T16:31:29",
"latestWantTime": "2024-04-22T16:31:29",
"name": "XXXX, YY ZZ",
"pallets": [
{
"billOfLading": 43489495,
"number": "00001",
"parts": [
{
"quantity": "YYYYY-XXXXX",
"shipperPartNumber": "1234R",
"weight": "7.998"
},
{
"quantity": "ZZZZ-XXXX",
"shipperPartNumber": "1E2312",
"weight": "36.800"
}
]
}
],
"postalCode": "12341",
"referenceNumbers": [
"XXX:1223",
"YYY:123123",
"324234234",
"YY:D32412234"
],
"sequence": 2,
"state": "LA",
"stopReferenceId": "X12",
"stopType": "delivery",
"unloadTimeInMinutes": 120,
"timeInUtc": True
}
]
}
})
headers = {
'Content-Type': 'application/json',
'apikey': 'REPLACE_KEY_VALUE'
}
conn.request("POST", "/api/v1/tracking", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))Azure - Staging
POST
https://api-staging.ng.fourkites.com/api/v1/tracking
import http.client
import json
conn = http.client.HTTPSConnection("api-staging.ng.fourkites.com")
payload = json.dumps({
"additionalData": {
"modeDetails": {
"shipperModes": "Parcel"
}
},
"load": {
"carrier": "cc79",
"haulType": [
"outbound_load"
],
"simultaneousTrackingReferenceNumber": "123456",
"simultaneousTrackingSequenceNumber": 1,
"masterSequenceNumber": "1",
"masterReferenceNumber": "83456",
"loadNumber": "ParcelTestNew",
"priority": "normal",
"trackingNumber": "1122334455",
"referenceNumbers": [
"XXX:11223344,11334455",
"YYY:123,54321",
"ZZZZ:C3212",
"Z1234",
"SCAC:XXXX"
],
"relayLoad": False,
"stops": [
{
"addressLine1": "500 West Madison Street",
"addressLine2": "Suite 3300",
"city": "Chicago",
"country": "US",
"name": "FourKites HQ",
"postalCode": "60611",
"referenceNumbers": [
"XXX:111",
"YYY:13445345",
"1232432",
"YY:F3234234"
],
"sequence": 1,
"state": "LA",
"stopReferenceId": "X12",
"stopType": "pickup",
"unloadTimeInMinutes": 120,
"timeInUtc": True,
"customer": {
"id": None,
"poNumbers": [
"04112024"
],
"pointOfContact": {
"email": "[email protected]",
"phone": "545454"
}
},
"earliestAppointmentTime": "2024-04-21T19:16:15",
"latestAppointmentTime": "2024-04-21T19:16:15",
"earliestWantTime": "2024-04-21T16:31:29",
"latestWantTime": "2024-04-21T16:31:29",
"pallets": [
{
"parts": [
{
"quantity": "XXX-YYY",
"shipperPartNumber": "1123",
"weight": "7.998"
},
{
"quantity": "YYY-ZZZ",
"shipperPartNumber": "33221",
"weight": "36.800"
}
]
}
]
},
{
"addressLine1": "123 AB Avenue",
"addressLine2": "",
"city": "Los Angeles",
"country": "US",
"customer": {
"id": 1453242,
"poNumbers": [
"123413",
"123123"
],
"pointOfContact": {
"email": "[email protected]",
"phone": "1234456734"
}
},
"earliestAppointmentTime": "2024-04-22T19:16:15",
"latestAppointmentTime": "2024-04-22T19:16:15",
"earliestWantTime": "2024-04-22T16:31:29",
"latestWantTime": "2024-04-22T16:31:29",
"name": "XXXX, YY ZZ",
"pallets": [
{
"billOfLading": 43489495,
"number": "00001",
"parts": [
{
"quantity": "YYYYY-XXXXX",
"shipperPartNumber": "1234R",
"weight": "7.998"
},
{
"quantity": "ZZZZ-XXXX",
"shipperPartNumber": "1E2312",
"weight": "36.800"
}
]
}
],
"postalCode": "12341",
"referenceNumbers": [
"XXX:1223",
"YYY:123123",
"324234234",
"YY:D32412234"
],
"sequence": 2,
"state": "LA",
"stopReferenceId": "X12",
"stopType": "delivery",
"unloadTimeInMinutes": 120,
"timeInUtc": True
}
]
}
})
headers = {
'Content-Type': 'application/json',
'apikey': 'REPLACE_KEY_VALUE'
}
conn.request("POST", "/api/v1/tracking", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))