UPS - Trackstar

Overview

UPS invoices come from the UPS Billing Center as a CSV and a PDF per invoice. Each CSV row is a single charge: a shipment with a base freight charge, a fuel surcharge, and a tax becomes three rows that share the same Tracking Number and Invoice Number. The columns cover shipment identification, package details, charges, sender/receiver/third-party addresses, customs data (for international shipments), and freight-forwarding metadata.

Files you’ll receive

Trackstar archives both files for every invoice on the account and on any UPS billing plan the login can see. Each has its own entry in the Files API.

File	`file_name`	Format	Notes
Invoice CSV	`Invoice_<invoice number>_<MMDDYY>.csv`	Comma-delimited, UTF-8, `\n` line endings	UPS sends the CSV without a header row. Trackstar adds the 250 column names below as the first row; the values are not changed.
Invoice PDF	`Invoice_<invoice number>_<MMDDYY>.pdf`	PDF	The invoice as UPS prints it. UPS often publishes the PDF a day or more after the CSV, so it can show up in a later sync than its CSV.

UPS chooses the file name, which carries the invoice number and the invoice date. Plan invoices are named by plan number instead of invoice number. A plan number repeats every billing period, so the date is what tells two plan invoices apart. When UPS sends a download as a zip, Trackstar unpacks it and archives the CSV or PDF inside, so you never receive a zip.

Shape notes

250 names, 270 values on account invoices. Account invoice CSVs downloaded since August 31, 2026 have 270 values per row, whatever the invoice date; ones downloaded earlier have 250. UPS does not publish names for the last 20, so the header row Trackstar adds still has 250 names and each data row has 20 more values than the header. So far those 20 columns have always been empty. Plan invoice CSVs are still 250 values wide. If you read the file with a header-keyed CSV reader, expect the extra values to land under an unnamed key.
Multi-row shipments. Expect 2–5 rows per Tracking Number, one per charge type.
Net vs. gross. Net Amount is what the customer paid for the charge. Incentive Amount is the discount; Net Amount + Incentive Amount = gross charge before discount.
Charge types are coded. The Charge Classification Code column contains a 3-letter code (FRT, FSC, ACC, TAX, etc.). Trackstar maps these to the descriptions listed under Mapping to invoice line items.
Two date formats. Transaction Date is usually YYYY-MM-DD, but some US charge rows use MM/DD/YYYY. Trackstar converts both to ISO 8601 in transaction_date.
Account-level charges have no transaction date. Miscellaneous charges billed to the account rather than to a shipment leave Transaction Date blank. Trackstar uses Invoice Date for those rows.
International columns. The majority of columns (Customs Number, Duty Amount, VAT Amount, etc.) are only populated for international shipments. Most domestic US rows leave them empty.
Place Holder columns. Place Holder 46–48 and Place Holder 50–59 are empty columns reserved by UPS. There is no Place Holder 49; that position holds SCC Scale Weight.

Sample rows

Curated subset showing the most shape-informative columns. The downloadable CSV below has every column.

Account Number,Invoice Number,Transaction Date,Tracking Number,Lead Shipment Number,Zone,Charge Classification Code,Charge Description,Basis Value,Incentive Amount,Net Amount
KX2RDL,000000KX2RDL136,2026-03-24,1Z8CZ3C80496442033,1ZGIB8MW7257008693,3,FRT,Transportation Charges,40.21,3.30,36.91
KX2RDL,000000KX2RDL136,2026-03-24,1Z8CZ3C80496442033,1ZGIB8MW7257008693,3,FSC,Fuel Surcharges,13.92,1.31,12.61
KX2RDL,000000KX2RDL136,2026-03-03,1ZH6ZTPU9908473687,1Z446QNL9666456748,4,FRT,Transportation Charges,64.20,1.75,62.45
KX2RDL,000000KX2RDL136,2026-03-03,1ZH6ZTPU9908473687,1Z446QNL9666456748,4,TAX,Taxes,11.38,0.95,10.43
KX2RDL,000000KX2RDL136,2026-03-08,1Z0860QU7406981544,1ZP1I0Y86447412718,8,FRT,Transportation Charges,85.12,3.85,81.27

Download

