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 |
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"
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"
Key Fields
| Field | Description |
|---|
file_name | Name of the file |
generated_time | 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
By default, the files endpoint returns files from the last 24 hours. Use start_time and end_time to query a specific date range:
curl -X GET "https://production.trackstarhq.com/carrier/files?start_time=2026-03-01T00:00:00Z&end_time=2026-03-31T23:59:59Z" \
-H "x-trackstar-api-key: YOUR_API_KEY" \
-H "x-trackstar-access-token: YOUR_ACCESS_TOKEN"
file_type (e.g. csv, pdf) and file_name.
Download URLs expire after 20 minutes. If you need to access the file after expiration, make another request to get a fresh URL.
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 |
