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

# Royal Mail

> Sample invoice line-item CSV for Royal Mail.

## Overview

Royal Mail is unique among the carriers: it provides invoice data and tracking data as **separate feeds**, so there is no single raw invoice file to download. Trackstar joins the two together and serves a combined line-item file. Each row is **one tracked item** (one barcode) with its share of the invoice charges.

Because the file is assembled by Trackstar, its columns use Trackstar's normalized naming — lowercase with underscores — rather than Royal Mail's report column names. The file has **16 columns** with a single header row.

## Shape notes

* **One row per tracked item.** A Royal Mail sales order can cover many items. The invoice charges for a sales order are divided evenly across the tracked items matched to it, so `gross_cost` and `net_cost` are per-item shares and can carry long decimals.
* **`source_type` marks direction.** `outbound` for items sent to a recipient; `rts` for items returned to sender. Returned items also populate `reason_for_non_delivery` and `date_return_to_sender`.
* **Two date formats.** `invoice_date` uses Royal Mail's `DD.MM.YYYY` format; `date_item_delivered` and `date_return_to_sender` use `YYYY-MM-DD`.
* **Tracking numbers are S10 barcodes.** Two letters, nine digits, and a `GB` suffix (e.g., `AB123456789GB`).
* **`charge_description` in the API.** In the [invoice line items](/api-reference/carrier-api/invoice-line-items/info) endpoint, each row's `charge_description` is built from `product_name` and `class_of_mail` (with ` RTS` appended for returns).

## Sample rows

Curated subset of columns for readability. The downloadable CSV has all 16 columns.

```csv theme={null}
account_number,invoice_number,invoice_date,sales_order_no,product_code,product_name,class_of_mail,tracking_number,gross_cost,net_cost,source_type
2684030563,1969461209,31.03.2026,4500000011,TSS,Tracked Small Signed,Tracked 24,RB715114139GB,22.82,19.02,outbound
2684030563,1969461209,31.03.2026,4500000012,TPS,Tracked Parcel Signed,Tracked 24,JW528145125GB,8.7675,7.3075,outbound
2684030563,1969461209,31.03.2026,4500000003,TRN,Tracked Returns,Tracked Returns 48,BJ338375127GB,33.07666666666667,27.563333333333333,rts
2684030563,1969461209,31.03.2026,4500000007,TRS,Tracked Returns Signed,Tracked Returns 24,AQ644428358GB,8.2725,6.895,rts
```

## Download

<a href="https://cdn.jsdelivr.net/gh/trackstarhq/documentation@main/assets/carrier-samples/royal-mail.csv" download>Download full sample CSV (1 header row + 25 data rows, 16 columns)</a>

<Note>
  All sample data is synthetic. Account numbers, invoice numbers, tracking numbers, and names are fabricated and do not correspond to any real shipments or customers.
</Note>

## Fields

Each row is one tracked item. All 16 columns appear in every row, in this order.

### Account and invoice

| # | Column | Description |
| :-: | :- | :- |
| 1 | `account_number` | Royal Mail account number — mapped to `account_id` |
| 2 | `account_name` | Account holder name |
| 3 | `invoice_number` | Royal Mail invoice number — mapped to `invoice_id` |
| 4 | `invoice_date` | Invoice date, `DD.MM.YYYY` — mapped to `transaction_date` |
| 5 | `sales_order_no` | Royal Mail sales order number; groups the items billed together |

### Product and item

| # | Column | Description |
| :-: | :- | :- |
| 6 | `product_code` | Tracked product code (`TPS`, `TPN`, `TSS`, `TSN`, `TRS`, `TRN`) |
| 7 | `product_name` | Human-readable product name |
| 8 | `class_of_mail` | Service class (e.g., `Tracked 24`, `Tracked 48`) |
| 9 | `volume` | Number of items in the sales order |
| 10 | `tracking_number` | Item barcode (S10 format, e.g., `AB123456789GB`) |

### Costs and delivery

| # | Column | Description |
| :-: | :- | :- |
| 11 | `gross_cost` | This item's share of the gross (VAT-inclusive) cost |
| 12 | `net_cost` | This item's share of the net (ex-VAT) cost |
| 13 | `source_type` | `outbound` or `rts` (return to sender) |
| 14 | `reason_for_non_delivery` | Reason the item was not delivered (returns only) |
| 15 | `date_return_to_sender` | Date the item was returned, `YYYY-MM-DD` (returns only) |
| 16 | `date_item_delivered` | Delivery date, `YYYY-MM-DD` (outbound only) |


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