Download full sample CSV (25 rows, 250-name header, 270 values per row) The sample is shaped like an account invoice: a 250-name header row with 270 values in every data row. Two rows use the MM/DD/YYYY transaction date format.

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.

Mapping to invoice line items

Each CSV row becomes one invoice line item.

Trackstar field	Source	Notes
`id`	`Lead Shipment Number`	Rows that share a lead shipment number get a `-1`, `-2`, … suffix in the order they appear. A row with no lead shipment number gets a generated ID.
`tracking_number`	`Tracking Number`
`invoice_id`	`Invoice Number`
`account_id`	`Account Number`
`transaction_date`	`Transaction Date`	Falls back to `Invoice Date` when blank. `MM/DD/YYYY` values are converted, and the time is set to midnight UTC.
`charge_description`	`Charge Classification Code`	Mapped from the code, not taken from the `Charge Description` column: `FRT` Transportation Charges, `FSC` Fuel Surcharges, `ACC` Accessorial Charges, `TAX` Taxes, `GOV` Government Charges, `BRK` Brokerage Charges, `EXM` Exemptions, `MSC` Miscellaneous Charges, `INF` Informational. A blank code gives `Data Unavailable`; any other code gives `Unknown Charge Type`.
`net_cost`	`Net Amount`
`gross_cost`	`Net Amount` + `Incentive Amount`	`Basis Value` is not used.
`raw`	The full row	Keyed by the 250 column names. The 20 unnamed trailing values are left out.

Fields

UPS columns are grouped below by functional family, not in file order. The header row of the downloadable CSV has all 250 names in the order they appear in the file.

Invoice identification

Column	Description	Example
`Version`	UPS CSV schema version	`6.1`
`Recipient Number`	Account number of the invoice recipient	`KX2RDL`
`Account Number`	Billing account number	`KX2RDL`
`Account Country`	ISO country code of the billing account	`US`
`Invoice Date`	Date the invoice was issued	`2026-03-31`
`Invoice Number`	Unique invoice identifier	`000000KX2RDL136`
`Invoice Type Code`	Invoice type (`01` = standard)	`01`
`Invoice Type Detail Code`	Subtype of the invoice	`01`
`Account Tax ID`	Tax ID associated with the account	(populated for EU/non-US accounts)
`Invoice Currency Code`	ISO 4217 currency of this invoice	`USD`
`Invoice Amount`	Total invoice amount in `Invoice Currency Code`, repeated on every row of the invoice	`941.36`
`Invoice Due Date`	When payment is due	`2026-04-30`
`Alternate Invoicing Currency Code`	Secondary currency (if dual-currency billing)	`EUR`
`Alternate Invoice Amount`	Total in the alternate currency	`167.20`
`Invoice Exchange Rate`	Rate used to convert to `Alternate Invoicing Currency Code`	`0.915`
`Alternate Invoice Number`	Secondary invoice reference
`Tax Variance Amount`	Tax adjustment
`Currency Variance Amount`	Currency conversion adjustment
`Invoice Level Charge`	Flag: is this an invoice-level (not shipment-level) charge	`Y` / `N`

Shipment and package

