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
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 |
