Carrier Invoice Data

This guide covers two approaches for accessing carrier invoice data through the Trackstar Carrier API: retrieving parsed line item data as JSON, or downloading raw invoice files.

Overview

Carrier integrations (e.g. UPS, FedEx, USPS, DHL) provide invoice data in two formats:

Invoice Line Items — parsed, structured JSON data for each individual charge
Files — raw invoice documents (CSVs, PDFs) for download

Understanding invoice line items

A carrier invoice is a bill for services rendered over a billing period. Each invoice contains many individual charges — each one becomes a separate line item in the Trackstar API. One shipment → many line items. A single FedEx shipment from Chicago to London might appear on an invoice as:

`tracking_number`	`charge_description`	`net_cost`
`794612345678`	Freight	$42.18
`794612345678`	Fuel Surcharge	$6.33
`794612345678`	Residential Delivery	$4.50

All three rows share a tracking_number and invoice_id but have different charge_description and net_cost values. To get the total cost of a shipment, sum net_cost across all line items with the same tracking_number. Invoice shapes vary by carrier. Each carrier delivers invoice data in its own CSV/PDF format. Trackstar normalizes them into the line-item schema, but the raw files are also available via the Files endpoint. See Carrier Sample Files for exact shapes per integration.

Option 1: Invoice Line Items (JSON)

Use the Get Invoice Line Items endpoint to retrieve parsed invoice charges. Each line item contains cost details, transaction dates, and charge descriptions.

curl -X GET https://production.trackstarhq.com/carrier/invoice-line-items \
  -H "x-trackstar-api-key: YOUR_API_KEY" \
  -H "x-trackstar-access-token: YOUR_ACCESS_TOKEN"

import requests

url = "https://production.trackstarhq.com/carrier/invoice-line-items"

headers = {
    "x-trackstar-api-key": "YOUR_API_KEY",
    "x-trackstar-access-token": "YOUR_ACCESS_TOKEN"
}

response = requests.get(url, headers=headers)
data = response.json()

for item in data["data"]:
    print(f"Invoice {item['invoice_id']}: {item['charge_description']} - ${item['net_cost']}")

const url = "https://production.trackstarhq.com/carrier/invoice-line-items";

const response = await fetch(url, {
  headers: {
    "x-trackstar-api-key": "YOUR_API_KEY",
    "x-trackstar-access-token": "YOUR_ACCESS_TOKEN"
  }
});

const { data } = await response.json();

for (const item of data) {
  console.log(`Invoice ${item.invoice_id}: ${item.charge_description} - $${item.net_cost}`);
}

Key Fields

Field	Description
`id`	Unique identifier for the line item
`transaction_date`	Date the charge was incurred
`account_id`	Carrier account ID associated with the charge
`invoice_id`	Invoice ID from the carrier
`gross_cost`	Gross cost before discounts
`net_cost`	Net cost after discounts
`charge_description`	Description of the charge type

Filtering by Date

You can filter line items by transaction date to retrieve charges for a specific period:

curl -X GET "https://production.trackstarhq.com/carrier/invoice-line-items?transaction_date[gte]=2026-03-01T00:00:00Z&transaction_date[lte]=2026-03-31T23:59:59Z" \
  -H "x-trackstar-api-key: YOUR_API_KEY" \
  -H "x-trackstar-access-token: YOUR_ACCESS_TOKEN"

Option 2: Raw Invoice Files

Use the Get Files endpoint to download raw invoice documents. This returns presigned download URLs for each file.

curl -X GET https://production.trackstarhq.com/carrier/files \
  -H "x-trackstar-api-key: YOUR_API_KEY" \
  -H "x-trackstar-access-token: YOUR_ACCESS_TOKEN"

import requests

url = "https://production.trackstarhq.com/carrier/files"

headers = {
    "x-trackstar-api-key": "YOUR_API_KEY",
    "x-trackstar-access-token": "YOUR_ACCESS_TOKEN"
}

response = requests.get(url, headers=headers)
data = response.json()

for file in data["data"]:
    print(f"{file['file_name']} ({file['file_type']}) - expires: {file['download_url_expires_at']}")
    # Download the file using the presigned URL
    # file_response = requests.get(file["download_url"])

const url = "https://production.trackstarhq.com/carrier/files";

const response = await fetch(url, {
  headers: {
    "x-trackstar-api-key": "YOUR_API_KEY",
    "x-trackstar-access-token": "YOUR_ACCESS_TOKEN"
  }
});

const { data } = await response.json();

for (const file of data) {
  console.log(`${file.file_name} (${file.file_type}) - expires: ${file.download_url_expires_at}`);
  // Download the file using the presigned URL
  // const fileResponse = await fetch(file.download_url);
}

Key Fields

Field	Description
`id`	The file’s unique ID, used to fetch it from `/carrier/files/{id}`
`file_name`	Name of the file
`created_date`	When the file was generated
`file_type`	File extension (e.g. “csv”, “pdf”)
`download_url`	Presigned download URL
`download_url_expires_at`	When the download URL expires

Filtering by Date

Use created_date to query a specific date range:

curl -X GET "https://production.trackstarhq.com/carrier/files?created_date[gte]=2026-03-01T00:00:00Z&created_date[lte]=2026-03-31T23:59:59Z" \
  -H "x-trackstar-api-key: YOUR_API_KEY" \
  -H "x-trackstar-access-token: YOUR_ACCESS_TOKEN"

You can also filter by file_type (e.g. csv, pdf) and file_name.

start_time and end_time still work but are deprecated. They map to created_date[gte] and created_date[lte], so switch to created_date when you get the chance.

Download URLs expire after 20 minutes. If you need to access the file after expiration, make another request to get a fresh URL.

Getting One File by ID

The carrier-file.created webhook tells you a new file is ready, but it does not carry a download URL, because a presigned URL would expire before the webhook could be retried. Fetch the file by its id to get a fresh URL:

curl -X GET "https://production.trackstarhq.com/carrier/files/2026-03-01T00:00:00/8f2c1b9e/invoice.csv" \
  -H "x-trackstar-api-key: YOUR_API_KEY" \
  -H "x-trackstar-access-token: YOUR_ACCESS_TOKEN"

See Get Carrier File. This is also how you get a new URL for a file you already listed, without paging through the list endpoint again.

Which Approach to Use?

	Invoice Line Items	Files
Format	Structured JSON	Raw CSV/PDF
Best for	Programmatic analysis, cost tracking, dashboards	Archival, accounting systems that require original documents
Granularity	Individual charges	Full invoice documents

Home

How-To Guides

Use Cases

Carrier Invoice Data

Overview

Understanding invoice line items

Option 1: Invoice Line Items (JSON)

Key Fields

Filtering by Date

Option 2: Raw Invoice Files

Key Fields

Filtering by Date

Getting One File by ID

Which Approach to Use?

​Overview

​Understanding invoice line items

​Option 1: Invoice Line Items (JSON)

​Key Fields

​Filtering by Date

​Option 2: Raw Invoice Files

​Key Fields

​Filtering by Date

​Getting One File by ID

​Which Approach to Use?

Overview

Understanding invoice line items

Option 1: Invoice Line Items (JSON)

Key Fields

Filtering by Date

Option 2: Raw Invoice Files

Key Fields

Filtering by Date

Getting One File by ID

Which Approach to Use?