Column	Description	Example
`Transaction Date`	Date the charge was incurred (usually ship date). Usually `YYYY-MM-DD`, sometimes `MM/DD/YYYY`; blank on account-level charges	`2026-03-24`
`Pickup Record Number`	UPS pickup manifest number	`8834217511`
`Lead Shipment Number`	Primary shipment identifier; used as the line-item `id`	`1ZGIB8MW7257008693`
`World Ease Number`	UPS World Ease consolidation identifier
`Shipment Reference Number 1` / `2`	Customer-supplied shipment refs	`ORDER-12345`
`Bill Option Code`	`PP` (prepaid), `FC` (freight collect), `TP` (third party), etc.	`PP`
`Package Quantity`	Number of packages on this shipment	`1`
`Oversize Quantity`	How many of those packages were oversize	`0`
`Tracking Number`	UPS 1Z tracking number for the package	`1Z8CZ3C80496442033`
`Package Reference Number 1`–`5`	Customer-supplied package-level refs
`Entered Weight`	Actual weight at ship time	`8.4`
`Entered Weight Unit of Measure`	`LB` or `KG`	`LB`
`Billed Weight`	Weight UPS billed (may be dimensional weight)	`12.0`
`Billed Weight Unit of Measure`	Unit for billed weight	`LB`
`Container Type`	Container code (LTR, PKG, PAK, etc.)	`PKG`
`Billed Weight Type`	`A` = actual, `D` = dim	`D`
`Package Dimensions`	`LxWxH` formatted string	`12x9x6`
`Package Dimension Unit Of Measure`	`IN` or `CM`	`IN`
`Raw dimension length`	Raw dim length	`12`
`Raw dimension unit of measure`	Unit for raw dim	`IN`
`Detail Keyed Dim`	Keyed-in dimensions
`Detail Keyed Unit of Measure`	Unit for keyed dims
`Detail Keyed Billed Dimension`	Billed keyed dim
`Detail Keyed Billed Unit of Measure`	Unit for keyed billed dim
`Scale weight quantity`	Weight per scale reading
`Scale Weight Unit of Measure`	Unit for scale weight
`SCC Scale Weight`	Scale weight (SCC context)
`Zone`	UPS zone (1–8) indicating shipping distance	`4`
`Corrected Zone`	Zone after address correction, if any
`Original Shipment Package Quantity`	Original piece count before correction
`Original tracking number`	Prior tracking number if shipment was re-labeled
`Original Service Description`	Text of the shipping service	`UPS Ground`
`Shipment Value Amount`	Declared value	`250.00`
`Shipment Description`	Text description of shipment contents

Charges

Column	Description	Example
`Charge Category Code`	High-level charge bucket	`T` (transportation)
`Charge Category Detail Code`	Subcategory
`Charge Source`	Origin of the charge	`S` (shipment)
`Type Code 1` / `Type Code 2`	Internal UPS charge type codes
`Type Detail Code 1` / `2`	Subcodes
`Type Detail Value 1` / `2`	Values paired with the type codes
`Charge Classification Code`	Primary charge type. `FRT`, `FSC`, `ACC`, `TAX`, `GOV`, `BRK`, `EXM`, `MSC`, `INF`; becomes `charge_description`	`FRT`
`Charge Description Code`	Human-readable code for the charge	`FRT`
`Charge Description`	Display text for the charge	`Transportation Charges`
`Charged Unit Quantity`	Number of units the charge applies to	`1`
`Basis Currency Code`	Currency the charge was computed in	`USD`
`Basis Value`	Gross amount before discount	`40.21`
`Tax Indicator`	`Y` if this charge is a tax	`N`
`Transaction Currency Code`	Currency the charge was billed in	`USD`
`Incentive Amount`	Discount applied	`3.30`
`Net Amount`	Final charged amount (`Basis Value` − `Incentive Amount`)	`36.91`
`Miscellaneous Currency Code`	Currency for any misc charge
`Miscellaneous Incentive Amount`	Misc discount
`Miscellaneous Net Amount`	Misc net
`Tax Law Article Number`	Reference to applicable tax law
`Tax Law Article Basis Amount`	Basis amount per tax law

Addresses

UPS ships four address blocks per row (Sender, Receiver, Third Party, Sold To) plus two optional “Miscellaneous Address” blocks. Each block has the same 8 columns.

Column	Description	Example
`Sender Name` / `Receiver Name` / `Third Party Name` / `Sold To Name`	Contact name	`Jane Smith`
`{Block} Company Name`	Company name	`Acme Corp`
`{Block} Address Line 1` / `Address Line 2`	Street address	`123 Main St`
`{Block} City`	City	`Atlanta`
`{Block} State`	State or region	`GA`
`{Block} Postal`	Postal/ZIP code	`30309`
`{Block} Country`	ISO country code	`US`
`Miscellaneous Address Qual 1` / `2`	Qualifier describing what the misc address represents	`BROKER`
`Miscellaneous Address 1 Name`–`Country`	Full 8-col address block for misc 1
`Miscellaneous Address 2 Name`–`Country`	Full 8-col address block for misc 2

Shipment lifecycle dates

Column	Description
`Shipment Date`	When the shipment was tendered to UPS
`Shipment Export Date`	Date exported from origin country
`Shipment Import Date`	Date imported into destination country
`Entry Date`	Customs entry date
`Direct Shipment Date`	Direct-ship date
`Shipment Delivery Date`	When the shipment was delivered
`Shipment Release Date`	Customs release date
`Cycle Date`	UPS billing cycle date
`EFT Date`	Electronic funds transfer date
`Validation Date`	Invoice validation date

