USPS - Trackstar

Overview

USPS delivers invoice data as EPS transaction detail reports, with one row per charge (label purchase, refund, scan form, etc.). Each row becomes one line item in the Trackstar API. Unlike UPS or FedEx, a row is not tied to one shipment: a single EPS transaction can cover many packages, and a package can appear in several transactions.

Files you’ll receive

Trackstar requests the EPS transaction detail report from the USPS reporting portal and serves it unchanged through the Files endpoint.

One CSV per date range. Each report covers up to 7 days. Its file name starts with TRANSACTIONDETAILS-{CRID}-{start date}-{end date}, with dates as YYYY-MM-DD, and its file_type is csv. A daily sync usually produces one report.
Reports overlap by a day. USPS reports cover whole days, and each daily report starts on the date the previous one ended. Charges from that shared day appear in both files. The two copies are identical except for ACH Withdrawal Amount (see below). Line items are not duplicated, because both copies produce the same line-item id. If you process the raw files yourself, de-duplicate on Package Identification Code (PIC) plus EPS Transaction ID.

Shape notes

One row per charge. A label purchase is one row; a later refund or adjustment on the same package is a separate row with its own EPS Transaction ID.
Rows don’t map 1:1 to shipments. One EPS transaction can cover many packages, so many rows can share an EPS Transaction ID. The same PIC can appear on several rows, one per transaction that charged it. Account-level rows have no PIC at all.
Transaction types vary. Common values include Label Purchase, Label Refund, SCAN Form Used, Carrier Pickup, and Shipping Services File. The Transaction Type column becomes the charge_description in the Trackstar-normalized output.
Dates are space-separated. Transaction Date/Time uses YYYY-MM-DD HH:MM:SS format.
Identifiers are wrapped in single quotes. USPS sends PIC, EFN, and customer reference numbers wrapped in single quotes, for example '9234690377819201924530'. Trackstar keeps the quotes as sent, so tracking_number and the line-item id include them. Strip them if you need the bare number.
ACH Withdrawal Amount is a report total. Every row carries the same value: the report’s total ACH withdrawal, not that row’s amount. Use Transaction Amount or Postage for the row’s own charge.
Tracking numbers are IMpb barcodes. The Package Identification Code (PIC) column holds the 20–22 digit USPS IMpb barcode (inside the quotes), which Trackstar maps to tracking_number.
Pass-through fields. Trackstar reads 6 columns (Package Identification Code (PIC), EPS Account #, EPS Transaction ID, Postage, Transaction Date/Time, Transaction Type). The remaining 15 columns pass through in the raw field.

Sample rows

The full CSV is shown here because USPS has only 21 columns. The downloadable CSV contains additional rows.

ACH Withdrawal ID,ACH Withdrawal Amount,EPS Account #,EPS Transaction ID,Transaction Amount,Transaction Date/Time,Transaction Type,EFN,Package Identification Code (PIC),Mail Class,Postage,CRID,Master MID,Permit Number,Permit Type,Permit Finance Number,Reason,Details,Cust Ref Num1,Cust Ref Num2,Dispute ID
600126146287812131,386.63,2684030563,6258250725712,23.72,2026-03-01 00:44:00,SCAN Form Used,'78040954577960076935','4335647197791615280044',Priority Mail,23.72,196946120,936725700,869390,PI,696447412,,,'ORD-000000',,
798745740698154416,386.63,2684030563,2930981279092,6.34,2026-03-01 07:45:00,Label Purchase,'31328393343983579206','2763541425546063107612',First-Class Package Service,6.34,196946120,936725700,869390,IMI,417176062,,,'ORD-000001',,
397285208437793537,386.63,2684030563,9448598755437,18.05,2026-03-01 14:58:00,SCAN Form Used,'46622006836046155654','6220271650671714456685',Parcel Select Ground,18.05,196946120,936725700,869390,OMAS,123073776,,,'ORD-000002',,
912361099971760982,386.63,2684030563,3616825412233,27.88,2026-03-01 21:00:00,Carrier Pickup,'81431220160867147962','0219491151180344381731',USPS Ground Advantage,27.88,196946120,936725700,869390,IMI,238232735,,,'ORD-000003',,
303971003922821593,386.63,2684030563,1107793877784,25.80,2026-03-02 04:09:00,Label Refund,'11765625298377889577','2296049909992957912190',USPS Ground Advantage,25.80,196946120,936725700,869390,PI,051456075,Customer Request,,'ORD-000004',,

Download

Download full sample CSV (1 header row + 25 data rows, 21 columns)

All sample data is synthetic. Tracking numbers, account numbers, addresses, and reference fields are fabricated and do not correspond to any real shipments or customers.

Fields

Column	Description	Example	Parsed
`ACH Withdrawal ID`	Bank withdrawal reference	`600126146287812131`
`ACH Withdrawal Amount`	The report’s total ACH withdrawal, repeated on every row	`386.63`
`EPS Account #`	Enterprise Payment System account; mapped to `account_id`	`2684030563`	✓
`EPS Transaction ID`	EPS transaction ID; mapped to `invoice_id`. Not unique per row: one transaction can cover many packages	`6258250725712`	✓
`Transaction Amount`	Total debited	`23.72`
`Transaction Date/Time`	`YYYY-MM-DD HH:MM:SS`; mapped to `transaction_date`	`2026-03-01 00:44:00`	✓
`Transaction Type`	Type of transaction; becomes `charge_description`	`Label Purchase`	✓
`EFN`	Electronic File Number, wrapped in single quotes	`'78040954577960076935'`
`Package Identification Code (PIC)`	USPS IMpb tracking number, wrapped in single quotes; mapped to `tracking_number` and part of the line-item `id`. Blank on account-level rows	`'4335647197791615280044'`	✓
`Mail Class`	Service class	`Priority Mail`
`Postage`	Postage amount; mapped to both `gross_cost` and `net_cost`	`23.72`	✓
`CRID`	Customer Registration ID	`196946120`
`Master MID`	Master Mailer ID	`936725700`
`Permit Number`	Permit imprint number	`869390`
`Permit Type`	Permit type (`IMI`, `OMAS`, `PI`)	`PI`
`Permit Finance Number`	Finance number on the permit	`696447412`
`Reason`	Reason (e.g. for refunds)	`Customer Request`
`Details`	Additional transaction details
`Cust Ref Num1` / `Cust Ref Num2`	Customer-supplied references, wrapped in single quotes	`'ORD-000000'`
`Dispute ID`	Dispute case reference

Columns marked ✓ are parsed into the Trackstar invoice_line_items schema; the rest are preserved in the raw field.

Mapping to invoice line items

Trackstar field	Source
`id`	`{Package Identification Code (PIC)}_{EPS Transaction ID}`, or `_{EPS Transaction ID}` when the row has no PIC. The same charge gets the same `id` when it appears in two overlapping reports
`tracking_number`	`Package Identification Code (PIC)`, quotes included
`invoice_id`	`EPS Transaction ID`
`account_id`	`EPS Account #`
`transaction_date`	`Transaction Date/Time`
`charge_description`	`Transaction Type`
`gross_cost` / `net_cost`	Both set to `Postage`
`raw`	The full row, as sent

​Overview

​Files you’ll receive

​Shape notes

​Sample rows

​Download

​Fields

​Mapping to invoice line items

Overview

Files you’ll receive

Shape notes

Sample rows

Download

Fields

Mapping to invoice line items