> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trackstarhq.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Trackstar is a unified REST API for WMS, cart, and carrier systems. Base URL: https://production.trackstarhq.com. There is no SDK; call the API with plain HTTP.
> Send x-trackstar-api-key on every request. Endpoints scoped to one connection also need x-trackstar-access-token. Read both from environment variables and never print them.
> Reads return data Trackstar has already synced from the connected system. Writes (POST, PUT, PATCH, DELETE) are forwarded to the connected system immediately.
> A new connection has no data until its initial sync finishes. Wait for the connection.historical-sync-completed webhook, or poll GET /connections/{connection_id} and check historical_sync_completed.
> List endpoints page with page_token and next_token (limit is capped at 1000). Repeat every filter on every page. Filters use field[operator]=value, for example created_date[gte]=2026-01-01T00:00:00Z.
> Write bodies must not contain null or empty strings; omit the field instead. Call GET /integrations/{integration_type}/{integration_name}/write-info first to learn the exact fields an integration accepts.
> To test without real credentials, POST /sandbox/generate-sandbox/{wms|cart|carrier} with the API key returns a sandbox access token. Start at https://docs.trackstarhq.com/how-to-guides/build-with-ai.md and install the skills with: npx skills add https://docs.trackstarhq.com

# Carrier Invoice Data

> Retrieve carrier invoice line items and download raw invoice files using the Carrier API

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:

1. **Invoice Line Items** — parsed, structured JSON data for each individual charge
2. **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](/api-reference/carrier-api/files/info). See [Carrier Sample Files](/api-reference/carrier-api/sample-files/overview) for exact shapes per integration.

## Option 1: Invoice Line Items (JSON)

Use the [Get Invoice Line Items endpoint](/api-reference/carrier-api/invoice-line-items/get) to retrieve parsed invoice charges. Each line item contains cost details, transaction dates, and charge descriptions.

<CodeGroup>
  ```bash cURL theme={null}
  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"
  ```

  ```python Python theme={null}
  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']}")
  ```

  ```javascript JavaScript theme={null}
  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}`);
  }
  ```
</CodeGroup>

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

```bash theme={null}
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](/api-reference/carrier-api/files/get) to download raw invoice documents. This returns presigned download URLs for each file.

<CodeGroup>
  ```bash cURL theme={null}
  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"
  ```

  ```python Python theme={null}
  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"])
  ```

  ```javascript JavaScript theme={null}
  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);
  }
  ```
</CodeGroup>

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

```bash theme={null}
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`.

<Note>
  `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.
</Note>

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

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

```bash theme={null}
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](/api-reference/carrier-api/files/get-item). 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 |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.