Customs and international freight

Most of these columns are empty for domestic US shipments.

Column	Description
`Entry Port`	Port code where shipment entered
`Entry Number`	Customs entry number
`Export Place`	Place of export
`Entered Currency Code`	Declared currency
`Customs Number`	Customs reference
`Exchange Rate`	FX rate applied
`Master Air Waybill Number`	Master AWB for air freight
`EPU`	Entry Processing Unit code
`Entry Type`	Type of customs entry
`CPC Code`	Customs Procedure Code
`Line Item Number`	Commercial invoice line number
`Goods Description`	Description of goods
`Entered Value`	Declared value
`Duty Amount`	Duties owed
`Weight`	Customs weight
`Unit of Measure`	Weight unit
`Item Quantity` / `Item Quantity Unit of Measure`	Units and their UoM
`Import Tax ID`	Importer tax ID
`Declaration Number`	Customs declaration number
`Carrier Name/Clinical Trial Identification Number/SDS ID`	Multi-use identifier
`CCCD Number`	Country-specific customs doc number
`Cycle Number`	Billing cycle number
`Foreign Trade Reference Number`	FTR number
`Job Number`	Internal UPS job number
`Transport Mode`	Air, ground, ocean
`Tax Type` / `Tariff Code` / `Tariff Rate` / `Tariff Treatment Number`	Tariff fields
`Contact Name` / `Class Number`
`Document Type` / `Document Number` / `Office Number`	Customs docs
`Duty Value` / `Duty Rate`
`Total Value for Duty`
`Excise Tax Amount` / `Excise Tax Rate`
`GST Amount` / `GST Rate`	Canadian GST
`VAT Basis Amount` / `VAT Amount` / `VAT Rate`	EU VAT
`Other Basis Amount` / `Other Amount` / `Other Rate`	Other tax fields
`Other Customs Number Indicator` / `Other Customs Number`
`Customs Office Name`	Name of the processing customs office
`Order In Council` / `SIMA Access` / `Tax Value`	Canadian customs fields
`Total Customs Amount`	Sum of all customs charges
`Origin Country`	Country of origin

Freight and reference numbers

Column	Description
`BOL # 1`–`BOL # 5`	Bill of Lading numbers
`PO # 1`–`PO # 10`	Purchase order numbers
`NMFC`	National Motor Freight Classification code
`Detail Class`	Freight class
`Freight Sequence Number`	Sequence within a freight shipment
`Declared Freight Class`	Customer-declared freight class
`EORI Number`	EU Economic Operator Registration number
`Customer Reference Number`	Customer-supplied invoice reference
`Store Number`	Retail store number

Miscellaneous and placeholder

Column	Description
`Miscellaneous Line 1`–`5`, `7`–`11`	Unclassified misc fields
`Payor Role Code`	Role of the paying party (`SHP`, `CON`, `TP`)
`Promo Discount Applied Indicator`	Flag for promo discounts
`Promo Discount Alias`	Promo code
`SDS Match Level Cd` / `SDS RDR Date` / `SDS Delivery Date` / `SDS Error Code`	Surepost Delivery Service fields
`Place Holder 46`–`48`, `Place Holder 50`–`59`	Reserved empty columns
`SCC Scale Weight`	Sits between `Place Holder 48` and `Place Holder 50` (also listed under Shipment and package)

On account invoices, 20 unnamed values follow Place Holder 59 on every row. See Shape notes.

​Overview

​Files you’ll receive

​Shape notes

​Sample rows

​Download

​Mapping to invoice line items

​Fields

​Invoice identification

​Shipment and package

​Charges

​Addresses

​Shipment lifecycle dates

​Customs and international freight

​Freight and reference numbers

​Miscellaneous and placeholder

Overview

Files you’ll receive

Shape notes

Sample rows

Download

Mapping to invoice line items

Fields

Invoice identification

Shipment and package

Charges

Addresses

Shipment lifecycle dates

Customs and international freight

Freight and reference numbers

Miscellaneous and placeholder