Manage & Track Freight Shipments

Once freight is booked, these endpoints retrieve it, download its paperwork, follow it in transit, and cancel it if plans change. See Quote & Book Freight for the booking itself.

GET /v2/freight/shipments

Return the freight shipments on your account, most recently created first.

curl -i -X GET \
  'https://api.shipstation.com/v2/freight/shipments?page=1&page_size=50' \
  -H 'api-key: YOUR_API_KEY_HERE'

Results are paginated with page and page_size. The default page size is 25 and the maximum is 500 — larger values are capped rather than rejected, and page values below 1 are treated as 1.

{
  "shipments": [
    {
      "freight_shipment_id": "se-98765432",
      "freight_provider_account_id": "se-4821",
      "freight_provider_name": "UNISHIPPERS",
      "status": "in_transit",
      "bol_number": "BOL-20260417-4821",
      "pro_number": "072-51293847",
      "documents": [
        {
          "type": "bill_of_lading",
          "url": "/v2/downloads/10/a1b2c3d4e5f6/bill_of_lading.pdf"
        }
      ]
    }
  ],
  "total": 137,
  "page": 1,
  "page_size": 25,
  "pages": 6
}

GET /v2/freight/shipments/:freight_shipment_id

Retrieve a single freight shipment with its current status, carrier reference numbers, and documents.

curl -i -X GET \
  https://api.shipstation.com/v2/freight/shipments/se-98765432 \
  -H 'api-key: YOUR_API_KEY_HERE'

The status here is the stored status, updated as tracking is received. To pull fresh status from the carrier, use Get freight shipment tracking.

An unknown ID returns a 404 with error code invalid_identifier, and field_name set to freight_shipment_id.

GET /v2/freight/shipments/:freight_shipment_id/documents

List the paperwork for a shipment, with a download URL for each document.

curl -i -X GET \
  https://api.shipstation.com/v2/freight/shipments/se-98765432/documents \
  -H 'api-key: YOUR_API_KEY_HERE'

{
  "documents": [
    {
      "type": "bill_of_lading",
      "created_at": "2026-04-16T14:32:07Z",
      "url": "/v2/downloads/10/a1b2c3d4e5f6/bill_of_lading.pdf"
    },
    {
      "type": "pallet_label",
      "created_at": "2026-04-16T14:32:07Z",
      "url": "/v2/downloads/10/a1b2c3d4e5f6/pallet_label.pdf"
    }
  ]
}

Each url is a path relative to the API host — resolve it against https://api.shipstation.com and fetch it with your API key to get the PDF.

Documents appear as the shipment progresses. The Bill of Lading and pallet labels are generated at booking; a weight and inspection certificate appears if the carrier reweighs the freight; the proof of delivery only exists after delivery. Poll this endpoint, or watch tracking events, rather than expecting the full set up front.

GET /v2/freight/shipments/:freight_shipment_id/tracking

Retrieve live status and event history from the carrier for a booked shipment.

curl -i -X GET \
  https://api.shipstation.com/v2/freight/shipments/se-98765432/tracking \
  -H 'api-key: YOUR_API_KEY_HERE'

The shipment is tracked by its PRO number when the carrier has assigned one, and by its BOL number otherwise.

{
  "freight_shipment_id": "se-98765432",
  "freight_provider_account_id": "se-4821",
  "freight_provider_name": "UNISHIPPERS",
  "carrier_scac": "FXFE",
  "bol_number": "BOL-20260417-4821",
  "pro_number": "072-51293847",
  "status": "in_transit",
  "tracking_status": "in_transit",
  "estimated_delivery_date": "2026-04-22",
  "tracking_url": "https://www.fedex.com/fedextrack/?trknbr=07251293847",
  "last_event_at": "2026-04-20T14:05:00Z",
  "events": [
    {
      "occurred_at": "2026-04-17T10:22:00Z",
      "status": "at_pickup",
      "carrier_code": "AP",
      "description": "Freight picked up in Grand Rapids, MI",
      "documents": []
    },
    {
      "occurred_at": "2026-04-20T14:05:00Z",
      "status": "in_transit",
      "carrier_code": "AF",
      "description": "Departed terminal in Grand Rapids, MI",
      "documents": []
    }
  ]
}

Read status for a coarse state and tracking_status for the carrier's detail. Both are described in Statuses. estimated_delivery_date is a YYYY-MM-DD date, while occurred_at and last_event_at are timestamps; carriers that report only a date return midnight as the time.

Events can carry documents, most usefully a proof of delivery attached to the delivery event.

A shipment with neither a PRO nor a BOL number cannot be tracked, and returns:

{
  "request_id": "4b8e2f4c-1f6f-4b1a-9c4a-8f5e6d7c8b9a",
  "errors": [
    {
      "error_source": "shipengine",
      "error_type": "business_rules",
      "error_code": "freight_tracking_not_available",
      "message": "Tracking is not yet available for this shipment. A PRO or BOL number is required."
    }
  ]
}

This is expected in the window right after booking. Treat it as "not yet" rather than as a failure, and retry later.

The other outcomes this endpoint can return:

A successful call also writes the carrier's status back to the stored shipment — its status, tracking status, and last-event timestamp — so Get freight shipment by ID reflects what tracking last returned. The write is best-effort: if it fails, you still get the tracking response. The PRO number is not updated this way, so a shipment tracked by BOL number keeps a null pro_number in the stored record.

GET /v2/freight/tracking

Track any freight shipment by its PRO or BOL number, whether or not it was booked through ShipStation. This is the endpoint to use for freight booked elsewhere, or when all you have is a number from a supplier.

curl -i -X GET \
  'https://api.shipstation.com/v2/freight/tracking?freight_provider_account_id=se-4821&tracking_number=072-51293847&tracking_type=pro_number&carrier_scac=FXFE' \
  -H 'api-key: YOUR_API_KEY_HERE'

GET /v2/freight/tracking?freight_provider_account_id=se-4821&tracking_number=072-51293847&tracking_type=pro_number&carrier_scac=FXFE

The response is the same shape as shipment tracking, minus freight_shipment_id, status, and estimated_delivery_date, since the number may not correspond to a shipment on your account. Read tracking_status for the carrier's state, and take the estimated delivery date from the events if you need it.

Nothing is stored as a result of this call — it is a pass-through to the provider. Tracking a number that happens to belong to one of your own shipments does not update that shipment's stored status; use Get freight shipment tracking for that.

carrier_scac in the response is the SCAC the carrier reported back, not the one you sent, so it can be null even on a successful lookup.

Its failure modes:

DELETE /v2/freight/shipments/:freight_shipment_id

Cancel a booked shipment with the carrier.

curl -i -X DELETE \
  https://api.shipstation.com/v2/freight/shipments/se-98765432 \
  -H 'api-key: YOUR_API_KEY_HERE'

{
  "freight_shipment_id": "se-98765432",
  "cancelled_transactions": [
    "7f1c9a52-3d84-4f0e-9b3a-2c6d5e4f8a10",
    "3ac81f60-92b7-4de1-8f04-5b9a7c2e6d13"
  ]
}

cancelled_transactions lists what was actually cancelled at the provider — typically the booked shipment and the pickup request.