### Fields (international format)
| Column | Description | Example |
| :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------- | :----------------------------- |
| `Billing Country/Territory` | ISO country code of the billing account | `GB` / `NL` |
| `Invoice Type` | Invoice kind | `Shipment` / `Credit Memo` |
| `Settlement Type` | Payment settlement | `Regular` |
| `Bill to Account Number` | Billing account — mapped to `account_id` | `196946120` |
| `Government Number` | Government-required identifier | |
| `FedEx Invoice Number` | Invoice ID — mapped to `invoice_id` | `2684030563` |
| `Invoice Date` | `DD-MMM-YYYY` — mapped to `transaction_date` | `31-Mar-2026` |
| `Due Date` | Payment due date | `14-Apr-2026` |
| `Bill to Currency` | Invoice currency | `GBP` / `EUR` |
| `Total Standard Charges` | Total before surcharges/discounts | `57.34` |
| `Total Discounts` / `Total Surcharges` / `Total Taxes` | Invoice-level totals | |
| `Original Amount Due` | Invoice grand total (used for reconciliation) | `1247.19` |
| `Alternate Currency` / `Alternate Currency Exchange Rate` | Secondary currency fields | |
| `Air Waybill Number` | Tracking number — mapped to `tracking_number` | `936725700869` |
| `Bill To` | Who pays | `Shipper` |
| `Shipper Reference 1` / `2` / `3` | Shipper-supplied references | |
| `POD Date` / `POD Time` / `POD Name` | Proof-of-delivery fields | |
| `Ship Date (formatted)` / `Ship Date` / `Tendered Date` | Shipment lifecycle dates | |
| `Service` | Service name | `FedEx International Priority` |
| `Packaging` / `SvcPkg Label` | Packaging type | |
| `Origin Station` / `Destination Station` | FedEx station codes | |
| `Pieces` | Piece count | `1` |
| `Actual Weight` / `Actual Weight Units` | Actual weight | `2.5` / `KG` |
| `Meter Number` | FedEx meter number | |
| `Child Account Number` | Sub-account | |
| `Master Air Waybill Number` | MAWB for air freight | |
| `Sender Company Name` / `Sender Contact Name` / `Sender Address Line 1` / `Line 2` / `Line 3` / `Address City` / `Address State` / `Address Postal` / `Address Country/Territory` | Sender address | |
| `Recipient Company Name` / `Recipient Contact Name` / `Recipient Address Line 1` / `Line 2` / `Line 3` / `Address City` / `Address State` / `Address Postal` / `Address Country/Territory` | Recipient address | |
| `MPS Package Tracking ID` | MPS package tracking ID | |
| `Dim Length` / `Dim Width` / `Dim Height` / `Dim Divisor` / `Dim Unit` | Dimensional fields | |
| `Rated Weight Amount` / `Rated Weight Units` | Billed weight | |
| `Zone Code` | Shipping zone (2–6) | `3` |
| `Air Waybill Total Amount` | Row total (sum of charges in pair columns) | `57.34` |
| `Air Waybill Charge Label` × 51 | Charge label for each pair slot | `Fuel Surcharge` |
| `Air Waybill Charge Amount` × 51 | Charge amount for each pair slot | `3.21` |
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.
# Sample Files Overview
Source: https://docs.trackstarhq.com/api-reference/carrier-api/sample-files/overview
Per-integration reference for the invoice CSV format each carrier delivers, with downloadable synthetic samples.
Each carrier delivers invoice data in its own CSV format. The pages in this group document those formats individually — what columns appear, what each column means, how multi-row shipments are structured, and where line-item charges live. Each integration has a downloadable synthetic CSV you can parse against without needing a live integration.
Most of these files are the **raw carrier file** served as-is, so they keep each carrier's own column names and casing. Royal Mail is the exception: its invoice and tracking data arrive separately, so Trackstar combines them into a single line-item file with normalized column names.
All sample data on these pages is **synthetic**. Tracking numbers, account numbers, addresses, and reference fields are fabricated and do not correspond to any real shipments or customers.
## Integrations
| Integration | Regional variants | Delimiter | Column count | Charge structure |
| :----------------------------------------------------------------- | :-------------------------------------- | :-------- | :----------------------------- | :-------------------------------------------------------------------------------------------------------- |
| [DHL eCommerce](/api-reference/carrier-api/sample-files/dhl-ecom) | — | `,` | 79 (no header row) | One row per shipment; charges spread across named columns (`Charge*`, `ZFuel*`, `ZSC*`, `ZRM*`) |
| [DHL Express](/api-reference/carrier-api/sample-files/dhl-express) | — | `,` | 153 | `Line Type` marker (`I` / `S`); charges in `XC1`–`XC9` column groups |
| [DPD](/api-reference/carrier-api/sample-files/dpd) | English (Dutch column aliases accepted) | `;` | 43 | One row per shipment; charges in named columns (`Base price`, `Energy surcharge`, `Fuel surcharge`, etc.) |
| [FedEx](/api-reference/carrier-api/sample-files/fedex) | US, International (UK / NL) | `,` | 210 (US) / 168 (International) | One row per shipment; charges in repeating `Label` / `Amount` column pairs |
| [Royal Mail](/api-reference/carrier-api/sample-files/royal-mail) | — | `,` | 16 | Trackstar-combined line-item file (not a raw carrier file); one row per tracked item |
| [UPS](/api-reference/carrier-api/sample-files/ups) | — | `,` | 250 | One row per **charge**; multiple rows per shipment share a tracking number |
| [USPS](/api-reference/carrier-api/sample-files/usps) | — | `,` | 21 | One row per transaction (1:1 with line items) |
## How to use these samples
* **Prototype your integration** without needing a live carrier connection. Download the CSV, run it through your own ingestion code, and compare against the schema documented on each page.
* **Understand the Trackstar `invoice_line_items` schema in context.** Each page lists which raw columns Trackstar maps to which normalized field (`tracking_number`, `invoice_id`, `charge_description`, `gross_cost`, `net_cost`, etc.).
* **Test your downstream systems** against realistic-shaped data, including multi-row shipments, multi-currency invoices, and empty optional columns.
For the normalized API that sits over all these formats, see [Invoice Line Items](/api-reference/carrier-api/invoice-line-items/info). For the raw-file endpoint that returns presigned URLs to a customer's actual (non-synthetic) files, see [Files](/api-reference/carrier-api/files/info).
# Royal Mail
Source: https://docs.trackstarhq.com/api-reference/carrier-api/sample-files/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
Download full sample CSV (1 header row + 25 data rows, 16 columns)
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.
## 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) |
# UPS
Source: https://docs.trackstarhq.com/api-reference/carrier-api/sample-files/ups
Sample invoice CSV for UPS, with the complete 250-column field dictionary.
## Overview
UPS delivers one CSV per billing period. Each 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 CSV has 250 columns covering shipment identification, package details, charges, sender/receiver/third-party addresses, customs data (for international shipments), and freight-forwarding metadata.
## Shape notes
* **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 human-readable charge descriptions in the normalized `charge_description` field.
* **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 (46–59).** Empty columns reserved by UPS for future use.
## Sample rows
Curated subset showing the most shape-informative columns. The downloadable CSV below has all 250 columns.
```csv theme={null}
Account Number,Invoice Number,Transaction Date,Tracking Number,Lead Shipment Number,Zone,Charge Classification Code,Charge Description,Basis Value,Incentive Amount,Net Amount
KX2RDL,ULN-0563196946,2026-03-24,1Z8CZ3C80496442033,1ZGIB8MW7257008693,3,FRT,Transportation Charges,40.21,3.30,36.91
KX2RDL,ULN-0563196946,2026-03-24,1Z8CZ3C80496442033,1ZGIB8MW7257008693,3,FSC,Fuel Surcharges,13.92,1.31,12.61
KX2RDL,ULN-0563196946,2026-03-03,1ZH6ZTPU9908473687,1Z446QNL9666456748,4,FRT,Transportation Charges,64.20,1.75,62.45
KX2RDL,ULN-0563196946,2026-03-03,1ZH6ZTPU9908473687,1Z446QNL9666456748,4,TAX,Taxes,11.38,0.95,10.43
KX2RDL,ULN-0563196946,2026-03-08,1Z0860QU7406981544,1ZP1I0Y86447412718,8,FRT,Transportation Charges,85.12,3.85,81.27
```
## Download
Download full sample CSV (25 rows, 250 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
UPS columns are grouped below by functional family. All 250 columns are delivered in every invoice in the order shown.
### 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 | `ULN-0563196946` |
| `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` | `182.77` |
| `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) | `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` | `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`–`59` | Reserved empty columns |
# USPS
Source: https://docs.trackstarhq.com/api-reference/carrier-api/sample-files/usps
Sample invoice CSV for USPS, pulled from the Enterprise Payment System (EPS) transaction report.
## Overview
USPS delivers invoice data as EPS transaction reports — one row per postage transaction. Each row represents a single charge (label purchase, refund, scan form, etc.), so shipments and line items are 1:1 in this CSV (unlike UPS or FedEx, which have multi-row shipments).
## Shape notes
* **One row per transaction.** Unlike other carriers where a single shipment produces multiple rows, USPS EPS emits one row per event — a label purchase is one row, a subsequent refund is a separate row with a negative `Transaction Amount`.
* **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.
* **Tracking numbers are IMpb barcodes.** The `Package Identification Code (PIC)` column holds the 20–22 digit USPS IMpb barcode, which Trackstar maps to `tracking_number`.
* **Pass-through fields.** Trackstar uses only 5 columns (`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.
```csv theme={null}
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,23.54,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,6.70,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,17.73,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,26.20,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,28.12,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 (25 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` | Amount withdrawn via ACH | `23.54` | |
| `EPS Account #` | Enterprise Payment System account — mapped to `account_id` | `2684030563` | ✓ |
| `EPS Transaction ID` | Unique transaction ID — mapped to `invoice_id` | `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 | `78040954577960076935` | |
| `Package Identification Code (PIC)` | USPS IMpb tracking number — mapped to `tracking_number` and the line-item `id` | `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 | `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.
# Update Cart Order Trackstar Tags
Source: https://docs.trackstarhq.com/api-reference/cart-api/orders/add-tag
put /cart/orders/{order_id}/trackstar-tags
Update the trackstar tags for the specified cart order.
# Create Cart Order Shipment
Source: https://docs.trackstarhq.com/api-reference/cart-api/orders/create-shipment
post /cart/orders/{order_id}/shipments
Get the required, optional, and integration specific fields by calling the [integrations](/api-reference/mgmt/integrations) endpoint.
# Get All Cart Orders
Source: https://docs.trackstarhq.com/api-reference/cart-api/orders/get
get /cart/orders
Returns all Orders for the Cart connection associated with the provided access token.
# Get Cart Order
Source: https://docs.trackstarhq.com/api-reference/cart-api/orders/get-item
get /cart/orders/{order_id}
Returns a single Order for the Cart connection with the associated order ID.
# Cart Orders
Source: https://docs.trackstarhq.com/api-reference/cart-api/orders/info
An order is a purchase made by a customer. It contains information about the order,
including the individual line items. Each line item contains a `product_id` that
can be passed to the [`/cart-api/products/{product_id}`](/api-reference/cart-api/products/get-item) for more details.
The line item may also include the item's `sku`, the parent product's ID, and the parent product's `sku`.
### Order Statuses (in order of lifecycle)
| Status | Definition |
| :-------------------- | :-------------------------------------------------------------------------------------------------------------------------------- |
| `open` | Order has been placed. |
| `confirmed` | Order has been confirmed by the cart system. |
| `processing` | Order is being processed by the warehouse. |
| `partially_fulfilled` | Order has been partially fulfilled. |
| `fulfilled` | Order has been fulfilled and shipped. |
| `backordered` | Order cannot be fulfilled because of a lack of available inventory. |
| `exception` | There is an issue with the order. |
| `cancelled` | Order has been cancelled by either the platform, warehouse, or customer. |
| `other` | Status of the order can't be determined. Often due to a custom status being used. See the `raw_status` field for more information |
# Refund Cart Order
Source: https://docs.trackstarhq.com/api-reference/cart-api/orders/refund
post /cart/orders/{order_id}/refund
Refunds an order with the specified line items and amount.
# Update Cart Product Trackstar Tags
Source: https://docs.trackstarhq.com/api-reference/cart-api/products/add-tag
put /cart/products/{product_id}/trackstar-tags
Update the trackstar tags for the specified cart product.
# Adjust Inventory for Product
Source: https://docs.trackstarhq.com/api-reference/cart-api/products/adjust
put /cart/products/{product_id}/adjust-inventory
Adjust the inventory for the specified cart product.
# Batch Adjust Inventory for Cart Products
Source: https://docs.trackstarhq.com/api-reference/cart-api/products/batch-adjust
put /cart/products/batch-adjust-inventory
Set the exact on-hand inventory for multiple cart products in a single call.
Each line specifies a product and the exact quantity to set; increase and
decrease adjustments are not supported here.
# Get All Cart Products
Source: https://docs.trackstarhq.com/api-reference/cart-api/products/get
get /cart/products
Returns all Products for the Cart connection associated with the provided access token.
# Get Cart Product
Source: https://docs.trackstarhq.com/api-reference/cart-api/products/get-item
get /cart/products/{product_id}
Returns a single Product for the Cart connection with the associated product ID.
# Products
Source: https://docs.trackstarhq.com/api-reference/cart-api/products/info
A product is an item's listing on the cart platform. It contains information about the product, such as its name and `sku`.
Every variant and parent product are listed in this endpoint. A variant will contain information like the price and inventory
levels reflected by the platform. It will also have its parent product's ID.
Parent products are indicated by having their `parent_product_id` set to the same value as their `id`.
They may or may not have information about their price or inventory levels, but the source of truth for this information
will be in their associated variants.
# Update Cart Warehouse Trackstar Tags
Source: https://docs.trackstarhq.com/api-reference/cart-api/warehouses/add-tag
put /cart/warehouses/{warehouse_id}/trackstar-tags
Update the trackstar tags for the specified cart warehouse.
# Get All Cart Warehouses
Source: https://docs.trackstarhq.com/api-reference/cart-api/warehouses/get
get /cart/warehouses
Returns all Warehouses for the Cart connection associated with the provided access token.
# Get Cart Warehouse
Source: https://docs.trackstarhq.com/api-reference/cart-api/warehouses/get-item
get /cart/warehouses/{warehouse_id}
Returns a single Warehouse for the Cart connection with the associated warehouse ID.
# Warehouses
Source: https://docs.trackstarhq.com/api-reference/cart-api/warehouses/info
A warehouse is a physical location where inventory is stored. It contains information about the warehouse, such as its name and (if applicable) code.
# Create Link Token
Source: https://docs.trackstarhq.com/api-reference/mgmt/create-link-token
post /link/token
Creates a temporary link token that is required to initiate the `react-trackstar-link` component.
See the [Getting Started guide](/how-to-guides/getting-started) for more details.
# Create Magic Link
Source: https://docs.trackstarhq.com/api-reference/mgmt/create-magic-link
post /magic-links
Create a Magic Link to allow users to connect their integrations via a temporary link.
# Delete Connection
Source: https://docs.trackstarhq.com/api-reference/mgmt/delete-connection
delete /connections
Deletes the connection associated with your access token.
# Delete Magic Link
Source: https://docs.trackstarhq.com/api-reference/mgmt/delete-magic-link
delete /magic-links/{magic_link_id}
Delete a Magic Link by its ID.
# Exchange Auth Code
Source: https://docs.trackstarhq.com/api-reference/mgmt/exchange-auth-code
post /link/exchange
Exchanges a temporary authorization code for a permanent access token.
See the [Getting Started guide](/how-to-guides/getting-started) for more details.
# Get Connection
Source: https://docs.trackstarhq.com/api-reference/mgmt/get-connection
get /connections/{connection_id}
Returns the specified connection.
# Get Connections
Source: https://docs.trackstarhq.com/api-reference/mgmt/get-connections
get /connections
Returns connected integrations for your organization.
# Integration Info for Single Integration
Source: https://docs.trackstarhq.com/api-reference/mgmt/get-integration
get /integrations/{integration_type}/{integration_name}
Information about the data provided by a single integration.
# Get Magic Link
Source: https://docs.trackstarhq.com/api-reference/mgmt/get-magic-link
get /magic-links/{magic_link_id}
Get a Magic Link by its ID.
# Get Magic Links
Source: https://docs.trackstarhq.com/api-reference/mgmt/get-magic-links
get /magic-links
Get a list of all Magic Links for your organization.
# Integration Write Info
Source: https://docs.trackstarhq.com/api-reference/mgmt/integration-write-info
get /integrations/{integration_type}/{integration_name}/write-info
The spec for all the write operations supported by an integration,
in [OpenAPI 3.1.0](https://swagger.io/specification/) format.
Also provides the connection-specific fields for an integration if you pass in the access token.
# Integration Info
Source: https://docs.trackstarhq.com/api-reference/mgmt/integrations
get /integrations/{integration_type}
Information about the data provided by each integration.
# Sync Connection
Source: https://docs.trackstarhq.com/api-reference/mgmt/sync-connection
post /connections/sync
Manually trigger a sync for the connection associated with your access token.
# Toggle All Schedules
Source: https://docs.trackstarhq.com/api-reference/mgmt/toggle-all-schedules
patch /schedules/toggle-all
Pause or unpause every schedule for the connection associated with your access token in a single call.
# Toggle Schedule
Source: https://docs.trackstarhq.com/api-reference/mgmt/toggle-connection-schedule
patch /schedules/{function_name}/toggle
Pause or unpause a schedule for the connection associated with your access token.
# Update Connection
Source: https://docs.trackstarhq.com/api-reference/mgmt/update-connection
patch /connections
Manually update properties of the connection associated with your access token.
# Generate Sandbox
Source: https://docs.trackstarhq.com/api-reference/sandbox/generate-sandbox
post /sandbox/generate-sandbox/{integration_type}
Generates a sandbox with mocked out data.
Uses the same connection ID every time, and will reset any existing sandbox.
See the [walkthrough](/how-to-guides/sandbox) for more information.
# Get All Bills
Source: https://docs.trackstarhq.com/api-reference/wms-api/billing/get
get /wms/billing
Returns all Bills for the WMS connection associated with the provided access token.
# Get Bill
Source: https://docs.trackstarhq.com/api-reference/wms-api/billing/get-item
get /wms/billing/{bill_id}
Returns a single Bill for the WMS connection with the associated bill id.
# Billing
Source: https://docs.trackstarhq.com/api-reference/wms-api/billing/info
A bill is charged by a warehouse to a customer. Reasons for billing include shipping, storing, picking, packing, and more.
When appropriate, the ID of the object incurring the charge (often the order being shipped or unit being stored) will also be available.
Billing is disabled by default. Reach out to us if you would like to enable billing data.
# Update Inbound Shipment Trackstar Tags
Source: https://docs.trackstarhq.com/api-reference/wms-api/inbound-shipments/add-tag
put /wms/inbound-shipments/{inbound_shipment_id}/trackstar-tags
Update the trackstar tags for the specified inbound shipment.
# Get All Inbound Shipments
Source: https://docs.trackstarhq.com/api-reference/wms-api/inbound-shipments/get
get /wms/inbound-shipments
Returns all Inbound Shipments for the WMS connection associated with the provided access token.
# Get Inbound Shipment
Source: https://docs.trackstarhq.com/api-reference/wms-api/inbound-shipments/get-item
get /wms/inbound-shipments/{inbound_shipment_id}
Returns a single Inbound Shipment for the WMS connection with the associated inbound shipment id.
# Get All Inbound Shipment Suppliers
Source: https://docs.trackstarhq.com/api-reference/wms-api/inbound-shipments/inbound-shipment-suppliers-get
get /wms/inbound-shipments/suppliers
# Inbound Shipments
Source: https://docs.trackstarhq.com/api-reference/wms-api/inbound-shipments/info
An Inbound Shipment (also known as an Advance Shipping Notice, ASN, or Receiving Order) is a record of a shipment from a supplier
(usually a vendor or factory) to a warehouse. Shipments are often associated with a Purchase Order, which represents the order
that the warehouse sent to the supplier.
The Inbound Shipment contains information about the items being sent, including their individual
`inventory_item_id`s. These IDs can be passed into the [`/wms-api/inventory/{inventory_item_id}`](/api-reference/wms-api/inventory/get-item) endpoint for more details.
### Inbound Shipment Statuses (in order of lifecycle)
| Status | Definition |
| :----------- | :------------------------------------------------------------------------------------------------------------------------ |
| `open` | Shipment record has been created and items are not yet in the warehouse. |
| `in-transit` | Items are on their way to the warehouse. |
| `receiving` | The warehouse has begun the receiving process for the shipment. |
| `received` | Items have been received in the warehouse. |
| `cancelled` | Shipment has been cancelled by either the warehouse or the customer. |
| `other` | Status of the shipment can't be determined. Often due to a custom status being used. See raw\_status field for more info. |
# Create Inbound Shipment
Source: https://docs.trackstarhq.com/api-reference/wms-api/inbound-shipments/post
post /wms/inbound-shipments
Get the required, optional, and integration specific fields by calling the [integrations](/api-reference/mgmt/integrations) endpoint.
# Update Inbound Shipment
Source: https://docs.trackstarhq.com/api-reference/wms-api/inbound-shipments/put
put /wms/inbound-shipments/{inbound_shipment_id}
Get the required, optional, and integration specific fields by calling the [integrations](/api-reference/mgmt/integrations) endpoint.
# Receive Inbound Shipment
Source: https://docs.trackstarhq.com/api-reference/wms-api/inbound-shipments/receive
put /wms/inbound-shipments/{inbound_shipment_id}/receive
Receive an inbound shipment for the WMS connection with the associated inbound shipment id.
# Update Inventory Trackstar Tags
Source: https://docs.trackstarhq.com/api-reference/wms-api/inventory/add-tag
put /wms/inventory/{inventory_id}/trackstar-tags
Update the trackstar tags for the specified inventory item.
# Adjust Inventory Item
Source: https://docs.trackstarhq.com/api-reference/wms-api/inventory/adjust
put /wms/inventory/{inventory_id}/adjust
Adjust the inventory for the specified inventory item.
# Get All Inventory Items
Source: https://docs.trackstarhq.com/api-reference/wms-api/inventory/get
get /wms/inventory
Returns all Inventory for the WMS connection associated with the provided access token.
# Get Inventory Item
Source: https://docs.trackstarhq.com/api-reference/wms-api/inventory/get-item
get /wms/inventory/{inventory_id}
Returns a single Inventory Item for the WMS connection with the associated inventory id.
# Inventory
Source: https://docs.trackstarhq.com/api-reference/wms-api/inventory/info
Inventory is a representation of a physical good in a warehouse. Each product has one or more inventory items associated with it.
Each `inventory_item_id` returned from the [Product](/api-reference/wms-api/products/info) endpoint maps to the `id` field in the Inventory endpoint.
To most accurately map a `sku` or Product Name to inventory levels, first call the [Product](/api-reference/wms-api/products/info) endpoint to get the `inventory_item_id` list.
Then, call the [`/wms-api/inventory/{inventory_item_id}`](/api-reference/wms-api/inventory/get-item) endpoint to get the inventory levels for each Inventory Item.
### Inventory Breakdowns
| Field | Definition | Formula |
| :-------------- | :--------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------- |
| `awaiting` | Inventory that is expected to arrive to a warehouse. | |
| `onhand` | Total quantity in the warehouse. | committed + unfulfillable + fulfillable (this formula does not apply if an item has substitute SKUs) |
| `committed` | Inventory that is already assigned to orders. | |
| `unfulfillable` | Inventory that is damaged, quarantined, etc... | |
| `fulfillable` | Inventory that can be fulfilled and shipped for orders. | |
| `unsellable` | Inventory that is being held from sales channels (e.g. reserved) | `deprecated` |
| `sellable` | Inventory that is available in sales channels. | |
### Inventory Ledger
[Inventory ledger](/api-reference/wms-api/inventory/inventory-ledger) is designed as a time-series event log of inventory transactions that occurred at a specific point in time.
Each event is immutable and timestamped, so you’ll see the complete history of what happened to inventory over time rather than just the current state. Each transaction creates a new ledger entry, preserving the audit trail.
Example transactions that can create a new ledger entry:
* Quantity changes (receipts, shipments, adjustments, cycle counts)
* Inventory movements between locations/bins
* Status changes (available → reserved, etc.)
Inventory ledger is disabled by default. Reach out to us if you would like to enable ledger data.
# Get Inventory Ledger
Source: https://docs.trackstarhq.com/api-reference/wms-api/inventory/inventory-ledger
get /wms/inventory/ledger
Returns the Inventory Ledger for the WMS connection associated with the provided access token.
# Update Order Trackstar Tags
Source: https://docs.trackstarhq.com/api-reference/wms-api/orders/add-tag
put /wms/orders/{order_id}/trackstar-tags
Update the trackstar tags for the specified order.
# Create Order File
Source: https://docs.trackstarhq.com/api-reference/wms-api/orders/attach-file
post /wms/orders/{order_id}/file
Create a file for the specified order.
# Cancel Order
Source: https://docs.trackstarhq.com/api-reference/wms-api/orders/cancel
put /wms/orders/{order_id}/cancel
Cancel an order for the WMS connection with the associated order id.
# Ship Order
Source: https://docs.trackstarhq.com/api-reference/wms-api/orders/create-shipment
post /wms/orders/{order_id}/shipments
Marks the order as fulfilled and passes in the provided shipment and package information.
Get the required, optional, and integration specific fields by calling the [integrations](/api-reference/mgmt/integrations) endpoint.
# Get All Orders
Source: https://docs.trackstarhq.com/api-reference/wms-api/orders/get
get /wms/orders
Returns all Orders for the WMS connection associated with the provided access token.
# Get Order
Source: https://docs.trackstarhq.com/api-reference/wms-api/orders/get-item
get /wms/orders/{order_id}
Returns a single Order for the WMS connection with the associated order id.
# Get Order Packs
Source: https://docs.trackstarhq.com/api-reference/wms-api/orders/get-packs
get /wms/orders/{order_id}/packs
Returns the packs for the specified order.
# Orders
Source: https://docs.trackstarhq.com/api-reference/wms-api/orders/info
An order is a purchase made by a customer. It contains information about the order,
including the individual line items. Each line item contains a `product_id` that
can be passed to the [`/wms-api/products/{product_id}`](/api-reference/wms-api/products/get-item) for more details.
The line item may also include a `sku`.
### Order Statuses (in order of lifecycle)
| Status | Definition |
| :-------------------- | :-------------------------------------------------------------------------------------------------------------------------------- |
| `open` | Order has been placed. |
| `confirmed` | Order has been confirmed by the warehouse. |
| `processing` | Order is being processed and items are being picked. |
| `picked` | Items in order have been picked. |
| `packed` | Items in order have been packed. |
| `partially_fulfilled` | Order has been partially fulfilled. |
| `fulfilled` | Order has been fulfilled and shipped. |
| `backordered` | Order cannot be fulfilled because of a lack of available inventory. |
| `exception` | There is an issue with the order. |
| `cancelled` | Order has been cancelled by either the warehouse or the customer. |
| `other` | Status of the order can't be determined. Often due to a custom status being used. See the `raw_status` field for more information |
# Get All Order Channels
Source: https://docs.trackstarhq.com/api-reference/wms-api/orders/order-channels-get
get /wms/orders/channels
Returns all Order Channels for the WMS connection associated with the provided access token.
# Create Order
Source: https://docs.trackstarhq.com/api-reference/wms-api/orders/post
post /wms/orders
Get the required, optional, and integration specific fields by calling the [integrations](/api-reference/mgmt/integrations) endpoint.
# Update Order
Source: https://docs.trackstarhq.com/api-reference/wms-api/orders/put
put /wms/orders/{order_id}
Get the required, optional, and integration specific fields by calling the [integrations](/api-reference/mgmt/integrations) endpoint.
# Update Product Trackstar Tags
Source: https://docs.trackstarhq.com/api-reference/wms-api/products/add-tag
put /wms/products/{product_id}/trackstar-tags
Update the trackstar tags for the specified product.
# Get All Products
Source: https://docs.trackstarhq.com/api-reference/wms-api/products/get
get /wms/products
Returns all Products for the WMS connection associated with the provided access token.
# Get Product
Source: https://docs.trackstarhq.com/api-reference/wms-api/products/get-item
get /wms/products/{product_id}
Returns a single Product for the WMS connection with the associated product ID.
# Products
Source: https://docs.trackstarhq.com/api-reference/wms-api/products/info
A product is a virtual record of a product sold on an online store. It contains information about the product, such as its name, `sku`,
and a list of inventory items that make up the product.
Each `inventory_item` returned from the Product endpoint has an `inventory_item_id` that maps to the `id` field in the [Inventory](/api-reference/wms-api/inventory/info) endpoint.
To most accurately map a `sku` or Product Name to inventory levels, first call the Product endpoint to get the `inventory_items` list.
Then, call the [`/wms-api/inventory/{inventory_item_id}`](/api-reference/wms-api/inventory/get-item) endpoint to get the inventory levels for each `inventory_item_id`.
# Create a Kit Product
Source: https://docs.trackstarhq.com/api-reference/wms-api/products/kit-post
post /wms/kits
Get the required, optional, and integration specific fields by calling the [integrations](/api-reference/mgmt/integrations) endpoint.
# Update a Kit Product
Source: https://docs.trackstarhq.com/api-reference/wms-api/products/kit-put
put /wms/kits/{kit_id}
Get the required, optional, and integration specific fields by calling the [integrations](/api-reference/mgmt/integrations) endpoint.
# Create Product
Source: https://docs.trackstarhq.com/api-reference/wms-api/products/post
post /wms/products
Get the required, optional, and integration specific fields by calling the [integrations](/api-reference/mgmt/integrations) endpoint.
# Update Product
Source: https://docs.trackstarhq.com/api-reference/wms-api/products/put
put /wms/products/{product_id}
Get the required, optional, and integration specific fields by calling the [integrations](/api-reference/mgmt/integrations) endpoint.
# Update Return Trackstar Tags
Source: https://docs.trackstarhq.com/api-reference/wms-api/returns/add-tag
put /wms/returns/{return_id}/trackstar-tags
Update the trackstar tags for the specified return.
# Cancel Return
Source: https://docs.trackstarhq.com/api-reference/wms-api/returns/cancel
put /wms/returns/{return_id}/cancel
Cancel a return for the WMS connection with the associated return id.
# Get All Returns
Source: https://docs.trackstarhq.com/api-reference/wms-api/returns/get
get /wms/returns
Returns all Returns for the WMS connection associated with the provided access token.
# Get Return
Source: https://docs.trackstarhq.com/api-reference/wms-api/returns/get-item
get /wms/returns/{return_id}
Returns a single Return for the WMS connection with the associated return id.
# Returns
Source: https://docs.trackstarhq.com/api-reference/wms-api/returns/info
## Return
A Return, also known as a Return Merchandise Authorization or RMA, is an instance of a customer sending one or multiple products back to a warehouse.
It contains information about the individual items being returned, such as their inventory IDs and whether or not they have been restocked at that warehouse.
The `inventory_item_id` in each line item can be passed into the [`/wms-api/inventory/{inventory_item_id}`](/api-reference/wms-api/inventory/get-item) endpoint for more details.
### Return Statuses (in order of lifecycle)
| Status | Definition |
| :----------- | :---------------------------------------------------------------------------------------------------------------------- |
| `open` | Return has been created and items are not yet in the warehouse. |
| `in-transit` | Items are on thier way to the warehouse. |
| `receiving` | The warehouse has begun the receiving process for the return. |
| `received` | Items have been received in the warehouse. |
| `cancelled` | Return has been cancelled by either the warehouse or the customer. |
| `other` | Status of the return can't be determined. Often due to a custom status being used. See raw\_status field for more info. |
# Create Return
Source: https://docs.trackstarhq.com/api-reference/wms-api/returns/post
post /wms/returns
Get the required, optional, and integration specific fields by calling the [integrations](/api-reference/mgmt/integrations) endpoint.
# Update Return
Source: https://docs.trackstarhq.com/api-reference/wms-api/returns/put
put /wms/returns/{return_id}
Get the required, optional, and integration specific fields by calling the [integrations](/api-reference/mgmt/integrations) endpoint.
# Get All Shipping Methods
Source: https://docs.trackstarhq.com/api-reference/wms-api/shipping-methods/get
get /wms/shipping-methods
Returns all Shipping Methods for the WMS connection associated with the provided access token.
# Get Shipping Method
Source: https://docs.trackstarhq.com/api-reference/wms-api/shipping-methods/get-item
get /wms/shipping-methods/{shipping_method_id}
Returns a single Shipping Method for the WMS connection with the associated shipping method id.
# Shipping Methods
Source: https://docs.trackstarhq.com/api-reference/wms-api/shipping-methods/info
A shipping method is a way to deliver an order to a customer e.g. expedited, ground, or overnight.
Shipping methods are defined by the carrier and can be used to calculate shipping costs. The shipping method is usually selected by the customer during the checkout process.
# Get All Warehouse Customers
Source: https://docs.trackstarhq.com/api-reference/wms-api/warehouse-customers/get
get /wms/warehouse-customers
Returns all Warehouse Customers for the WMS connection associated with the provided access token.
# Get Warehouse Customer
Source: https://docs.trackstarhq.com/api-reference/wms-api/warehouse-customers/get-item
get /wms/warehouse-customers/{warehouse_customer_id}
Returns a single Warehouse Customer for the WMS connection with the associated warehouse customer id.
# Warehouse Customers
Source: https://docs.trackstarhq.com/api-reference/wms-api/warehouse-customers/info
A Warehouse Customer is the merchant/owner of inventory, products, orders, inbound-shipments, and returns.
If a connected Warehouse Management System belongs to a 3PL (or has many customers in their warehouse),
each object from the Trackstar API will have a `warehouse_customer_id` that designates which Warehouse Customer that object belongs to.
# Update Warehouse Trackstar Tags
Source: https://docs.trackstarhq.com/api-reference/wms-api/warehouses/add-tag
put /wms/warehouses/{warehouse_id}/trackstar-tags
Update the trackstar tags for the specified warehouse.
# Get All Warehouses
Source: https://docs.trackstarhq.com/api-reference/wms-api/warehouses/get
get /wms/warehouses
Returns all Warehouses for the WMS connection associated with the provided access token.
# Get Warehouse
Source: https://docs.trackstarhq.com/api-reference/wms-api/warehouses/get-item
get /wms/warehouses/{warehouse_id}
Returns a single Warehouse for the WMS connection with the associated warehouse id.
# Get All Warehouse Locations
Source: https://docs.trackstarhq.com/api-reference/wms-api/warehouses/get-warehouse-locations
get /wms/warehouses/{warehouse_id}/locations
Returns all Warehouse Locations for the WMS connection with the associated warehouse id.
# Get Warehouse Location
Source: https://docs.trackstarhq.com/api-reference/wms-api/warehouses/get-warehouse-locations-item
get /wms/warehouses/{warehouse_id}/locations/{location_id}
Returns a single Warehouse Location for the WMS connection with the associated warehouse and location id.
# Warehouses
Source: https://docs.trackstarhq.com/api-reference/wms-api/warehouses/info
A warehouse is a physical location where inventory is stored. It contains information about the warehouse, such as its name and (if applicable) code.
Within a warehouse can exist many locations. A location is a specific area where inventory is stored (e.g. a shelf, a bin, a pallet, etc...). Use the `GET /get-warehouse-locations` endpoint to get a list of locations within a warehouse.
# About the API
Source: https://docs.trackstarhq.com/how-to-guides/about-the-api
Structures and paradigms for the Trackstar API
The Trackstar API can be hit at [https://production.trackstarhq.com](https://production.trackstarhq.com).
Trackstar API responses are all returned in JSON format. They will also contain the header `X-Request-Id: abc123`
## Authentication
All Trackstar API requests require an API Key to authenticate requests. You can view and manage your API keys in the [Trackstar dashboard](https://dashboard.trackstarhq.com/settings/api-keys).
Additionally most endpoints also require an access token, which maps to a specific connection (a customer's integrated WMS, Cart, or Carrier). Access tokens are returned at the end of the [Token Exchange](/how-to-guides/getting-started#2-implement-token-exchange-endpoints-be) process. They can also be found in the [Connections page of the Trackstar dashboard](https://dashboard.trackstarhq.com/connections).
To authenticate a request, include the following headers:
```bash theme={null}
headers = {
"x-trackstar-api-key": "",
"x-trackstar-access-token": "" # When required
}
```
## OpenAPI Spec and Postman Collection
The Trackstar OpenAPI spec can be found at [https://production.trackstarhq.com/openapi.json](https://production.trackstarhq.com/openapi.json). The API documentation found on this page is a stylized version of that spec.
The Trackstar Postman collection can be found in JSON format at [https://production.trackstarhq.com/postman.json](https://production.trackstarhq.com/postman.json). To use it, simply open the Postman [app](https://www.postman.com/downloads/) or [web client](https://postman.co/home), click "Import", and type in the above URL.
## Errors
Standard HTTP status codes are used to indicate success or failure of an API request.
Error response bodies are returned in the following format:
```json theme={null}
{
"error": "Sample error message",
"origin": "trackstar"
}
```
* `error`: The error message.
* `origin`: The origin of the error. This will be `"trackstar"` for errors originating from the Trackstar API, and `"integration"` for errors originating from an integration.
Errors will always have a status code associated with them. Some types of errors will contain additional fields, but all will contain `"error"` and `"origin"`.
### Unimplemented Endpoints
Endpoints that are not supported for a given integration (e.g. `GET /wms/returns` for the `Cool WMS` integration) will return a `501` status code with the following body:
```json theme={null}
{
"error": "Endpoint get_returns is not implemented for Cool WMS"
}
```
## Pagination
Endpoints that list data retrieve 1000 items by default. You can change this using the `limit` query parameter.
1000 is the max supported page size. Any limit that exceeds 1000 will only return 1000 results.
Endpoints implement pagination logic and return a `next_token`, which will be `null` if there is no additional data. Valid `next_token`s can then be passed into the endpoint's `page_token` parameter to get the next page of results. Leave this field out to get the first page.
When paginating, keep all original filters across subsequent requests.
### Example: Paginating through all orders
```python Python theme={null}
import requests
API_KEY = "YOUR_API_KEY"
ACCESS_TOKEN = "YOUR_ACCESS_TOKEN"
url = "https://production.trackstarhq.com/wms/orders"
headers = {
"x-trackstar-api-key": API_KEY,
"x-trackstar-access-token": ACCESS_TOKEN
}
all_orders = []
params = {"limit": 500}
response = requests.get(url, headers=headers, params=params)
data = response.json()
all_orders.extend(data["data"])
while data["next_token"]:
params["page_token"] = data["next_token"]
response = requests.get(url, headers=headers, params=params)
data = response.json()
all_orders.extend(data["data"])
print(f"Fetched {len(all_orders)} orders")
```
```javascript JavaScript theme={null}
const API_KEY = "YOUR_API_KEY";
const ACCESS_TOKEN = "YOUR_ACCESS_TOKEN";
const url = "https://production.trackstarhq.com/wms/orders";
const headers = {
"x-trackstar-api-key": API_KEY,
"x-trackstar-access-token": ACCESS_TOKEN
};
const allOrders = [];
let pageToken = null;
do {
const params = new URLSearchParams({ limit: "500" });
if (pageToken) params.set("page_token", pageToken);
const response = await fetch(`${url}?${params}`, { headers });
const data = await response.json();
allOrders.push(...data.data);
pageToken = data.next_token;
} while (pageToken);
console.log(`Fetched ${allOrders.length} orders`);
```
## Filtering
Some list endpoints support different shapes for query parameters. For parameters that support them, possible comparison operators are `= or eq` (equal), `neq` (not equal), `gt` (greater than), `lt` (less than), `gte` (greater than or equal), `lte` (less than or equal), `in` (in a list), and `nin` (not in a list).
For `in` and `nin` the API accepts a comma separated string e.g. `value_1,value_2`, up to a maximum of 100 values. Requests with more than 100 values return a `422`; split them across multiple requests.
When filtering by a date, the fastest and most efficient query is to use both `gte` and `lte` to filter by a date range.
### Examples
Filter orders created in a specific date range:
```bash theme={null}
curl -X GET "https://production.trackstarhq.com/wms/orders?created_date[gte]=2026-01-01T00:00:00Z&created_date[lte]=2026-01-02T23:59:59Z" \
-H "x-trackstar-api-key: YOUR_API_KEY" \
-H "x-trackstar-access-token: YOUR_ACCESS_TOKEN"
```
Filter orders by status:
```bash theme={null}
curl -X GET "https://production.trackstarhq.com/wms/orders?status=fulfilled" \
-H "x-trackstar-api-key: YOUR_API_KEY" \
-H "x-trackstar-access-token: YOUR_ACCESS_TOKEN"
```
Filter orders by multiple statuses using `in`:
```bash theme={null}
curl -X GET "https://production.trackstarhq.com/wms/orders?status[in]=fulfilled,open" \
-H "x-trackstar-api-key: YOUR_API_KEY" \
-H "x-trackstar-access-token: YOUR_ACCESS_TOKEN"
```
Combine filters — fulfilled orders from the last week:
```bash theme={null}
curl -X GET "https://production.trackstarhq.com/wms/orders?status=fulfilled&updated_date[gte]=2026-04-01T00:00:00Z" \
-H "x-trackstar-api-key: YOUR_API_KEY" \
-H "x-trackstar-access-token: YOUR_ACCESS_TOKEN"
```
More details can be found in each individual endpoint's documentation.
## Rate Limits
The Trackstar API has the following rate limits on a per access-token basis:
| Method | Rate Limit |
| ------------------------ | ------------------ |
| GET | 10 requests/second |
| POST, PUT, PATCH, DELETE | 50 requests/second |
This means that if you have multiple access tokens, you can make requests up to the limit for each one. If you exceed the limit, you will receive a `429 Too Many Requests` response.
The API will return the following headers to indicate your current rate limit status:
```json theme={null}
{
"x-ratelimit-limit": "10",
"x-ratelimit-remaining": "9",
"x-ratelimit-reset": "1746126611",
"retry-after": "1"
}
```
* `x-ratelimit-limit`: The total number of requests allowed per second.
* `x-ratelimit-remaining`: The number of requests you have remaining in the current second.
* `x-ratelimit-reset`: The epoch time when your rate limit will reset.
* `retry-after`: The number of seconds you should wait before making another request.
# Connection Issues
Source: https://docs.trackstarhq.com/how-to-guides/connection-issues
Understanding and resolving connection errors
After a connection is created, Trackstar continuously monitors its health. Two types of issues can occur: **invalid credentials** and **missing permissions**. Understanding the difference is key to resolving them quickly.
## Types of Connection Issues
### Invalid Credentials (Blocking)
Invalid credential errors mean Trackstar can no longer authenticate with the connected system. This is a **blocking** issue — no data can be synced for any resource until the credentials are updated.
Common causes:
* Password or API key was rotated or expired
* Account was deactivated or suspended
* OAuth token was revoked
When this happens, the connection needs to be [reinstalled](#reinstalling-a-connection) with fresh credentials.
### Missing Permissions (Non-Blocking)
Permission errors mean the credentials are valid, but they don't have access to all supported resources. This is a **non-blocking** issue — the connection will continue to sync data for the resources it does have access to. Only the restricted resources are affected.
Common causes:
* API key has limited scope (e.g. read-only access, no access to returns)
* User role in the connected system doesn't include all modules
* Certain features are disabled or not part of the customer's plan
These can often be resolved by updating the user's role or permissions in the connected system, or by reinstalling with credentials that have broader access.
## How Issues Appear
### In the Dashboard
The [Connections page](https://dashboard.trackstarhq.com/connections) shows the health status of each connection. Click into a connection to see detailed error information, including whether issues are blocking or non-blocking, and which specific resources are affected.
A healthy connection with full permissions:
A connection with invalid credentials shows a blocking error on every resource:
A connection with missing permissions shows errors only on the affected resources:
### Via Webhooks
* `connection-error.created` — fired when a new error is detected (credential or permission)
* `connection-error.updated` — fired when an existing error changes
* `connection-error.deleted` — fired when an error is resolved (e.g. after reinstalling with updated credentials)
See the [webhooks documentation](/how-to-guides/webhooks) for more details.
### Via the API
The [GET /connections](/api-reference/mgmt/get-connections) endpoint returns a populated `errors` array when a connection has issues:
```json theme={null}
{
"data": {
"connection_id": "conn_abc123",
"integration_name": "some_integration",
"errors": [
{
"error_type": "invalid_credentials",
"resource": null,
"message": "The provided credentials are no longer valid."
}
]
}
}
```
For permission errors, the `resource` field indicates which specific resource is affected:
```json theme={null}
{
"errors": [
{
"error_type": "missing_permission",
"resource": "returns",
"message": "The provided credentials do not have access to returns data."
}
]
}
```
### Email Notifications
Trackstar can send email notifications when connection issues are detected. Configure email notification settings in the [dashboard](https://dashboard.trackstarhq.com/settings/notifications). This gives your team visibility into issues without needing to build webhook handling.
## Reinstalling a Connection
When credentials need to be updated, you can reinstall the connection. There are three ways:
* In the [Trackstar Dashboard](https://dashboard.trackstarhq.com/connections) by clicking the "Reinstall Connection" button within the connection row
* By generating a [magic link](/how-to-guides/trackstar-link#sending-a-magic-link) with the `Reinstall Existing Connection` field filled in
* Programmatically via the embedded Trackstar Link flow: pass the `connection_id` of the broken connection to the [`POST /link/token`](/api-reference/mgmt/create-link-token) endpoint when generating a link token. When your user opens Trackstar Link with this token, it will skip the integration selection screen and go directly to the credential input for that connection. After they enter new credentials, the connection is reinstalled automatically.
```bash theme={null}
curl -X POST https://production.trackstarhq.com/link/token \
-H "x-trackstar-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"connection_id": "conn_abc123"}'
```
The connection will be reinstalled with the same ID and access token, so no code changes are needed on your side. No historical data will be lost, and a new initial sync will be triggered for any newly-accessible resources.
## Proactively Checking Connection Health
You can call [`GET /connections/{id}`](/api-reference/mgmt/get-connection) at any time to check the `errors` array and verify a connection is healthy before relying on the data.
# Getting Started
Source: https://docs.trackstarhq.com/how-to-guides/getting-started
## How Trackstar Works
Trackstar connects your application to your customers' systems (WMS, Cart, or Carrier) through a unified API. Here's the core model:
1. You create a **connection** between your app and a customer's system. Each connection produces an **access token**.
2. After connecting, Trackstar performs an **initial sync** that pulls historical data (30 days by default).
3. Once the sync completes, you can read and write data through Trackstar's API. Data is kept up to date automatically via recurring syncs.
## Quick Setup (No Coding Required)
You can start connecting your customers' systems to Trackstar in minutes without writing any code using one of these methods:
1. Inputting credentials directly into the Trackstar dashboard.
2. Sending a Magic Link to your customers to connect their system.
### 1. Inputting Credentials
If your customer has provided you with their credentials, you can input them directly into the Trackstar dashboard.
1. Go to the [Connections page](https://dashboard.trackstarhq.com/connections) in the Trackstar dashboard.
2. Click the "Add Connection" button.
3. Select the integration you want to connect.
4. Fill in the required fields (e.g. API key, username, password).
5. An access token will be generated for you. This token is used to authenticate requests to Trackstar.
### 2. Sending a Magic Link
If you don't have your customer's credentials, you can send them a Magic Link to connect their system.
1. Go to the [Connections page](https://dashboard.trackstarhq.com/connections) in the Trackstar dashboard.
2. Click the "Generate Magic Link" button.
3. Fill out the settings for the Magic Link (e.g. expiration time, available actions).
4. Send the generated URL to your customer.
5. Your customer will be able to connect their system by opening the link and entering their credentials.
6. Once completed, you can find the access token in the Trackstar dashboard.
## Fully Embedded Setup (Coding Required)
The following guide will walk you through integrating [Trackstar Link](/how-to-guides/trackstar-link) into your application. Trackstar Link is a javascript component that you embed in your frontend to allow your users to connect their systems via Trackstar.
If you get stuck or have trouble, email us at `support@trackstarhq.com`.
Fully setting up Trackstar will require updates to both your frontend (FE) and backend (BE) code. We will denote which steps are for the frontend and which are for the backend.
Your frontend will make calls to your backend, which will in turn make calls to the Trackstar API. This gets the authorization necessary for your user to authenticate with Trackstar and the underlying APIs.
### 1. Get an API key
You can find your API keys in the [Trackstar dashboard](https://dashboard.trackstarhq.com/settings/api-keys).
Test it by making an API call to the `POST /link/token` endpoint to get a link token.
```bash theme={null}
curl -X POST https://production.trackstarhq.com/link/token \
-H 'x-trackstar-api-key: YOUR_API_KEY'
```
If successful, you should get a response like this:
```json theme={null}
{
"link_token": "some_link_token"
}
```
**Store this API key somewhere safe!** This will be the API key for your whole organization.
### 2. Implement Token Exchange Endpoints (BE)
There are two backend API endpoints that you need to implement. (Note: you can name these endpoints whatever you want, but we will use the names `/get-link-token` and `/store-token` in this guide).
* `POST /get-link-token` - Returns a **temporary link token** that is used to initialize the `react-trackstar-link` component.
* `POST /store-token` - Exchanges a **temporary auth code** for a **permanent access token** and saves it to a database. This access token is associated with a customer and an integration (e.g. ShipBob, Shopify, FedEx).
We will use a combination of Python + Flask or Node.js + Express + Axios in this guide, but you can use any language and framework you want.
#### 2.1 `/get-link-token`
**Link tokens** are temporary access keys granted to your frontend to make API calls on behalf of your organization. Your frontend will call this endpoint to get a link token. You will see this being called in step 4.
```python Python theme={null}
from flask import Flask
import requests
TRACKSTAR_API_KEY = ""
@app.route("/get-link-token", methods=["POST"])
def link_token():
response = requests.post(
"https://production.trackstarhq.com/link/token",
headers={
"x-trackstar-api-key": TRACKSTAR_API_KEY,
"Content-Type": "application/json"
},
)
response.raise_for_status()
response = response.json()
link_token = response["link_token"]
return {"linkToken": link_token}
```
```javascript Node.js theme={null}
const express = require('express');
const axios = require('axios');
const app = express();
const TRACKSTAR_API_KEY = '';
app.use(express.json());
app.post('/get-link-token', async (req, res) => {
try {
const response = await axios.post(
'https://production.trackstarhq.com/link/token',
null,
{
headers: {
'x-trackstar-api-key': TRACKSTAR_API_KEY
},
},
);
const { link_token } = response.data;
res.send({ linkToken: link_token });
} catch (error) {
console.error(error);
res.status(500).send('Error getting link token');
}
});
app.listen(3000, () => {
console.log('Server listening on port 3000');
});
```
#### 2.2 `/store-token`
After a user installs an integration, the frontend will send an **auth code** to the backend, along with any relevant customer data. The **auth code** is a temporary token that you must exchange via Trackstar's `/link/exchange` endpoint to get a long-lived `access_token`.
Additionally, a `connection_id` and `integration_name` will be returned. **Connection IDs** are unique identifiers for each connected integration. You should store these in your database along with the `access_token` if you plan on utilizing Trackstar Webhooks.
```python Python theme={null}
from flask import Flask, request
import requests
TRACKSTAR_API_KEY = ""
@app.route("/store-token", methods=["POST"])
def store_token():
body = request.get_json()
customer_id = body.get("customer_id") # and any other relevant info from your FE
auth_code = body.get("auth_code")
# Call Trackstar API to get access_token (and integration_name)
response = requests.post(
"https://production.trackstarhq.com/link/exchange",
json={"auth_code": auth_code},
headers={
"x-trackstar-api-key": TRACKSTAR_API_KEY,
"Content-Type": "application/json"
},
)
response.raise_for_status()
response = response.json()
access_token, connection_id, integration_name, available_actions = (
response["access_token"],
response["connection_id"],
response["integration_name"],
response["available_actions"],
)
# Store customer_id, access_token, connection_id, integration_name in your database
access_tokens_table = ...
row = {
"customer_id": customer_id,
"access_token": access_token,
"connection_id": connection_id,
"integration_name": integration_name,
"available_actions": available_actions,
}
access_tokens_table.put(row)
return "Success!" # back to your frontend
```
```javascript Node.js theme={null}
const express = require('express');
const axios = require('axios');
const app = express();
const TRACKSTAR_API_KEY = '';
app.use(express.json());
app.post('/store-token', async (req, res) => {
const { customer_id, auth_code } = req.body;
// And any other relevant info from your frontend
try {
// Call Trackstar API to get access_token (and integration_name)
const response = await axios.post(
'https://production.trackstarhq.com/link/exchange',
{ auth_code },
{
headers: {
'x-trackstar-api-key': TRACKSTAR_API_KEY,
'Content-Type': 'application/json'
},
},
);
const { access_token, connection_id, integration_name } = response.data;
// Store customer_id, access_token, integration_name in your database
const access_tokens_table = ...;
const row = {
customer_id,
access_token,
connection_id,
integration_name,
};
await access_tokens_table.put(row);
res.send('Success!'); // back to your frontend
} catch (error) {
console.error(error);
res.status(500).send('Error storing token');
}
});
app.listen(3000, () => {
console.log('Server listening on port 3000');
});
```
### 3. Install react-trackstar-link (FE)
In your frontend code, install the official [react-trackstar-link](https://www.npmjs.com/package/@trackstar/react-trackstar-link) package.
```bash npm theme={null}
npm install @trackstar/react-trackstar-link
```
or
```bash yarn theme={null}
yarn add @trackstar/react-trackstar-link
```
### 4. Implement react-trackstar-link (FE)
In your frontend code, import the `TrackstarConnectButton` component and render it in your app.
```jsx theme={null}
import { TrackstarConnectButton } from '@trackstar/react-trackstar-link';
function App() {
const someCustomerId = "12345";
return (
{
// the endpoint you implemented in step 2.1
const response = await fetch('https://my-company.backend.com/get-link-token',
{
method: 'POST',
}
);
const { linkToken } = await response.json();
return linkToken;
}}
onSuccess={async (authCode, integrationName) =>
// the endpoint you implemented in step 2.2
await fetch('https://my-company.backend.com/store-token',
{
method: 'POST',
headers: {
'Content-Type': 'application/json',
},
body: JSON.stringify({
customer_id: someCustomerId,
auth_code: authCode,
integration_name: integrationName,
}),
}
)
}
onClose={() => console.log('closed')}
onLoad={() => console.log('loaded')}
// sandbox={true} // Set to true to include a "Sandbox" integration in the list
>
Connect Integration
);
}
```
By default, Trackstar Link shows WMS integrations. To connect Cart or Carrier integrations, set the `integrationType` prop to `"cart"` or `"carrier"`. See the [Trackstar Link docs](/how-to-guides/trackstar-link#available-props) for all available props.
More documentation, including additional properties, can be found [here](https://github.com/trackstarhq/react-trackstar-link).
### 5. Make API calls (BE)
Now you can use the access token to make API calls to Trackstar!
After a new connection is created, Trackstar performs an **initial sync** that pulls data from the last 30 days. **Data will not be available until this sync completes.**
You can know when data is ready by:
* **Listening for the [`connection.historical-sync-completed`](/how-to-guides/webhooks/admin/connection-historical-sync) webhook** — this fires for each resource type (e.g. orders, inventory) as it finishes syncing. This is the recommended approach.
* **Polling [`GET /connections/{id}`](/api-reference/mgmt/get-connection)** — check the connection's sync status programmatically.
For more details on sync behavior and timing, see [Syncing Data](/how-to-guides/syncing-data#initial-sync-behavior).
Here are examples querying each API vertical:
```python WMS API theme={null}
import requests
TRACKSTAR_API_KEY = ""
ACCESS_TOKEN = ""
url = "https://production.trackstarhq.com/wms/inventory"
headers = {
"x-trackstar-api-key": TRACKSTAR_API_KEY,
"x-trackstar-access-token": ACCESS_TOKEN, # from your database that you stored in step 2.2
"Content-Type": "application/json"
}
response = requests.get(url, headers=headers)
response.raise_for_status()
data = response.json()
```
```python Cart API theme={null}
import requests
TRACKSTAR_API_KEY = ""
ACCESS_TOKEN = ""
url = "https://production.trackstarhq.com/cart/orders"
headers = {
"x-trackstar-api-key": TRACKSTAR_API_KEY,
"x-trackstar-access-token": ACCESS_TOKEN, # from your database that you stored in step 2.2
"Content-Type": "application/json"
}
response = requests.get(url, headers=headers)
response.raise_for_status()
data = response.json()
```
```python Carrier API theme={null}
import requests
TRACKSTAR_API_KEY = ""
ACCESS_TOKEN = ""
url = "https://production.trackstarhq.com/carrier/invoice-line-items"
headers = {
"x-trackstar-api-key": TRACKSTAR_API_KEY,
"x-trackstar-access-token": ACCESS_TOKEN, # from your database that you stored in step 2.2
"Content-Type": "application/json"
}
response = requests.get(url, headers=headers)
response.raise_for_status()
data = response.json()
```
You can read the API reference for all supported operations.
### 6. What's Next
Now that you have Trackstar set up, here are some next steps:
* **[Syncing Data](/how-to-guides/syncing-data)** — learn about sync frequencies, initial sync behavior, and how to trigger manual syncs.
* **[Webhooks](/how-to-guides/webhooks/webhooks)** — get notified in real time when data changes (e.g. orders created, inventory updated).
* **[Sandbox](/how-to-guides/sandbox)** — test your integration with mocked data before going live.
* **[Writing Data](/how-to-guides/programmatic-writes)** — create orders, update products, and write data back to your customers' systems.
* **[Use Cases](/use-cases/overview)** — see detailed guides for common workflows like order fulfillment and inventory management.
If you have any questions or feedback, email us at `support@trackstarhq.com`.
# On-Demand Syncs
Source: https://docs.trackstarhq.com/how-to-guides/on-demand-syncs
On-demand syncs let you trigger a backfill of a specific data type over a custom time window, outside of Trackstar's normal sync schedule. They're useful for re-syncing historical data or pulling a longer window of data than the default [30-day initial sync](/how-to-guides/syncing-data#initial-sync-behavior).
For information about Trackstar's normal scheduled syncs, see [Syncing Data](/how-to-guides/syncing-data).
## Supported Functions
Support is rolled out per integration + function. If you'd like support added for an integration or function, [reach out to us](mailto:support@trackstarhq.com) and we'll look into enabling it.
### WMS
**Available function names:**
* `get_products`
* `get_orders`
* `get_inbound_shipments`
* `get_returns`
* `get_bills`
* `get_inventory_ledger`
`get_inventory` is intentionally **not** supported for on-demand syncs. Inventory syncs always fetch a full snapshot from the integration regardless of the time window, so an on-demand sync over a custom range would not change what gets pulled. To refresh inventory, use [`POST /connections/{id}/sync`](/api-reference/mgmt/sync-connection) or wait for the next scheduled sync.
### Carrier
**Available function names:**
* `get_invoice_line_items`
### Cart
On-demand syncs are not currently enabled for any Cart functions.
## Usage
There are three endpoints for managing on-demand syncs:
| Operation | Method | Path |
| ------------------- | ------ | --------------------------------------------------- |
| Create a sync job | `POST` | `/connections/on-demand-syncs` |
| Get sync job status | `GET` | `/connections/on-demand-syncs/{sync_job_id}` |
| Cancel a sync job | `POST` | `/connections/on-demand-syncs/{sync_job_id}/cancel` |
Like all Trackstar API calls, you'll need to authenticate [using your API key and the access token](/how-to-guides/getting-started#5-make-api-calls-be) for the specific connection.
You can manage on-demand syncs either through the API directly or through the [Trackstar dashboard](https://dashboard.trackstarhq.com/connections). Each section below shows both options — pick whichever fits your workflow.
## Creating a Sync Job
### Request Parameters
The following parameters are required when creating a sync job via the API:
ISO 8601 timestamp marking the start of the time window to sync (e.g., `2025-12-01T00:00:00Z`).
ISO 8601 timestamp marking the end of the time window to sync (e.g., `2026-01-01T00:00:00Z`).
The data-fetching function to run. Must be one of the values listed in [Supported Functions](#supported-integrations-and-functions).
If you attempt to start an on-demand sync for an integration + function combination that isn't currently enabled, you will receive a `400` response with the message:
```text theme={null}
On-demand sync is not enabled for {integration_name} {function_name}
```
```python Python theme={null}
import requests
TRACKSTAR_API_KEY = "your_api_key"
ACCESS_TOKEN = "your_access_token"
url = "https://production.trackstarhq.com/connections/on-demand-syncs"
headers = {
"x-trackstar-api-key": TRACKSTAR_API_KEY,
"x-trackstar-access-token": ACCESS_TOKEN,
"Content-Type": "application/json"
}
payload = {
"start_time": "2025-12-01T00:00:00Z",
"end_time": "2026-01-01T00:00:00Z",
"function_name": "get_orders"
}
response = requests.post(url, headers=headers, json=payload)
response.raise_for_status()
sync_job = response.json()
print(sync_job)
```
```javascript Node.js theme={null}
const axios = require('axios');
const TRACKSTAR_API_KEY = 'your_api_key';
const ACCESS_TOKEN = 'your_access_token';
const url = 'https://production.trackstarhq.com/connections/on-demand-syncs';
const headers = {
'x-trackstar-api-key': TRACKSTAR_API_KEY,
'x-trackstar-access-token': ACCESS_TOKEN,
'Content-Type': 'application/json'
};
const payload = {
start_time: '2025-12-01T00:00:00Z',
end_time: '2026-01-01T00:00:00Z',
function_name: 'get_orders'
};
const response = await axios.post(url, payload, { headers });
console.log(response.data);
```
```bash cURL theme={null}
curl --request POST \
--url https://production.trackstarhq.com/connections/on-demand-syncs \
--header 'x-trackstar-api-key: your_api_key' \
--header 'x-trackstar-access-token: your_access_token' \
--header 'Content-Type: application/json' \
--data '{
"start_time": "2025-12-01T00:00:00Z",
"end_time": "2026-01-01T00:00:00Z",
"function_name": "get_orders"
}'
```
1. Open the [Connections page](https://dashboard.trackstarhq.com/connections) and click into the connection you want to sync.
2. In the connection details drawer, switch to the **On-Demand Syncs** tab.
3. Click **Create**.
4. In the modal, pick a function, choose a start and end time (interpreted as your local timezone and converted to UTC on submit), and click **Create Sync Job**.
The new job will appear at the top of the list with status `open`.
## Checking Sync Job Status
Use the `sync_job_id` returned from the create call to check progress. The response includes a `status` field with one of the following values:
| Status | Meaning |
| ----------- | --------------------------------------------------------------------------------------------------- |
| `open` | The job has been created and is either queued or actively running. |
| `completed` | The job finished successfully. Synced data is now available via the standard Trackstar API. |
| `cancelled` | The job was cancelled before it could finish (see [Cancelling a Sync Job](#cancelling-a-sync-job)). |
A typical successful lifecycle is `open → completed`. A cancelled job follows `open → cancelled`. Only jobs in the `open` state can be cancelled.
The full response also includes `id`, `connection_id`, `function_name`, `requested_start_time`, `requested_end_time`, and `created_at`.
Use the `sync_job_id` returned from the create call:
```python Python theme={null}
import requests
TRACKSTAR_API_KEY = "your_api_key"
ACCESS_TOKEN = "your_access_token"
SYNC_JOB_ID = "your_sync_job_id"
url = f"https://production.trackstarhq.com/connections/on-demand-syncs/{SYNC_JOB_ID}"
headers = {
"x-trackstar-api-key": TRACKSTAR_API_KEY,
"x-trackstar-access-token": ACCESS_TOKEN
}
response = requests.get(url, headers=headers)
response.raise_for_status()
status = response.json()
print(status)
```
```javascript Node.js theme={null}
const axios = require('axios');
const TRACKSTAR_API_KEY = 'your_api_key';
const ACCESS_TOKEN = 'your_access_token';
const SYNC_JOB_ID = 'your_sync_job_id';
const url = `https://production.trackstarhq.com/connections/on-demand-syncs/${SYNC_JOB_ID}`;
const headers = {
'x-trackstar-api-key': TRACKSTAR_API_KEY,
'x-trackstar-access-token': ACCESS_TOKEN
};
const response = await axios.get(url, { headers });
console.log(response.data);
```
```bash cURL theme={null}
curl --request GET \
--url https://production.trackstarhq.com/connections/on-demand-syncs/your_sync_job_id \
--header 'x-trackstar-api-key: your_api_key' \
--header 'x-trackstar-access-token: your_access_token'
```
The **On-Demand Syncs** tab in the connection details drawer lists all sync jobs for that connection, with their function name, status, and requested window. The list is sorted by most recently created first.
Click the refresh icon to re-fetch the list — the dashboard does not auto-poll.
## Cancelling a Sync Job
If a sync job is no longer needed, you can cancel it before it completes. Only jobs in the `open` state can be cancelled.
```python Python theme={null}
import requests
TRACKSTAR_API_KEY = "your_api_key"
ACCESS_TOKEN = "your_access_token"
SYNC_JOB_ID = "your_sync_job_id"
url = f"https://production.trackstarhq.com/connections/on-demand-syncs/{SYNC_JOB_ID}/cancel"
headers = {
"x-trackstar-api-key": TRACKSTAR_API_KEY,
"x-trackstar-access-token": ACCESS_TOKEN,
"Content-Type": "application/json"
}
response = requests.post(url, headers=headers)
response.raise_for_status()
print(response.json())
```
```javascript Node.js theme={null}
const axios = require('axios');
const TRACKSTAR_API_KEY = 'your_api_key';
const ACCESS_TOKEN = 'your_access_token';
const SYNC_JOB_ID = 'your_sync_job_id';
const url = `https://production.trackstarhq.com/connections/on-demand-syncs/${SYNC_JOB_ID}/cancel`;
const headers = {
'x-trackstar-api-key': TRACKSTAR_API_KEY,
'x-trackstar-access-token': ACCESS_TOKEN,
'Content-Type': 'application/json'
};
const response = await axios.post(url, null, { headers });
console.log(response.data);
```
```bash cURL theme={null}
curl --request POST \
--url https://production.trackstarhq.com/connections/on-demand-syncs/your_sync_job_id/cancel \
--header 'x-trackstar-api-key: your_api_key' \
--header 'x-trackstar-access-token: your_access_token' \
--header 'Content-Type: application/json'
```
In the **On-Demand Syncs** tab, click the cancel icon at the end of any row whose status is `open`. The icon only appears for cancellable rows.
Once cancelled, the job stays in the list with status `cancelled` and the icon disappears.
## Important Notes
* **Asynchronous execution:** Sync jobs run in the background. Poll the status endpoint or rely on Trackstar's existing webhooks (e.g. [`order.created`](/how-to-guides/webhooks/wms/order-created), [`order.updated`](/how-to-guides/webhooks/wms/order-updated)) to know when new data has landed.
* **Precedence over scheduled syncs:** On-demand syncs take precedence over scheduled syncs on the same connection. While a sync job is in the `open` state, the regularly scheduled syncs for that connection will not run, which can cause recent data to fall behind. Once all open sync jobs finish (or are cancelled), scheduled syncs automatically resume from where they left off — so no data is missed, only delayed.
# Passthrough Requests
Source: https://docs.trackstarhq.com/how-to-guides/passthrough-requests
Passthrough requests allow you to make direct API calls to an integration's API using the credentials already stored in Trackstar. This is useful when you need to access data that Trackstar may not make requests for.
## Supported Integrations
Passthrough is currently being rolled out on a per-integration basis. The following integrations are currently supported:
### WMS
* Amazon
* Deposco
* Linnworks
* ShipHero
* Tiktok
* Veracore
* Walmart
### Cart
* Amazon
* NuOrder
* Tiktok
* Shopify
* Wayfair
This list is regularly updated as we add passthrough support to more integrations.
## API Endpoint
Send POST requests to the URL below with the required body parameters to create a passthrough request. `` will either be `wms` or `cart`.
```
https://production.trackstarhq.com//passthrough
```
Like all Trackstar API calls, you'll need to authenticate using your API key and the access token for the specific connection.
### Request Parameters
The HTTP method to use for the request. Must be one of: `GET`, `POST`, `PUT`, `PATCH`, `DELETE`.
The integration-specific endpoint path (e.g., `/graphql`, `/api/v1/orders`). This is the path on the integration's API, not Trackstar's.
The request body to send to the integration. For example, for GraphQL requests, this would contain your query. Only used with POST, PUT, and PATCH methods.
Optional additional headers to send with the request. Trackstar automatically handles authentication headers for you.
Optional query parameters to append to the request URL (e.g., `{"page": "1", "limit": "100"}`).
### Response Format
The passthrough endpoint returns the raw response from the integration's API with the following structure:
* **status\_code**: The HTTP status code returned by the integration
* **headers**: Response headers from the integration
* **body**: The raw response body from the integration
## Example Request
Here's an example of making a passthrough request to retrieve data from an integration-specific endpoint:
```python Python theme={null}
import requests
TRACKSTAR_API_KEY = "your_api_key"
ACCESS_TOKEN = "your_access_token"
url = "https://production.trackstarhq.com/wms/passthrough"
headers = {
"x-trackstar-api-key": TRACKSTAR_API_KEY,
"x-trackstar-access-token": ACCESS_TOKEN,
"Content-Type": "application/json"
}
payload = {
"method": "GET",
"path": "/api/v1/custom-endpoint",
"params": {
"page": "1",
"limit": "50"
}
}
response = requests.post(url, headers=headers, json=payload)
response.raise_for_status()
data = response.json()
# Access the raw integration response
print(f"Status: {data['status_code']}")
print(f"Body: {data['body']}")
```
```javascript Node.js theme={null}
const axios = require('axios');
const TRACKSTAR_API_KEY = 'your_api_key';
const ACCESS_TOKEN = 'your_access_token';
const url = 'https://production.trackstarhq.com/wms/passthrough';
const headers = {
'x-trackstar-api-key': TRACKSTAR_API_KEY,
'x-trackstar-access-token': ACCESS_TOKEN,
'Content-Type': 'application/json'
};
const payload = {
method: 'GET',
path: '/api/v1/custom-endpoint',
params: {
page: '1',
limit: '50'
}
};
const response = await axios.post(url, payload, { headers });
// Access the raw integration response
console.log(`Status: ${response.data.status_code}`);
console.log(`Body: ${response.data.body}`);
```
```bash cURL theme={null}
curl --request POST \
--url https://production.trackstarhq.com/wms/passthrough \
--header 'x-trackstar-api-key: your_api_key' \
--header 'x-trackstar-access-token: your_access_token' \
--header 'Content-Type: application/json' \
--data '{
"method": "GET",
"path": "/api/v1/custom-endpoint",
"params": {
"page": "1",
"limit": "50"
}
}'
```
## Example: GraphQL Request
Some integrations use GraphQL. Here's how to make a GraphQL query via passthrough:
```python Python theme={null}
import requests
TRACKSTAR_API_KEY = "your_api_key"
ACCESS_TOKEN = "your_access_token"
url = "https://production.trackstarhq.com/wms/passthrough"
headers = {
"x-trackstar-api-key": TRACKSTAR_API_KEY,
"x-trackstar-access-token": ACCESS_TOKEN,
"Content-Type": "application/json"
}
# GraphQL query
payload = {
"method": "POST",
"path": "/graphql",
"headers": {
"Content-Type": "application/json"
},
"data": {
"query": """
query {
products(first: 10) {
edges {
node {
id
name
sku
}
}
}
}
"""
}
}
response = requests.post(url, headers=headers, json=payload)
response.raise_for_status()
data = response.json()
# Access the GraphQL response
graphql_response = data['body']
print(graphql_response)
```
```javascript Node.js theme={null}
const axios = require('axios');
const TRACKSTAR_API_KEY = 'your_api_key';
const ACCESS_TOKEN = 'your_access_token';
const url = 'https://production.trackstarhq.com/wms/passthrough';
const headers = {
'x-trackstar-api-key': TRACKSTAR_API_KEY,
'x-trackstar-access-token': ACCESS_TOKEN,
'Content-Type': 'application/json'
};
// GraphQL query
const payload = {
method: 'POST',
path: '/graphql',
headers: {
'Content-Type': 'application/json'
},
data: {
query: `
query {
products(first: 10) {
edges {
node {
id
name
sku
}
}
}
}
`
}
};
const response = await axios.post(url, payload, { headers });
// Access the GraphQL response
const graphqlResponse = response.data.body;
console.log(graphqlResponse);
```
```bash cURL theme={null}
curl --request POST \
--url https://production.trackstarhq.com/wms/passthrough \
--header 'x-trackstar-api-key: your_api_key' \
--header 'x-trackstar-access-token: your_access_token' \
--header 'Content-Type: application/json' \
--data '{
"method": "POST",
"path": "/graphql",
"headers": {
"Content-Type": "application/json"
},
"data": {
"query": "query { products(first: 10) { edges { node { id name sku } } } }"
}
}'
```
## Important Notes
Passthrough is currently in beta. If you attempt to use passthrough with an integration that doesn't support it, you will receive a `501` error indicating the endpoint is not implemented.
* **Authentication**: Trackstar automatically handles authentication with the integration. You don't need to include API keys or authentication tokens in your passthrough request.
* **Integration Documentation**: You'll need to refer to the specific integration's API documentation to understand available endpoints, request formats, and response structures.
* **Response Format**: The response body will match the format returned by the integration, not Trackstar's unified format.
* **Rate Limits**: Passthrough requests are subject to both Trackstar's rate limits and the rate limits of the underlying integration.
* **Cart Passthrough**: Cart integrations also support passthrough via `/cart/passthrough` using the same request format shown above.
# Writing Data
Source: https://docs.trackstarhq.com/how-to-guides/programmatic-writes
The Trackstar API enables you to write data into your end users' connected accounts.
We have done the heavy lifting to unify the `body` of each action across integrations, so you can write data in a consistent way across all of them. For each resource, we call this the "Base Schema". See the [Create Order Base Schema](/api-reference/wms-api/orders/post#base-schema) as an example.
However, the required and optional fields may vary depending on the integration you are writing to. Additionally, some integrations may require a field that is unique to them. To handle these cases, we have also included each integration's schema in the reference. See [Extensiv's Create Order Schema](/api-reference/wms-api/orders/post#extensiv-3-pl-central) for an example.
On the API side, we have created an endpoint that will return the required and optional fields for a given entity in a given integration.
## The /integrations endpoint
The [GET integrations](/api-reference/mgmt/integrations) endpoint returns information on our supported integrations. The required, optional, and integration-specific fields for each write operation are returned in the response.
```json theme={null}
{
"data": [
{
"integration_name": "Some WMS",
"write_operations": [
{
"action": "create_order",
"url": "POST /wms/orders",
"required_base_schema_fields": [
"line_items.product_id",
"line_items.quantity"
],
"optional_base_schema_fields": [
"order_number",
"line_items",
"channel",
"trading_partner"
],
"integration_specific_fields": {
"properties": {
"warehouse_id": {
"title": "warehouse_id",
"type": "string",
"description": "The warehouse this order will shipped from.",
"example": "",
"enum": [
"warehouse_1",
"warehouse_2"
]
}
},
"type": "object",
"required_fields": [
"warehouse_id"
]
}
}
],
"available_actions": [
"get_inventory",
"get_products",
"create_order",
]
}
]
}
```
## Example Create Order Request
Based on the response from the `/integrations` endpoint, the required and optional fields to create an order in the `Some WMS` integration are as follows:
| Field | Description | Type | Required |
| ----------------------- | ------------------------------- | ------ | -------- |
| line\_items.product\_id | The product ID of the line item | string | Yes |
| line\_items.quantity | The quantity of the line item | number | Yes |
| order\_number | The order number | string | No |
| line\_items | The line items | array | No |
| channel | The channel | string | No |
| trading\_partner | The trading partner | string | No |
| warehouse\_id | The warehouse ID | string | Yes |
Let's send in all of the fields for this request:
```bash theme={null}
curl -X POST https://production.trackstarhq.com/wms/orders \
-H "x-trackstar-api-key: " \
-H "x-trackstar-access-token: " \
-H "Content-Type: application/json" \
-d '{
"line_items": [
{
"product_id": "123",
"quantity": 2
}
],
"order_number": "1234",
"channel": "Retail",
"trading_partner": "Target",
"warehouse_id": "warehouse_1"
}'
```
And that's it! You have successfully created an order in your end user's connected system.
## Non Nullable Fields
All fields in the write body are **non-nullable**. Put another way, you cannot send a `null` or empty string value for any field. This includes null string literals such as `"null"`, `"none"`, or any similar variation.
For example, `order_number` and `reference_id` are optional fields. Sending in the following request will result in a 422 error response:
```bash theme={null}
curl -X POST https://production.trackstarhq.com/wms/orders \
-H "x-trackstar-api-key: " \
-H "x-trackstar-access-token: " \
-H "Content-Type: application/json" \
-d '{
"order_number": null,
"reference_id": "",
"line_items": [
{
"product_id": "123",
"quantity": 2
}
]
}'
```
Instead, you should omit the fields from the request like so:
```bash theme={null}
curl -X POST https://production.trackstarhq.com/wms/orders \
-H "x-trackstar-api-key: " \
-H "x-trackstar-access-token: " \
-H "Content-Type: application/json" \
-d '{
"line_items": [
{
"product_id": "123",
"quantity": 2
}
]
}'
```
# Sandbox
Source: https://docs.trackstarhq.com/how-to-guides/sandbox
Trackstar provides sandbox environments for testing and development. Each sandbox contains mocked data so you can get familiar with the API and test your integrations without affecting production data.
There are three sandboxes, one for each API vertical:
* **WMS Sandbox** — orders, inventory, products, returns, and more
* **Cart Sandbox** — orders, products, and warehouses
* **Carrier Sandbox** — invoice line items
## 1. Get an API key
You will need an API key to make API calls. See the [Getting Started](/how-to-guides/getting-started#1-get-an-api-key)
page for how to get one.
## 2. Get your Sandbox Access Token
We automatically generate sandbox data for each vertical when you sign up for Trackstar. Navigate to the [connections page](https://dashboard.trackstarhq.com/connections) and
find the connection rows with Integration Name "Sandbox". Click on the key icon to get the access token for the sandbox you want to use.
## 3. Make API calls
Now you can use the API Key and Access Token to make API calls to the sandbox.
```python WMS Sandbox theme={null}
import requests
url = "https://production.trackstarhq.com/wms/inventory"
headers = {
"x-trackstar-api-key": "YOUR_API_KEY",
"x-trackstar-access-token": "YOUR_WMS_SANDBOX_ACCESS_TOKEN"
}
response = requests.get(url, headers=headers)
response.raise_for_status()
data = response.json()
```
```python Cart Sandbox theme={null}
import requests
url = "https://production.trackstarhq.com/cart/orders"
headers = {
"x-trackstar-api-key": "YOUR_API_KEY",
"x-trackstar-access-token": "YOUR_CART_SANDBOX_ACCESS_TOKEN"
}
response = requests.get(url, headers=headers)
response.raise_for_status()
data = response.json()
```
```python Carrier Sandbox 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_CARRIER_SANDBOX_ACCESS_TOKEN"
}
response = requests.get(url, headers=headers)
response.raise_for_status()
data = response.json()
```
You can read the API reference for all supported operations.
## 4. Sandbox Integration in Trackstar Link
You can enable Sandbox integrations in Trackstar Link by setting the `sandbox` prop in the [Trackstar React Component](/how-to-guides/getting-started#4-implement-react-trackstar-link-fe).
If you go through the auth flow for a Sandbox integration, it will return an auth code that you can [exchange for an access token](/api-reference/mgmt/exchange-auth-code).
This is useful for:
1. Testing the end-to-end Trackstar integration flow without needing real integration credentials.
2. Completing the link exchange generates sandbox data and returns an access token that you can use to make API calls to the sandbox. (Like in step 2 above)
## 5. Data Explorer
The Trackstar Dashboard includes a **Data Explorer** that lets you view and edit data directly in the browser. This is available for both sandbox and production connections.
Navigate to the [Data Explorer](https://dashboard.trackstarhq.com/data-explorer) in the dashboard to:
* Browse all resources (orders, inventory, products, etc.) for any connection
* Edit sandbox data to simulate scenarios like fulfilling an order or updating inventory
* View production data to debug issues or verify sync results
* Switch between WMS, Cart, and Carrier tabs and toggle between Sandbox and Production data
All changes made to sandbox data through the Data Explorer will trigger webhooks, so you can test your full integration flow end-to-end.
# Syncing Data
Source: https://docs.trackstarhq.com/how-to-guides/syncing-data
How Trackstar syncs data
Trackstar automatically synchronizes data from your connected integrations at predefined intervals. This ensures that your application consistently accesses the most up-to-date information without the need to manage the complexities of each system's update patterns.
## Default Sync Frequencies
Different data types are synchronized at varying intervals to balance data freshness and system performance. Below is a breakdown of the default synchronization frequencies:
| **API** | **Data Type** | **Sync Frequency** |
| ------- | ------------------- | ------------------ |
| WMS | Inventory | Hourly |
| WMS | Inbound Shipments | Hourly |
| WMS | Orders | Hourly |
| WMS | Products | Hourly |
| WMS | Returns | Hourly |
| WMS | Shipping Methods | Every 12 hours |
| WMS | Warehouses | Every 12 hours |
| WMS | Warehouse Customers | Every 12 hours |
| WMS | Warehouse Locations | Every 12 hours |
| Cart | Orders | Hourly |
| Cart | Products | Hourly |
| Cart | Warehouses | Every 12 hours |
| Carrier | Invoice Line Items | Daily |
> **Note:** These frequencies are default settings and can be customized per connection.
## Initial Sync Behavior
Upon establishing a new connection, Trackstar performs an initial synchronization that retrieves data from the past **30 days** by default. This historical sync ensures that your system starts with a comprehensive dataset.
To adjust the historical lookback window, navigate to your dashboard's [Connections Settings](https://dashboard.trackstarhq.com/settings/connection-settings).
When each data type (e.g. inventory, orders) has finished syncing for the first time, we will send a `connection.historical-sync-completed` event. This indicates data is now available for that data type from our API.
Example:
```json theme={null}
{
"connection_id": "connection_id",
"data": {
"newest_data_date": "2025-05-01T00:00:00Z",
"oldest_data_date": "2025-01-01T00:00:00Z",
"resource": "orders"
},
"event_type": "connection.historical-sync-completed",
"integration_name": "integration_name",
"integration_type": "wms"
}
```
You can also check the sync status of a connection programmatically by calling [`GET /connections/{id}`](/api-reference/mgmt/get-connection).
More information on our webhooks can be found in the [webhooks documentation](https://docs.trackstarhq.com/how-to-guides/webhooks).
## Customizing Sync Frequencies
Sync frequencies can be tailored on a **per-connection basis** to meet specific business requirements. If you need to modify the synchronization interval for a particular data type or connection, please contact our support team for assistance.
## Triggering a Sync
Beyond the scheduled synchronizations, you have the option to manually trigger a sync:
* **Via the Dashboard:** Go to the [Connections Page](https://dashboard.trackstarhq.com/connections), click on the connection you want to sync, press the sync button for the desired data type.
* **Via the API:** Utilize the [POST Sync Connection](https://docs.trackstarhq.com/api-reference/mgmt/sync-connection) endpoint to initiate a sync programmatically. This functionality is particularly useful when immediate data updates are required outside the regular sync schedule. To backfill a specific data type over a custom time window (rather than the default recent-data sync), see [On-Demand Syncs](/how-to-guides/on-demand-syncs).
> **Note:** Manually triggering a sync starts the process right away, but it may take a few minutes for new data to appear as the sync completes in the background.
## Real-Time Writes (POSTs and PUTs)
When you perform a write operation (such as creating or updating a resource via `POST` or `PUT`), Trackstar forwards that request directly to the underlying integration in real time.
We respond immediately with the success or error status from the integration, including any error messages or validation feedback provided by the integration itself. This ensures transparency and helps with rapid debugging and resolution when issues arise.
# Trackstar Link
Source: https://docs.trackstarhq.com/how-to-guides/trackstar-link
Trackstar provides a component to allow your customers to easily and securely connect to any supported integration.
This component can be embedded into your application, or sent as a "Magic Link" to your customers.
## Setting up Trackstar Link
There are two ways to set up Trackstar Link:
1. **Embedding the component**: You can embed the Trackstar Link component into your application.
This is the recommended way to use Trackstar Link, as it provides a seamless experience for your customers.
2. **Sending a Magic Link**: You can send a Magic Link to your customers.
This is useful if you don't have a web application, or if you want to provide a quick way for your customers to connect an integration.
### Embedding the Component
We have published an NPM package to make it easy to embed the Trackstar Link component into your application.
**React**
```bash Yarn theme={null}
yarn add @trackstar/react-trackstar-link
```
```bash NPM theme={null}
npm install @trackstar/react-trackstar-link
```
**Angular**
```bash Yarn theme={null}
yarn add @trackstar/angular-trackstar-link
```
```bash NPM theme={null}
npm install @trackstar/angular-trackstar-link
```
**Vanilla JS**
See example below
Once you have installed the package, you can use the `TrackstarLink` component in your application.
If you are using vanilla Javascript, you can still use the Trackstar Link component by loading the script in your HTML file:
```jsx React theme={null}
import { TrackstarConnectButton } from '@trackstar/react-trackstar-link';
function App() {
const someCustomerId = "12345";
return (
{
// See step 2.1 in How To Guides -> Getting Started
const response = await fetch('https://my-company.backend.com/get-link-token',
{
method: 'POST',
}
);
const { linkToken } = await response.json();
return linkToken;
}}
onSuccess={async (authCode, integrationName) =>
// See step 2.2 in How To Guides -> Getting Started
await fetch('https://my-company.backend.com/store-token',
{
method: 'POST',
body: JSON.stringify({
customer_id: someCustomerId,
auth_code: authCode,
integration_name: integrationName,
}),
}
)
}
onClose={() => console.log('closed')}
onLoad={() => console.log('loaded')}
>
Connect Integration
);
}
```
```javascript Vanilla JS theme={null}
```
#### Multiple Trackstar Buttons
Instead of using a single `TrackstarConnectButton` that opens a modal with a list of integrations, you can use multiple `TrackstarConnectButton` components to connect to specific integrations directly.
1. Set the `integrationAllowList` prop to an array of a single integration ID. This will bypass the integration selection screen.
2. Set the `buttonId` prop to a unique ID. This is required if you have multiple Trackstar Connect buttons on the same page.
For example, the following code will create three buttons that connect to Shiphero, Shipbob, and Deposco respectively:
```jsx theme={null}
import { TrackstarConnectButton } from '@trackstar/react-trackstar-link';
function App() {
const someCustomerId
const integrations = ['shiphero', 'shipbob', 'deposco'];
return (
{integrations.map((integration) => (
Connect to {integration}
))}
);
}
```
#### Available Props
A function that returns a link token. See [Getting a Link Token](/how-to-guides/getting-started/#2-1-get-link-token) for more information.
A function that is called when the customer successfully connects an integration. See [Storing Tokens](/how-to-guides/getting-started/#2-2-store-token) for more information.
A function that is called when the component is closed.
A function that is called when the component is loaded.
Set to true to include a "Sandbox" option in the list of integrations.
The type of integration to show in the list. Can be "wms", "cart", or "carrier". (default: "wms")
Only show the integrations in the list that have the given endpoints supported.
e.g. `integrationsWithEndpoints={['get_returns', 'create_return']}`
will only show the integrations that have the endpoints `get_returns` and `create_return`.
Only show the integrations in the list that are in the allow list.
e.g. `integrationAllowList={['wms1', 'wms2']}`
will only show the integrations that are in the allow list. If only one integration is in the allow list,
the integration selection screen will be bypassed.
**Note**: The list of integrations can be found at the [Integrations API Reference](/api-reference/mgmt/integrations).
Use the `integration_name` field to specify which integrations to show in the list.
Do not show the integrations in the list that are in the block list.
e.g. `integrationBlockList={['wms1', 'wms2']}`
will not show the integrations that are in the block list.
**Note**: The list of integrations can be found at the [Integrations API Reference](/api-reference/mgmt/integrations).
Use the `integration_name` field to specify which integrations to block from the list.
**Note**: `integrationAllowList`, and `integrationBlockList` are mutually exclusive. If both props are given values, all integrations will be displayed.
The URL of a custom logo to display in link modal.
The ID of the button. This is required if you have multiple Trackstar Connect buttons on the same page.
Custom CSS styles to apply to the button.
### Sending a Magic Link
Within the [Trackstar Dashboard](https://dashboard.trackstarhq.com/connections), you can send a Magic Link to your customers. Simply press the "Generate Magic Link" button
to open the Magic Link modal. From here, you can configure the Magic Link, generate a url, and send it to your customer.
Once the customer successfully connects an integration, the connection can be found in the [Connections page](https://dashboard.trackstarhq.com/connections) of the Trackstar Dashboard.
Click on the associated row, then press the "Copy" button to retrieve the permanent access token for the connection.
#### Magic Link Configuration
* **Link Duration**: The duration that the Magic Link is valid for. After this time, the Magic Link will expire and the customer will need to request a new one.
* **Customer ID (Optional)**: The ID of the customer that the Magic Link is for. This is useful for associating the connection with a customer in your system.
* **Connection ID (Optional)**: The ID of the connection that the Magic Link is for. Only pass this in when you want to update the credentials of an existing connection.
* **Endpoints List (Optional)**: Only show integrations that have the selected endpoints supported.
* **Integration Allow List (Optional)**: Only show the integrations that are in the allow list.
* **Integration Block List (Optional)**: Do not show the integrations that are in the block list.
## Custom Branding
You can customize the appearance of the Trackstar Link within the [Trackstar Dashboard](https://dashboard.trackstarhq.com/settings/branding). Here you can set the following:
* **Custom Logo**: The logo that will be displayed in the Trackstar Link modal.
* **Custom Color**: The color of the Trackstar Link button.
# Trackstar Tags
Source: https://docs.trackstarhq.com/how-to-guides/trackstar-tags
Tagging objects in Trackstar
Trackstar allows you to tag objects with custom metadata that isn't synced into the underlying integration. This is useful for
adding fields that don't fit into the integration's schema, or for adding additional context to objects.
Tags are supported across WMS, Cart, and Carrier integrations.
## The Trackstar Tag Object
A tag can be either a string or a dictionary with one key-value pair. e.g.
* A string: `"tag1"`
* A dictionary: `{"tag1": "value1"}`
## Setting Tags
To create a tag, make a `PUT` request to `/{integration_type}/{object_type}/{object_id}/trackstar-tags`. The request body includes a list of tags to add to the object.
*Note, because this is a `PUT` request, the tags will be replaced with the new list.*
### Supported Endpoints
| Integration | Endpoint |
| :---------- | :------------------------------------------------------------------ |
| WMS | `/wms/inventory/{inventory_id}/trackstar-tags` |
| WMS | `/wms/products/{product_id}/trackstar-tags` |
| WMS | `/wms/orders/{order_id}/trackstar-tags` |
| WMS | `/wms/inbound-shipments/{inbound_shipment_id}/trackstar-tags` |
| WMS | `/wms/returns/{return_id}/trackstar-tags` |
| WMS | `/wms/warehouses/{warehouse_id}/trackstar-tags` |
| Cart | `/cart/orders/{order_id}/trackstar-tags` |
| Cart | `/cart/products/{product_id}/trackstar-tags` |
| Cart | `/cart/warehouses/{warehouse_id}/trackstar-tags` |
| Carrier | `/carrier/invoice-line-items/{invoice_line_item_id}/trackstar-tags` |
### Example
```bash cURL theme={null}
curl --request PUT \
--url https://production.trackstarhq.com/cart/orders/{order_id}/trackstar-tags \
--header 'Content-Type: application/json' \
--header 'x-trackstar-access-token: ' \
--header 'x-trackstar-api-key: ' \
--data '{
"trackstar_tags": [
"tag1",
"tag2",
{
"tag3": "value3"
}
]
}'
```
```python Python theme={null}
import requests
url = "https://production.trackstarhq.com/cart/orders/{order_id}/trackstar-tags"
payload = {"trackstar_tags": ["tag1", "tag2", {"tag3": "value3"}]}
headers = {
"x-trackstar-api-key": "",
"x-trackstar-access-token": "",
"Content-Type": "application/json"
}
response = requests.request("PUT", url, json=payload, headers=headers)
```
## Getting Tags
Once you've added tags to an object, they will be returned in the `trackstar_tags` field of the object's response from any `GET` request.
# Connection created
Source: https://docs.trackstarhq.com/how-to-guides/webhooks/admin/connection-created
webhook connection.created
When a Connection is created.
# Connection deleted
Source: https://docs.trackstarhq.com/how-to-guides/webhooks/admin/connection-deleted
webhook connection.deleted
When a Connection is deleted.
# Connection error created
Source: https://docs.trackstarhq.com/how-to-guides/webhooks/admin/connection-error-created
webhook connection-error.created
When a Connection Error is created.
# Connection error deleted
Source: https://docs.trackstarhq.com/how-to-guides/webhooks/admin/connection-error-deleted
webhook connection-error.deleted
When a Connection Error is resolved.
# Connection error updated
Source: https://docs.trackstarhq.com/how-to-guides/webhooks/admin/connection-error-updated
webhook connection-error.updated
When a Connection Error is updated.
# Connection historical sync completed
Source: https://docs.trackstarhq.com/how-to-guides/webhooks/admin/connection-historical-sync
webhook connection.historical-sync-completed
Triggered when historical sync for a resource (orders, inventory, etc.) completes.
# Connection sync job completed
Source: https://docs.trackstarhq.com/how-to-guides/webhooks/admin/connection-sync-job-completed
webhook connection.sync-job-completed
Triggered when a sync job completes for a connection.
# Connection sync job stuck
Source: https://docs.trackstarhq.com/how-to-guides/webhooks/admin/connection-sync-job-stuck
webhook connection.sync-job-stuck
Triggered when Trackstar has determined that a sync job is stuck and will not progress.
# Carrier invoice line item created
Source: https://docs.trackstarhq.com/how-to-guides/webhooks/carrier/carrier-invoice-line-item-created
webhook carrier-invoice-line-item.created
When an Invoice Line Item is created.
# Carrier invoice line item updated
Source: https://docs.trackstarhq.com/how-to-guides/webhooks/carrier/carrier-invoice-line-item-updated
webhook carrier-invoice-line-item.updated
When an Invoice Line Item is updated.
# Cart order created
Source: https://docs.trackstarhq.com/how-to-guides/webhooks/cart/cart-order-created
webhook cart-order.created
When an Order is created.
# Cart order cart shipment created
Source: https://docs.trackstarhq.com/how-to-guides/webhooks/cart/cart-order-shipment-created
webhook cart-order.cart-shipment.created
When a shipment is created for an order
# Cart order updated
Source: https://docs.trackstarhq.com/how-to-guides/webhooks/cart/cart-order-updated
webhook cart-order.updated
When an Order is updated.
# Cart product created
Source: https://docs.trackstarhq.com/how-to-guides/webhooks/cart/cart-product-created
webhook cart-product.created
When a Product is created.
# Cart product updated
Source: https://docs.trackstarhq.com/how-to-guides/webhooks/cart/cart-product-updated
webhook cart-product.updated
When a Product is updated.
# Cart warehouse created
Source: https://docs.trackstarhq.com/how-to-guides/webhooks/cart/cart-warehouse-created
webhook cart-warehouse.created
When a Warehouse is created.
# Cart warehouse updated
Source: https://docs.trackstarhq.com/how-to-guides/webhooks/cart/cart-warehouse-updated
webhook cart-warehouse.updated
When a Warehouse is updated.
# Freight shipment created
Source: https://docs.trackstarhq.com/how-to-guides/webhooks/freight/freight-shipment-created
webhook freight-shipment.created
When a Shipment is created.
# Freight shipment updated
Source: https://docs.trackstarhq.com/how-to-guides/webhooks/freight/freight-shipment-updated
webhook freight-shipment.updated
When a Shipment is updated.
# Webhooks
Source: https://docs.trackstarhq.com/how-to-guides/webhooks/webhooks
Use Trackstar webhooks to be notified when certain events occur. The timing of a webhook event related to a resource (e.g. Orders, Inventory, Products, etc.) will coincide with the [sync frequency](https://docs.trackstarhq.com/how-to-guides/syncing-data#default-sync-frequencies) of that resource.
Resource webhooks (e.g. `order.created`, `inventory.updated`) are **not** sent during a connection's initial sync. They are only sent for changes detected after the initial sync completes.
However, the [`connection.historical-sync-completed`](/how-to-guides/webhooks/admin/connection-historical-sync) webhook **is** sent when the initial sync finishes for each resource type. Use this to know when data is available for querying.
For more information on how initial syncs work, see the [Syncing Data](/how-to-guides/syncing-data#initial-sync-behavior) guide.
Webhooks will point to a specific **URL** that you must set up. This URL must accept `POST` requests with the `Content-Type` set to `application/json`, and can be configured within the [Trackstar Dashboard](https://dashboard.trackstarhq.com/webhooks).
## Webhook Message Schema
| Field | Type | Description |
| --------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `connection_id` | `string` | The ID of the connection from which the event occurred. |
| `data` | `object` | The created or updated object. |
| `event_type` | `string` | The type of event that occurred. See above for the list of types. |
| `integration_name` | `string` | The name of the integration from which the event occurred. |
| `previous_attributes` | `object` | *Only present on updated events.* The previous values of the fields that were updated. If the change occurs within a nested field, we will represent that change via a `"."` joined string where integers represent the index of the array, and strings represent object keys. |
You can find each event's full schema in the subsequent pages in this section.
## Sample Webhook Message
```
{
"connection_id": "connection_id",
"data": {
"created_date": "2022-06-01T00:00:00Z",
"expected_arrival_date": "2022-06-09T00:00:00Z",
"id": "id",
"line_items": [
{
"expected_quantity": 1,
"inventory_item_id": "inventory_item_id_1",
"received_quantity": 1,
"sku": "sku1",
},
{
"expected_quantity": 2,
"inventory_item_id": "inventory_item_id_2",
"received_quantity": 2,
"sku": "sku2",
},
],
"purchase_order_number": "PO#",
"status": "received",
"supplier": "supplier",
"updated_date": "2023-06-14T15:36:48Z",
"warehouse_id": "warehouse_id",
},
"event_type": "inbound_shipment.updated",
"integration_name": "integration_name",
"previous_attributes": {
"status": "open",
"line_items.1.received_quantity": 1
},
}
```
Note: In the example above, `status` changed from "open" to "received" and the `received_quantity` of the second line item changed from 1 to 2.
`line_items.1.received_quantity` is referring to `data.line_items[1].received_quantity`
## Searching & Filtering Webhooks
In addition to filtering webhooks by Event Type, you can also filter by both Connection ID and Resource ID (e.g. the ID of an inventory item) within the "Tags" tab:
You also have the ability to filter by dates. For example, the below will return all webhooks that have been sent within the last week:
Which can be combined with a before date filter to further narrow the results:
**Note:** Filters are persistent when switching tabs in the filtering menu, meaning you have to manually clear or change them when jumping between tabs if you want different results.
## Verifying Webhook Signatures
Trackstar uses SVIX as its webhook provider. Information on how to verify the webhook signature can be found in the [SVIX documentation](https://docs.svix.com/receiving/verifying-payloads/how-manual).
## Webhook Transformations
Webhook transformations allow you to modify webhook properties in real-time using JavaScript before they are sent to your endpoint. You can change the target URL, modify the payload, or even cancel webhook delivery based on custom logic.
### Separating Test and Production Environments
A common use case for transformations is routing webhooks to different endpoints based on the environment. Since Trackstar doesn't currently have separate test and production webhook environments, you can use transformations to route webhooks to different URLs based on attributes in the webhook payload.
For example, you might want to:
* Send webhooks from test connections to a staging/test endpoint
* Send webhooks from production connections to your production endpoint
You can accomplish this by writing a transformation that checks the `connection_id` and routes webhooks accordingly.
### Example: Routing by Connection ID
Here's a practical example that routes webhooks to different URLs based on whether the connection is a test or production connection:
```javascript theme={null}
function handler(webhook) {
// Define your test and production connection IDs
const testConnectionIds = [
"conn_test_abc123",
"conn_test_def456",
"conn_test_ghi789"
];
// Check if this webhook is from a test connection
const isTestConnection = testConnectionIds.includes(webhook.payload.connection_id);
// Route to the appropriate endpoint
if (isTestConnection) {
webhook.url = "https://your-app.com/webhooks/test";
} else {
webhook.url = "https://your-app.com/webhooks/production";
}
return webhook;
}
```
### Example: Routing by Customer ID
If you don't want to keep track of a list of static connection IDs, you can also prefix the customer ID on your test connections with something like `uat` and filter based on that field:
```javascript theme={null}
function handler(webhook) {
// Define your test customer ID prefix
const testCustomerIdPrefix = "uat";
// Check if this webhook is from a test connection
const isTestConnection = webhook.payload.customer_id.startsWith(testCustomerIdPrefix);
// Route to the appropriate endpoint
if (isTestConnection) {
webhook.url = "https://your-app.com/webhooks/test";
} else {
webhook.url = "https://your-app.com/webhooks/production";
}
return webhook;
}
```
### Example: Routing by Integration Name
You can also route based on the integration name if you want to handle certain integrations differently:
```javascript theme={null}
function handler(webhook) {
const sandboxIntegrations = ["Sandbox"];
// Check if this is from a sandbox/test integration
const isSandboxIntegration = sandboxIntegrations.includes(webhook.payload.integration_name);
if (isSandboxIntegration) {
webhook.url = "https://your-app.com/webhooks/test";
} else {
webhook.url = "https://your-app.com/webhooks/production";
}
return webhook;
}
```
### Setting Up Transformations
To configure webhook transformations:
1. Navigate to the [Trackstar Dashboard](https://dashboard.trackstarhq.com/webhooks)
2. Click on your webhook endpoint to view its settings
3. Go to the "Advanced" tab
4. Locate the "Transformations" card
5. Enable transformations and paste your custom JavaScript code
6. Save your changes
For more information on webhook transformations, including additional examples and advanced usage, see the [Svix Transformations documentation](https://docs.svix.com/transformations).
# Bill created
Source: https://docs.trackstarhq.com/how-to-guides/webhooks/wms/bill-created
webhook bill.created
When a Bill is created.
# Bill updated
Source: https://docs.trackstarhq.com/how-to-guides/webhooks/wms/bill-updated
webhook bill.updated
When a Bill is updated.
# Inbound shipment created
Source: https://docs.trackstarhq.com/how-to-guides/webhooks/wms/inbound-shipment-created
webhook inbound-shipment.created
When an Inbound Shipment is created.
# Inbound shipment receipt created
Source: https://docs.trackstarhq.com/how-to-guides/webhooks/wms/inbound-shipment-receipt-created
webhook inbound-shipment.receipt.created
When a receipt is created for the inbound shipment.
# Inbound shipment updated
Source: https://docs.trackstarhq.com/how-to-guides/webhooks/wms/inbound-shipment-updated
webhook inbound-shipment.updated
When an Inbound Shipment is updated.
# Inventory created
Source: https://docs.trackstarhq.com/how-to-guides/webhooks/wms/inventory-created
webhook inventory.created
When an Inventory Item is created.
# Inventory_ledger created
Source: https://docs.trackstarhq.com/how-to-guides/webhooks/wms/inventory-ledger-created
webhook inventory_ledger.created
When an Inventory Ledger is created.
# Inventory_ledger updated
Source: https://docs.trackstarhq.com/how-to-guides/webhooks/wms/inventory-ledger-updated
webhook inventory_ledger.updated
When an Inventory Ledger is updated.
# Inventory updated
Source: https://docs.trackstarhq.com/how-to-guides/webhooks/wms/inventory-updated
webhook inventory.updated
When an Inventory Item is updated.
# Order created
Source: https://docs.trackstarhq.com/how-to-guides/webhooks/wms/order-created
webhook order.created
When an Order is created.
# Order shipment created
Source: https://docs.trackstarhq.com/how-to-guides/webhooks/wms/order-shipment-created
webhook order.shipment.created
When a shipment is created for an order
# Order updated
Source: https://docs.trackstarhq.com/how-to-guides/webhooks/wms/order-updated
webhook order.updated
When an Order is updated.
# Product created
Source: https://docs.trackstarhq.com/how-to-guides/webhooks/wms/product-created
webhook product.created
When a Kit is created.
# Product updated
Source: https://docs.trackstarhq.com/how-to-guides/webhooks/wms/product-updated
webhook product.updated
When a Kit is updated.
# Return created
Source: https://docs.trackstarhq.com/how-to-guides/webhooks/wms/return-created
webhook return.created
When a Return is created.
# Return updated
Source: https://docs.trackstarhq.com/how-to-guides/webhooks/wms/return-updated
webhook return.updated
When a Return is updated.
# Shipping method created
Source: https://docs.trackstarhq.com/how-to-guides/webhooks/wms/shipping-method-created
webhook shipping-method.created
When a Shipping Method is created.
# Shipping method updated
Source: https://docs.trackstarhq.com/how-to-guides/webhooks/wms/shipping-method-updated
webhook shipping-method.updated
When a Shipping Method is updated.
# Warehouse created
Source: https://docs.trackstarhq.com/how-to-guides/webhooks/wms/warehouse-created
webhook warehouse.created
When a Warehouse is created.
# Warehouse customer created
Source: https://docs.trackstarhq.com/how-to-guides/webhooks/wms/warehouse-customer-created
webhook warehouse-customer.created
When a Warehouse Customer is created.
# Warehouse customer updated
Source: https://docs.trackstarhq.com/how-to-guides/webhooks/wms/warehouse-customer-updated
webhook warehouse-customer.updated
When a Warehouse Customer is updated.
# Warehouse location created
Source: https://docs.trackstarhq.com/how-to-guides/webhooks/wms/warehouse-location-created
webhook warehouse-location.created
When a Warehouse Location is created.
# Warehouse location updated
Source: https://docs.trackstarhq.com/how-to-guides/webhooks/wms/warehouse-location-updated
webhook warehouse-location.updated
When a Warehouse Location is updated.
# Warehouse updated
Source: https://docs.trackstarhq.com/how-to-guides/webhooks/wms/warehouse-updated
webhook warehouse.updated
When a Warehouse is updated.
# Welcome to Trackstar!
Source: https://docs.trackstarhq.com/introduction
Thank you for your interest in Trackstar! If you have any questions, don't hesitate to reach out to `support@trackstarhq.com`. Access to the API can be requested via [our website](https://trackstarhq.com).
### What is Trackstar?
Trackstar is a Unified API for Supply Chain Logistics.
We currently offer APIs for Warehouse Management Systems (WMS), Carts, and Carriers.
Integrate once with Trackstar, and you automatically get access to all of our supported integrations — no need to build and maintain individual connections to each system.
We provide a drop-in frontend authentication component that makes it easy to connect to your customers' end systems.
### How It Works
Your customer connects their system (WMS, Cart, or Carrier) via [Trackstar Link](/how-to-guides/trackstar-link), a [Magic Link](/how-to-guides/trackstar-link#sending-a-magic-link), or the [dashboard](https://dashboard.trackstarhq.com/connections). Each connection produces an **access token**.
Trackstar automatically syncs data from the connected system on a recurring schedule. An [initial sync](/how-to-guides/syncing-data#initial-sync-behavior) pulls historical data, and ongoing syncs keep everything up to date.
Use the access token to read and write data through Trackstar's unified API. The same endpoints work across all integrations within a vertical.
Set up Trackstar and make your first API call.
### Use Cases
#### WMS API
Create orders and track fulfillments.
Keep stock in check.
Fulfill orders with tracking information.
Create RMAs and track disposition data.
Notify warehouses of incoming goods and track receipts.
#### Cart API
Sync products, pull orders, and push back shipment and inventory updates.
#### Carrier API
Retrieve invoice line items as JSON or download raw invoice files.
### About Our Endpoints
The Trackstar API can be queried via HTTP REST endpoints. We follow standard HTTP authentication, response codes, and verbs.
Our API accepts JSON-encoded requests which are all documented here. All of our responses are returned as JSON.
All requests must be made via `https` and all requests should be made to `https://production.trackstarhq.com/`
### Supported integrations
The up-to-date list of supported integrations can be found [here](https://www.trackstarhq.com/integrations).
You can subscribe to an RSS Feed to get notified of new integrations as they are added to the platform. The feed is available at [http://www.trackstarhq.com/integrations/rss.xml](http://www.trackstarhq.com/integrations/rss.xml).
# Carrier Invoice Data
Source: https://docs.trackstarhq.com/use-cases/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.
```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}`);
}
```
### 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.
```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);
}
```
### 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:
```bash theme={null}
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"
```
You can also filter by `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 |
# Cart Order Fulfillment
Source: https://docs.trackstarhq.com/use-cases/cart-order-fulfillment
Sync products, pull orders, create shipments, and adjust inventory using the Cart API
This guide covers the end-to-end workflow for managing orders from cart platforms (e.g. Shopify, Amazon, Etsy) using the Trackstar Cart API.
## Overview
The cart order fulfillment workflow typically involves:
1. Syncing your product catalog
2. Pulling in orders as they arrive
3. Pushing back shipment and tracking information after fulfillment
4. Adjusting inventory levels in the cart platform
## 1. Sync Products
Use the [Get Products endpoint](/api-reference/cart-api/products/get) to pull the product catalog from your customer's cart platform.
Every variant and parent product are listed in this endpoint. A variant will have a `parent_product_id` pointing to its parent. Parent products are indicated by having their `parent_product_id` set to the same value as their `id`. The source of truth for price and inventory levels is on the variants, not the parent product.
```bash cURL theme={null}
curl -X GET https://production.trackstarhq.com/cart/products \
-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/cart/products"
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 product in data["data"]:
is_variant = product["parent_product_id"] != product["id"]
print(f"{product['name']} (SKU: {product['sku']}, variant: {is_variant})")
```
```javascript JavaScript theme={null}
const url = "https://production.trackstarhq.com/cart/products";
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 product of data) {
const isVariant = product.parent_product_id !== product.id;
console.log(`${product.name} (SKU: ${product.sku}, variant: ${isVariant})`);
}
```
## 2. Pull Orders
Use the [Get Orders endpoint](/api-reference/cart-api/orders/get) to pull orders as they come in. You can filter by date to get only recent orders.
For real-time notifications, subscribe to the `cart-order.created` [webhook](/how-to-guides/webhooks) event.
```bash cURL theme={null}
curl -X GET "https://production.trackstarhq.com/cart/orders?created_date[gte]=2026-04-01T00:00:00Z" \
-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/cart/orders"
headers = {
"x-trackstar-api-key": "YOUR_API_KEY",
"x-trackstar-access-token": "YOUR_ACCESS_TOKEN"
}
params = {
"created_date[gte]": "2026-04-01T00:00:00Z"
}
response = requests.get(url, headers=headers, params=params)
orders = response.json()
```
```javascript JavaScript theme={null}
const url = "https://production.trackstarhq.com/cart/orders?created_date[gte]=2026-04-01T00:00:00Z";
const response = await fetch(url, {
headers: {
"x-trackstar-api-key": "YOUR_API_KEY",
"x-trackstar-access-token": "YOUR_ACCESS_TOKEN"
}
});
const orders = await response.json();
```
### Order Statuses
| Status | Definition |
| :-------------------- | :-------------------------------------------------- |
| `open` | Order has been placed. |
| `confirmed` | Order has been confirmed by the cart system. |
| `processing` | Order is being processed by the warehouse. |
| `partially_fulfilled` | Order has been partially fulfilled. |
| `fulfilled` | Order has been fulfilled and shipped. |
| `backordered` | Order cannot be fulfilled due to lack of inventory. |
| `exception` | There is an issue with the order. |
| `cancelled` | Order has been cancelled. |
## 3. Create Order Shipment
After fulfilling an order, use the [Create Shipment endpoint](/api-reference/cart-api/orders/create-shipment) to push tracking information back to the cart platform.
```bash cURL theme={null}
curl -X POST https://production.trackstarhq.com/cart/orders/ORDER_ID/shipments \
-H "Content-Type: application/json" \
-H "x-trackstar-api-key: YOUR_API_KEY" \
-H "x-trackstar-access-token: YOUR_ACCESS_TOKEN" \
-d '{
"tracking_number": "1Z999AA1234567890",
"tracking_url": "https://www.fedex.com/apps/fedextrack/?tracknumbers=1Z999AA1234567890",
"carrier_name": "FedEx",
"shipping_method_name": "FedEx Ground"
}'
```
```python Python theme={null}
import requests
url = "https://production.trackstarhq.com/cart/orders/ORDER_ID/shipments"
headers = {
"Content-Type": "application/json",
"x-trackstar-api-key": "YOUR_API_KEY",
"x-trackstar-access-token": "YOUR_ACCESS_TOKEN"
}
payload = {
"tracking_number": "1Z999AA1234567890",
"tracking_url": "https://www.fedex.com/apps/fedextrack/?tracknumbers=1Z999AA1234567890",
"carrier_name": "FedEx",
"shipping_method_name": "FedEx Ground"
}
response = requests.post(url, headers=headers, json=payload)
print(response.json())
```
```javascript JavaScript theme={null}
const url = "https://production.trackstarhq.com/cart/orders/ORDER_ID/shipments";
const response = await fetch(url, {
method: "POST",
headers: {
"Content-Type": "application/json",
"x-trackstar-api-key": "YOUR_API_KEY",
"x-trackstar-access-token": "YOUR_ACCESS_TOKEN"
},
body: JSON.stringify({
tracking_number: "1Z999AA1234567890",
tracking_url: "https://www.fedex.com/apps/fedextrack/?tracknumbers=1Z999AA1234567890",
carrier_name: "FedEx",
shipping_method_name: "FedEx Ground"
})
});
const data = await response.json();
console.log(data);
```
## 4. Adjust Inventory
Use the [Adjust Inventory endpoint](/api-reference/cart-api/products/adjust) to update inventory levels in the cart platform. This is useful for syncing stock changes that happen outside the cart (e.g. warehouse adjustments, returns processing).
The `adjustment_type` field controls how the `quantity` value is applied:
* `"increase"` — add to the current stock level
* `"decrease"` — subtract from the current stock level
* `"exact"` — set the stock level to this exact quantity
Inventory can only be adjusted on variant products, not parent products. Use the `parent_product_id` field to identify variants (see Step 1).
```bash cURL theme={null}
curl -X PUT https://production.trackstarhq.com/cart/products/PRODUCT_ID/adjust-inventory \
-H "Content-Type: application/json" \
-H "x-trackstar-api-key: YOUR_API_KEY" \
-H "x-trackstar-access-token: YOUR_ACCESS_TOKEN" \
-d '{
"quantity": 50,
"adjustment_type": "exact",
"warehouse_id": "warehouse_main"
}'
```
```python Python theme={null}
import requests
url = "https://production.trackstarhq.com/cart/products/PRODUCT_ID/adjust-inventory"
headers = {
"Content-Type": "application/json",
"x-trackstar-api-key": "YOUR_API_KEY",
"x-trackstar-access-token": "YOUR_ACCESS_TOKEN"
}
payload = {
"quantity": 50,
"adjustment_type": "exact",
"warehouse_id": "warehouse_main"
}
response = requests.put(url, headers=headers, json=payload)
print(response.json())
```
```javascript JavaScript theme={null}
const url = "https://production.trackstarhq.com/cart/products/PRODUCT_ID/adjust-inventory";
const response = await fetch(url, {
method: "PUT",
headers: {
"Content-Type": "application/json",
"x-trackstar-api-key": "YOUR_API_KEY",
"x-trackstar-access-token": "YOUR_ACCESS_TOKEN"
},
body: JSON.stringify({
quantity: 50,
adjustment_type: "exact",
warehouse_id: "warehouse_main"
})
});
const data = await response.json();
console.log(data);
```
## Real-Time Updates
Use [webhooks](/how-to-guides/webhooks) to get notified in real time:
| Event | Description |
| :---------------------------- | :--------------------------------------------------- |
| `cart-order.created` | A new order has been placed. |
| `cart-order.updated` | An order has been updated (status change, etc.). |
| `cart-order.shipment.created` | A shipment has been created for an order. |
| `cart-product.created` | A new product has been added to the catalog. |
| `cart-product.updated` | A product has been updated (price, inventory, etc.). |
# Inventory Management
Source: https://docs.trackstarhq.com/use-cases/inventory-management
Learn how to track stock levels using the Trackstar API
Effective inventory management is crucial for maintaining optimal stock levels and preventing stockouts or overstock situations. This guide shows you how to fetch inventory data and make adjustments using the Trackstar API.
## Overview
The inventory management workflow typically involves:
1. Fetching current stock levels across warehouses
2. Monitoring inventory changes and levels
3. Map between products and associated inventory items
## Getting Inventory Data
Use the [Get Inventory endpoint](/api-reference/wms-api/inventory/get) to retrieve current stock levels across all locations.
### Fetching All Inventory
```bash cURL theme={null}
curl -X GET https://production.trackstarhq.com/wms/inventory \
-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/wms/inventory"
headers = {
"x-trackstar-api-key": "YOUR_API_KEY",
"x-trackstar-access-token": "YOUR_ACCESS_TOKEN",
}
response = requests.get(url, headers=headers)
print(response.json())
```
```javascript JavaScript theme={null}
const url = "https://production.trackstarhq.com/wms/inventory";
fetch(url, {
method: "GET",
headers: {
"x-trackstar-api-key": "YOUR_API_KEY",
"x-trackstar-access-token": "YOUR_ACCESS_TOKEN"
}
})
.then(response => response.json())
.then(data => console.log(data));
```
```php PHP theme={null}
[
"header" =>
"x-trackstar-api-key: YOUR_API_KEY\r\n" .
"x-trackstar-access-token: YOUR_ACCESS_TOKEN\r\n",
"method" => "GET"
]
];
$context = stream_context_create($options);
$response = file_get_contents($url, false, $context);
echo $response;
?>
```
```go Go theme={null}
package main
import (
"fmt"
"io"
"net/http"
)
func main() {
url := "https://production.trackstarhq.com/wms/inventory"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Set("x-trackstar-api-key", "YOUR_API_KEY")
req.Header.Set("x-trackstar-access-token", "YOUR_ACCESS_TOKEN")
client := &http.Client{}
resp, err := client.Do(req)
if err != nil {
panic(err)
}
defer resp.Body.Close()
body, _ := io.ReadAll(resp.Body)
fmt.Println(string(body))
}
```
```java Java theme={null}
import java.io.IOException;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
public class TrackstarGetInventoryExample {
public static void main(String[] args) throws IOException, InterruptedException {
String url = "https://production.trackstarhq.com/wms/inventory";
HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create(url))
.header("x-trackstar-api-key", "YOUR_API_KEY")
.header("x-trackstar-access-token", "YOUR_ACCESS_TOKEN")
.GET()
.build();
HttpResponse response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println("Status: " + response.statusCode());
System.out.println("Body: " + response.body());
}
}
```
```ruby Ruby theme={null}
require 'net/http'
require 'uri'
url = URI('https://production.trackstarhq.com/wms/inventory')
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request['x-trackstar-api-key'] = 'YOUR_API_KEY'
request['x-trackstar-access-token'] = 'YOUR_ACCESS_TOKEN'
response = http.request(request)
puts "Status: #{response.code}"
puts "Response: #{response.body}"
```
### Sample Response
```json theme={null}
{
"data": [
{
"id": "inv_widget001_main",
"warehouse_customer_id": "customer_12345",
"created_date": "2024-01-15T10:00:00Z",
"updated_date": "2024-01-20T14:30:00Z",
"name": "Premium Widget",
"sku": "WIDGET-001",
"unit_cost": 25.00,
"active": true,
"awaiting": 100,
"onhand": 150,
"committed": 25,
"unfulfillable": 5,
"fulfillable": 120,
"unsellable": 0,
"sellable": 150,
"substitute_skus": [],
"inventory_by_warehouse_id": {
"warehouse_main": {
"onhand": 100,
"committed": 15,
"unfulfillable": 3,
"fulfillable": 82,
"unsellable": 0,
"sellable": 100,
"awaiting": 50
},
"warehouse_east": {
"onhand": 50,
"committed": 10,
"unfulfillable": 2,
"fulfillable": 38,
"unsellable": 0,
"sellable": 50,
"awaiting": 50
}
},
"lots": [
{
"lot_id": "LOT-W001-240115",
"onhand": 75,
"expiration_date": "2025-01-15"
}
],
"locations": [
{
"location_id": "A-01-15-02",
"warehouse_id": "warehouse_main",
"quantity": 75
},
{
"location_id": "B-02-08-01",
"warehouse_id": "warehouse_main",
"quantity": 25
}
],
"trackstar_tags": ["high-priority", {"category": "fast-mover"}],
"external_system_url": "https://wms.example.com/inventory/inv_widget001_main",
"additional_fields": {
"custom_field_1": "value1",
"warehouse_notes": "Premium product location"
},
"measurements": {
"length": 12.5,
"width": 8.0,
"height": 4.2,
"unit": "in",
"weight": 2.3,
"weight_unit": "lb"
}
},
{
"id": "inv_gadget002_main",
"warehouse_customer_id": "customer_12345",
"created_date": "2024-01-10T09:00:00Z",
"updated_date": "2024-01-18T16:45:00Z",
"name": "Smart Gadget",
"sku": "GADGET-002",
"unit_cost": 45.00,
"active": true,
"awaiting": 25,
"onhand": 75,
"committed": 10,
"unfulfillable": 0,
"fulfillable": 65,
"unsellable": 0,
"sellable": 75,
"substitute_skus": ["GADGET-002A"],
"inventory_by_warehouse_id": {
"warehouse_main": {
"onhand": 75,
"committed": 10,
"unfulfillable": 0,
"fulfillable": 65,
"unsellable": 0,
"sellable": 75,
"awaiting": 25
}
},
"lots": [],
"locations": [
{
"location_id": "C-03-12-01",
"warehouse_id": "warehouse_main",
"quantity": 75
}
],
"trackstar_tags": ["smart-device"],
"external_system_url": "https://wms.example.com/inventory/inv_gadget002_main",
"additional_fields": {
"electronics_category": "consumer",
"warehouse_notes": "Electronics section"
},
"measurements": {
"length": 6.8,
"width": 3.4,
"height": 1.8,
"unit": "in",
"weight": 0.8,
"weight_unit": "lb"
}
}
],
"next_token": null,
"total_count": 2
}
```
## Understanding Inventory Levels
For detailed information about inventory breakdowns, see the [Inventory Info page](/api-reference/wms-api/inventory/info).
## Multi-Location Inventory
Trackstar tracks inventory across multiple warehouses and specific locations within each warehouse.
### Warehouse-Level Inventory
Each inventory item shows totals by warehouse:
```json theme={null}
{
"inventory_by_warehouse_id": {
"warehouse_main": {
"onhand": 100,
"committed": 15,
"fulfillable": 85
},
"warehouse_east": {
"onhand": 50,
"committed": 10,
"fulfillable": 40
}
}
}
```
### Location-Level Details
Specific storage locations within warehouses:
```json theme={null}
{
"locations": [
{
"location_id": "A-01-15-02",
"warehouse_id": "warehouse_main",
"quantity": 75
},
{
"location_id": "B-02-08-01",
"warehouse_id": "warehouse_main",
"quantity": 25
}
]
}
```
## Mapping Products to Inventory Items
Products and inventory items have a many-to-many relationship in Trackstar. A single product (identified by SKU) can map to multiple inventory items across different warehouses. To accurately get inventory levels for a product, you need to first fetch the product to get its associated inventory items.
### Fetching Product Information
Use the [Get Product endpoint](/api-reference/wms-api/products/get-item) to retrieve a specific product and its inventory item mappings.
```bash cURL theme={null}
curl -X GET https://production.trackstarhq.com/wms/products/prod_widget_001 \
-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/wms/products/prod_widget_001"
headers = {
"x-trackstar-api-key": "YOUR_API_KEY",
"x-trackstar-access-token": "YOUR_ACCESS_TOKEN"
}
response = requests.get(url, headers=headers)
print(response.json())
```
```javascript JavaScript theme={null}
const url = "https://production.trackstarhq.com/wms/products/prod_widget_001";
fetch(url, {
method: "GET",
headers: {
"x-trackstar-api-key": "YOUR_API_KEY",
"x-trackstar-access-token": "YOUR_ACCESS_TOKEN"
}
})
.then(response => response.json())
.then(data => console.log(data));
```
```php PHP theme={null}
[
"header" =>
"x-trackstar-api-key: YOUR_API_KEY\r\n" .
"x-trackstar-access-token: YOUR_ACCESS_TOKEN\r\n",
"method" => "GET"
]
];
$context = stream_context_create($options);
$response = file_get_contents($url, false, $context);
echo $response;
?>
```
```go Go theme={null}
package main
import (
"fmt"
"io"
"net/http"
)
func main() {
url := "https://production.trackstarhq.com/wms/products/prod_widget_001"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Set("x-trackstar-api-key", "YOUR_API_KEY")
req.Header.Set("x-trackstar-access-token", "YOUR_ACCESS_TOKEN")
client := &http.Client{}
resp, err := client.Do(req)
if err != nil {
panic(err)
}
defer resp.Body.Close()
body, _ := io.ReadAll(resp.Body)
fmt.Println(string(body))
}
```
```java Java theme={null}
import java.io.IOException;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
public class TrackstarGetProductExample {
public static void main(String[] args) throws IOException, InterruptedException {
String url = "https://production.trackstarhq.com/wms/products/prod_widget_001";
HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create(url))
.header("x-trackstar-api-key", "YOUR_API_KEY")
.header("x-trackstar-access-token", "YOUR_ACCESS_TOKEN")
.GET()
.build();
HttpResponse response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println("Status: " + response.statusCode());
System.out.println("Body: " + response.body());
}
}
```
```ruby Ruby theme={null}
require 'net/http'
require 'uri'
url = URI('https://production.trackstarhq.com/wms/products/prod_widget_001')
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request['x-trackstar-api-key'] = 'YOUR_API_KEY'
request['x-trackstar-access-token'] = 'YOUR_ACCESS_TOKEN'
response = http.request(request)
puts "Status: #{response.code}"
puts "Response: #{response.body}"
```
### Sample Product Response
```json theme={null}
{
"data": {
"id": "prod_widget_001",
"warehouse_customer_id": "customer_12345",
"created_date": "2024-01-01T00:00:00Z",
"updated_date": "2024-01-15T10:30:00Z",
"name": "Premium Widget",
"sku": "WIDGET-001",
"gtin": "1234567890123",
"unit_price": 29.99,
"inventory_items": [
{
"inventory_item_id": "inv_widget001_main",
"sku": "WIDGET-001",
"unit_quantity": 1
},
{
"inventory_item_id": "inv_widget001_east",
"sku": "WIDGET-001",
"unit_quantity": 1
}
],
"is_kit": false,
"active": true,
"supplier": "ACME Suppliers",
"supplier_object": {
"supplier_id": "ACME001",
"supplier_name": "ACME Suppliers Inc"
},
"country_of_origin": "US",
"harmonized_code": "9999999999",
"supplier_products": [
{
"supplier_id": "ACME001",
"supplier_name": "ACME Suppliers Inc",
"external_id": "ACME-WIDGET-001",
"unit_cost": "25.00"
}
],
"trackstar_tags": ["premium", {"priority": "high"}],
"external_system_url": "https://wms.example.com/products/prod_widget_001",
"additional_fields": {
"product_category": "widgets",
"marketing_description": "Our best-selling premium widget"
}
}
}
```
### Getting Inventory Levels for Products
Once you have the `inventory_item_id` values from the product response, use the [Get Inventory endpoint](/api-reference/wms-api/inventory/get) to retrieve current stock levels. The `inventory_item_id` from the product endpoint maps directly to the `id` field in the inventory endpoint.
```bash cURL theme={null}
curl -X GET https://production.trackstarhq.com/wms/inventory/inv_widget001_main \
-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/wms/inventory/inv_widget001_main"
headers = {
"x-trackstar-api-key": "YOUR_API_KEY",
"x-trackstar-access-token": "YOUR_ACCESS_TOKEN",
}
response = requests.get(url, headers=headers)
print(response.json())
```
```javascript JavaScript theme={null}
const url = "https://production.trackstarhq.com/wms/inventory/inv_widget001_main";
fetch(url, {
method: "GET",
headers: {
"x-trackstar-api-key": "YOUR_API_KEY",
"x-trackstar-access-token": "YOUR_ACCESS_TOKEN"
}
})
.then(response => response.json())
.then(data => console.log(data));
```
```php PHP theme={null}
[
"header" =>
"x-trackstar-api-key: YOUR_API_KEY\r\n" .
"x-trackstar-access-token: YOUR_ACCESS_TOKEN\r\n",
"method" => "GET"
]
];
$context = stream_context_create($options);
$response = file_get_contents($url, false, $context);
echo $response;
?>
```
```go Go theme={null}
package main
import (
"fmt"
"io"
"net/http"
)
func main() {
url := "https://production.trackstarhq.com/wms/inventory/inv_widget001_main"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Set("x-trackstar-api-key", "YOUR_API_KEY")
req.Header.Set("x-trackstar-access-token", "YOUR_ACCESS_TOKEN")
client := &http.Client{}
resp, err := client.Do(req)
if err != nil {
panic(err)
}
defer resp.Body.Close()
body, _ := io.ReadAll(resp.Body)
fmt.Println(string(body))
}
```
```java Java theme={null}
import java.io.IOException;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
public class TrackstarGetInventoryItemExample {
public static void main(String[] args) throws IOException, InterruptedException {
String url = "https://production.trackstarhq.com/wms/inventory/inv_widget001_main";
HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create(url))
.header("x-trackstar-api-key", "YOUR_API_KEY")
.header("x-trackstar-access-token", "YOUR_ACCESS_TOKEN")
.GET()
.build();
HttpResponse response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println("Status: " + response.statusCode());
System.out.println("Body: " + response.body());
}
}
```
```ruby Ruby theme={null}
require 'net/http'
require 'uri'
url = URI('https://production.trackstarhq.com/wms/inventory/inv_widget001_main')
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request['x-trackstar-api-key'] = 'YOUR_API_KEY'
request['x-trackstar-access-token'] = 'YOUR_ACCESS_TOKEN'
response = http.request(request)
puts "Status: #{response.code}"
puts "Response: #{response.body}"
```
### Sample Inventory Item Response
```json theme={null}
{
"data": {
"id": "inv_widget001_main",
"warehouse_customer_id": "customer_12345",
"created_date": "2024-01-15T10:00:00Z",
"updated_date": "2024-01-20T14:30:00Z",
"name": "Premium Widget",
"sku": "WIDGET-001",
"unit_cost": 25.00,
"active": true,
"awaiting": 50,
"onhand": 100,
"committed": 15,
"unfulfillable": 3,
"fulfillable": 82,
"unsellable": 0,
"sellable": 100,
"substitute_skus": [],
"inventory_by_warehouse_id": {
"warehouse_main": {
"onhand": 100,
"committed": 15,
"unfulfillable": 3,
"fulfillable": 82,
"unsellable": 0,
"sellable": 100,
"awaiting": 50
}
},
"lots": [
{
"lot_id": "LOT-W001-240115",
"onhand": 75,
"expiration_date": "2025-01-15"
}
],
"locations": [
{
"location_id": "A-01-15-02",
"warehouse_id": "warehouse_main",
"quantity": 75
},
{
"location_id": "B-02-08-01",
"warehouse_id": "warehouse_main",
"quantity": 25
}
],
"trackstar_tags": ["high-priority", {"category": "fast-mover"}],
"external_system_url": "https://wms.example.com/inventory/inv_widget001_main",
"additional_fields": {
"custom_field_1": "value1",
"warehouse_notes": "Premium product location"
},
"measurements": {
"length": 12.5,
"width": 8.0,
"height": 4.2,
"unit": "in",
"weight": 2.3,
"weight_unit": "lb"
}
}
}
```
### Complete Product-to-Inventory Workflow
1. **Fetch the product** using the [Get Product endpoint](/api-reference/wms-api/products/get-item)
2. **Extract inventory item IDs** from the `inventory_items` array
3. **Fetch inventory levels** for each `inventory_item_id` using the [Get Inventory Item endpoint](/api-reference/wms-api/inventory/get-item)
# Order Fulfillment
Source: https://docs.trackstarhq.com/use-cases/order-fulfillment
Learn how to create orders and track fulfillments using the Trackstar API
Order fulfillment is a core workflow in warehouse management systems. This guide shows you how to create orders and track their progress through the fulfillment process.
## Overview
The order fulfillment process typically involves:
1. Creating an order with product details
2. Tracking order status through the fulfillment pipeline
3. Syncing updates and managing order data
## Creating Orders
To create an order, use the [Create Order endpoint](/api-reference/wms-api/orders/post) with the required order information including products, quantities, and shipping details.
For a full list of fields that need to be passed in, see the [Programmatic Writes guide](/how-to-guides/programmatic-writes).
### Create the Order
```bash cURL theme={null}
curl -X POST https://production.trackstarhq.com/wms/orders \
-H "Content-Type: application/json" \
-H "x-trackstar-api-key: YOUR_API_KEY" \
-H "x-trackstar-access-token: YOUR_ACCESS_TOKEN" \
-d '{
"warehouse_customer_id": "customer_12345",
"reference_id": "order_2024_001",
"order_number": "ORD-001",
"channel_object": {
"channel_id": "Online Store",
"channel_name": "shopify"
},
"trading_partner": "Direct",
"shipping_method_id": "1234",
"shipping_method": "fedex_ground",
"service_level": "Standard",
"total_price": 79.98,
"total_tax": 6.40,
"ship_to_address": {
"name": "John Doe",
"company": null,
"address1": "123 Main St",
"address2": "Apt 4B",
"city": "Anytown",
"state": "NY",
"zip_code": "12345",
"country": "US",
"phone_number": "+1234567890",
"email": "john@example.com"
},
"line_items": [
{
"product_id": "prod_widget_001",
"sku": "WIDGET-001",
"quantity": 2,
"unit_price": 29.99,
"discount_amount": 1.5
},
{
"product_id": "prod_gadget_002",
"sku": "GADGET-002",
"quantity": 1,
"unit_price": 19.99,
"discount_amount": 1.5
}
]
}'
```
```python Python theme={null}
import requests
import json
url = "https://production.trackstarhq.com/wms/orders"
headers = {
"Content-Type": "application/json",
"x-trackstar-api-key": "YOUR_API_KEY",
"x-trackstar-access-token": "YOUR_ACCESS_TOKEN"
}
payload = {
"warehouse_customer_id": "customer_12345",
"reference_id": "order_2024_001",
"order_number": "ORD-001",
"channel_object": {
"channel_id": "Online Store",
"channel_name": "shopify"
},
"trading_partner": "Direct",
"shipping_method_id": "1234",
"shipping_method": "fedex_ground",
"service_level": "Standard",
"total_price": 79.98,
"total_tax": 6.40,
"ship_to_address": {
"name": "John Doe",
"company": None,
"address1": "123 Main St",
"address2": "Apt 4B",
"city": "Anytown",
"state": "NY",
"zip_code": "12345",
"country": "US",
"phone_number": "+1234567890",
"email": "john@example.com"
},
"line_items": [
{
"product_id": "prod_widget_001",
"sku": "WIDGET-001",
"quantity": 2,
"unit_price": 29.99,
"discount_amount": 1.5
},
{
"product_id": "prod_gadget_002",
"sku": "GADGET-002",
"quantity": 1,
"unit_price": 19.99,
"discount_amount": 1.5
}
]
}
response = requests.post(url, headers=headers, json=payload)
print(response.json())
```
```javascript JavaScript theme={null}
const url = "https://production.trackstarhq.com/wms/orders";
const payload = {
warehouse_customer_id: "customer_12345",
reference_id: "order_2024_001",
order_number: "ORD-001",
channel_object: {
channel_id: "Online Store",
channel_name: "shopify"
},
trading_partner: "Direct",
shipping_method_id: "1234",
shipping_method: "fedex_ground",
service_level: "Standard",
total_price: 79.98,
total_tax: 6.40,
ship_to_address: {
name: "John Doe",
company: null,
address1: "123 Main St",
address2: "Apt 4B",
city: "Anytown",
state: "NY",
zip_code: "12345",
country: "US",
phone_number: "+1234567890",
email: "john@example.com"
},
line_items: [
{
product_id: "prod_widget_001",
sku: "WIDGET-001",
quantity: 2,
unit_price: 29.99,
discount_amount: 1.5
},
{
product_id: "prod_gadget_002",
sku: "GADGET-002",
quantity: 1,
unit_price: 19.99,
discount_amount: 1.5
}
]
};
fetch(url, {
method: "POST",
headers: {
"Content-Type": "application/json",
"x-trackstar-api-key": "YOUR_API_KEY",
"x-trackstar-access-token": "YOUR_ACCESS_TOKEN"
},
body: JSON.stringify(payload)
})
.then(response => response.json())
.then(data => console.log(data));
```
```php PHP theme={null}
"customer_12345",
"reference_id" => "order_2024_001",
"order_number" => "ORD-001",
"channel_object" => [
"channel_id" => "Online Store",
"channel_name" => "shopify"
],
"trading_partner" => "Direct",
"shipping_method_id" => "1234",
"shipping_method" => "fedex_ground",
"service_level" => "Standard",
"total_price" => 79.98,
"total_tax" => 6.40,
"ship_to_address" => [
"name" => "John Doe",
"company" => null,
"address1" => "123 Main St",
"address2" => "Apt 4B",
"city" => "Anytown",
"state" => "NY",
"zip_code" => "12345",
"country" => "US",
"phone_number" => "+1234567890",
"email" => "john@example.com"
],
"line_items" => [
[
"product_id" => "prod_widget_001",
"sku" => "WIDGET-001",
"quantity" => 2,
"unit_price" => 29.99,
"discount_amount" => 1.5
],
[
"product_id" => "prod_gadget_002",
"sku" => "GADGET-002",
"quantity" => 1,
"unit_price" => 19.99,
"discount_amount" => 1.5
]
]
];
$options = [
"http" => [
"header" => "Content-Type: application/json\r\n" .
"x-trackstar-api-key: YOUR_API_KEY\r\n" .
"x-trackstar-access-token: YOUR_ACCESS_TOKEN\r\n",
"method" => "POST",
"content" => json_encode($payload)
]
];
$context = stream_context_create($options);
$response = file_get_contents($url, false, $context);
echo $response;
?>
```
```go Go theme={null}
package main
import (
"bytes"
"encoding/json"
"fmt"
"net/http"
)
type OrderRequest struct {
WarehouseCustomerID string `json:"warehouse_customer_id"`
ReferenceID string `json:"reference_id"`
OrderNumber string `json:"order_number"`
ChannelObject ChannelObject `json:"channel_object"`
TradingPartner string `json:"trading_partner"`
ShippingMethodID string `json:"shipping_method_id"`
ShippingMethod string `json:"shipping_method"`
ServiceLevel string `json:"service_level"`
TotalPrice float64 `json:"total_price"`
TotalTax float64 `json:"total_tax"`
ShipToAddress Address `json:"ship_to_address"`
LineItems []LineItem `json:"line_items"`
}
type ChannelObject struct {
ChannelID string `json:"channel_id"`
ChannelName string `json:"channel_name"`
}
type Address struct {
Name string `json:"name"`
Company *string `json:"company"`
Address1 string `json:"address1"`
Address2 string `json:"address2"`
City string `json:"city"`
State string `json:"state"`
ZipCode string `json:"zip_code"`
Country string `json:"country"`
PhoneNumber string `json:"phone_number"`
Email string `json:"email"`
}
type LineItem struct {
ProductID string `json:"product_id"`
SKU string `json:"sku"`
Quantity int `json:"quantity"`
UnitPrice float64 `json:"unit_price"`
DiscountAmount float64 `json:"discount_amount"`
}
func main() {
url := "https://production.trackstarhq.com/wms/orders"
orderReq := OrderRequest{
WarehouseCustomerID: "customer_12345",
ReferenceID: "order_2024_001",
OrderNumber: "ORD-001",
ChannelObject: ChannelObject{
ChannelID: "Online Store",
ChannelName: "shopify",
},
TradingPartner: "Direct",
ShippingMethodID: "1234",
ShippingMethod: "fedex_ground",
ServiceLevel: "Standard",
TotalPrice: 79.98,
TotalTax: 6.40,
ShipToAddress: Address{
Name: "John Doe",
Company: nil,
Address1: "123 Main St",
Address2: "Apt 4B",
City: "Anytown",
State: "NY",
ZipCode: "12345",
Country: "US",
PhoneNumber: "+1234567890",
Email: "john@example.com",
},
LineItems: []LineItem{
{
ProductID: "prod_widget_001",
SKU: "WIDGET-001",
Quantity: 2,
UnitPrice: 29.99,
DiscountAmount: 1.5,
},
{
ProductID: "prod_gadget_002",
SKU: "GADGET-002",
Quantity: 1,
UnitPrice: 19.99,
DiscountAmount: 1.5,
},
},
}
jsonData, _ := json.Marshal(orderReq)
req, _ := http.NewRequest("POST", url, bytes.NewBuffer(jsonData))
req.Header.Set("Content-Type", "application/json")
req.Header.Set("x-trackstar-api-key", "YOUR_API_KEY")
req.Header.Set("x-trackstar-access-token", "YOUR_ACCESS_TOKEN")
client := &http.Client{}
resp, err := client.Do(req)
if err != nil {
panic(err)
}
defer resp.Body.Close()
fmt.Println("Response Status:", resp.Status)
}
```
```java Java theme={null}
import java.io.IOException;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.URI;
public class TrackstarOrderExample {
public static void main(String[] args) throws IOException, InterruptedException {
String url = "https://production.trackstarhq.com/wms/orders";
String jsonPayload = """
{
"warehouse_customer_id": "customer_12345",
"reference_id": "order_2024_001",
"order_number": "ORD-001",
"channel_object": {
"channel_id": "Online Store",
"channel_name": "shopify"
},
"trading_partner": "Direct",
"shipping_method_id": "1234",
"shipping_method": "fedex_ground",
"service_level": "Standard",
"total_price": 79.98,
"total_tax": 6.40,
"ship_to_address": {
"name": "John Doe",
"company": null,
"address1": "123 Main St",
"address2": "Apt 4B",
"city": "Anytown",
"state": "NY",
"zip_code": "12345",
"country": "US",
"phone_number": "+1234567890",
"email": "john@example.com"
},
"line_items": [
{
"product_id": "prod_widget_001",
"sku": "WIDGET-001",
"quantity": 2,
"unit_price": 29.99,
"discount_amount": 1.5
},
{
"product_id": "prod_gadget_002",
"sku": "GADGET-002",
"quantity": 1,
"unit_price": 19.99,
"discount_amount": 1.5
}
]
}
""";
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create(url))
.header("Content-Type", "application/json")
.header("x-trackstar-api-key", "YOUR_API_KEY")
.header("x-trackstar-access-token", "YOUR_ACCESS_TOKEN")
.POST(HttpRequest.BodyPublishers.ofString(jsonPayload))
.build();
HttpClient client = HttpClient.newHttpClient();
HttpResponse response = client.send(request,
HttpResponse.BodyHandlers.ofString());
System.out.println("Status Code: " + response.statusCode());
System.out.println("Response: " + response.body());
}
}
```
```ruby Ruby theme={null}
require 'net/http'
require 'json'
url = URI('https://production.trackstarhq.com/wms/orders')
payload = {
warehouse_customer_id: "customer_12345",
reference_id: "order_2024_001",
order_number: "ORD-001",
channel_object: {
channel_id: "Online Store",
channel_name: "shopify"
},
trading_partner: "Direct",
shipping_method_id: "1234",
shipping_method: "fedex_ground",
service_level: "Standard",
total_price: 79.98,
total_tax: 6.40,
ship_to_address: {
name: "John Doe",
company: nil,
address1: "123 Main St",
address2: "Apt 4B",
city: "Anytown",
state: "NY",
zip_code: "12345",
country: "US",
phone_number: "+1234567890",
email: "john@example.com"
},
line_items: [
{
product_id: "prod_widget_001",
sku: "WIDGET-001",
quantity: 2,
unit_price: 29.99,
discount_amount: 1.5
},
{
product_id: "prod_gadget_002",
sku: "GADGET-002",
quantity: 1,
unit_price: 19.99,
discount_amount: 1.5
}
]
}
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request['Content-Type'] = 'application/json'
request['x-trackstar-api-key'] = 'YOUR_API_KEY'
request['x-trackstar-access-token'] = 'YOUR_ACCESS_TOKEN'
request.body = payload.to_json
response = http.request(request)
puts "Status: #{response.code}"
puts "Response: #{response.body}"
```
### Response
The API will return the created order with a unique Trackstar order ID:
```json theme={null}
{
"data": {
"id": "order_abc123",
"warehouse_customer_id": "customer_12345",
"warehouse_id": "warehouse_main",
"created_date": "2024-01-15T10:00:00Z",
"updated_date": "2024-01-15T10:00:00Z",
"reference_id": "order_2024_001",
"order_number": "ORD-001",
"status": "open",
"raw_status": "new_order",
"channel": "shopify",
"channel_object": {
"channel_id": "Online Store",
"channel_name": "shopify"
},
"type": "d2c",
"trading_partner": "Direct",
"shipping_method": "fedex_ground",
"is_third_party_freight": false,
"third_party_freight_account_number": null,
"first_party_freight_account_number": null,
"invoice_currency_code": "USD",
"total_price": 79.98,
"total_tax": 6.40,
"total_discount": 3.00,
"total_shipping": 5.99,
"ship_to_address": {
"name": "John Doe",
"company": null,
"address1": "123 Main St",
"address2": "Apt 4B",
"city": "Anytown",
"state": "NY",
"zip_code": "12345",
"country": "US",
"phone_number": "+1234567890",
"email": "john@example.com"
},
"line_items": [
{
"product_id": "prod_widget_001",
"sku": "WIDGET-001",
"quantity": 2,
"unit_price": 29.99,
"is_picked": false,
"discount_amount": 1.5
},
{
"product_id": "prod_gadget_002",
"sku": "GADGET-002",
"quantity": 1,
"unit_price": 19.99,
"is_picked": false,
"discount_amount": 1.5
}
],
"tags": ["rush_order"],
"required_ship_date": "2024-01-18T00:00:00Z",
"saturday_delivery": false,
"signature_required": false,
"international_duty_paid_by": null,
"shipments": [],
"external_system_url": "https://wms.example.com/orders/order_abc123",
"trackstar_tags": ["high-priority", {"customer_type": "premium"}],
"additional_fields": {
"order_notes": "Handle with care",
"customer_tier": "gold"
}
}
}
```
## Tracking Order Status and Fulfillments
Once an order is created, you can track its progress using the [Get Order endpoint](/api-reference/wms-api/orders/get-item).
### Fetching an Order
```bash cURL theme={null}
curl -X GET https://production.trackstarhq.com/wms/orders/order_abc123 \
-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/wms/orders/order_abc123"
headers = {
"x-trackstar-api-key": "YOUR_API_KEY",
"x-trackstar-access-token": "YOUR_ACCESS_TOKEN"
}
response = requests.get(url, headers=headers)
print(response.json())
```
```javascript JavaScript theme={null}
const url = "https://production.trackstarhq.com/wms/orders/order_abc123";
fetch(url, {
method: "GET",
headers: {
"x-trackstar-api-key": "YOUR_API_KEY",
"x-trackstar-access-token": "YOUR_ACCESS_TOKEN"
}
})
.then(response => response.json())
.then(data => console.log(data));
```
```php PHP theme={null}
[
"header" => "x-trackstar-api-key: YOUR_API_KEY\r\n" .
"x-trackstar-access-token: YOUR_ACCESS_TOKEN\r\n",
"method" => "GET"
]
];
$context = stream_context_create($options);
$response = file_get_contents($url, false, $context);
echo $response;
?>
```
```go Go theme={null}
package main
import (
"fmt"
"io"
"net/http"
)
func main() {
url := "https://production.trackstarhq.com/wms/orders/order_abc123"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Set("x-trackstar-api-key", "YOUR_API_KEY")
req.Header.Set("x-trackstar-access-token", "YOUR_ACCESS_TOKEN")
client := &http.Client{}
resp, err := client.Do(req)
if err != nil {
panic(err)
}
defer resp.Body.Close()
body, _ := io.ReadAll(resp.Body)
fmt.Println("Response:", string(body))
}
```
```java Java theme={null}
import java.io.IOException;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.URI;
public class TrackstarGetOrderExample {
public static void main(String[] args) throws IOException, InterruptedException {
String url = "https://production.trackstarhq.com/wms/orders/order_abc123";
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create(url))
.header("x-trackstar-api-key", "YOUR_API_KEY")
.header("x-trackstar-access-token", "YOUR_ACCESS_TOKEN")
.GET()
.build();
HttpClient client = HttpClient.newHttpClient();
HttpResponse response = client.send(request,
HttpResponse.BodyHandlers.ofString());
System.out.println("Status Code: " + response.statusCode());
System.out.println("Response: " + response.body());
}
}
```
```ruby Ruby theme={null}
require 'net/http'
url = URI('https://production.trackstarhq.com/wms/orders/order_abc123')
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request['x-trackstar-api-key'] = 'YOUR_API_KEY'
request['x-trackstar-access-token'] = 'YOUR_ACCESS_TOKEN'
response = http.request(request)
puts "Status: #{response.code}"
puts "Response: #{response.body}"
```
### Sample Response
```json theme={null}
{
"data": {
"id": "order_abc123",
"warehouse_customer_id": "customer_12345",
"warehouse_id": "warehouse_main",
"created_date": "2024-01-15T10:00:00Z",
"updated_date": "2024-01-16T14:30:00Z",
"reference_id": "order_2024_001",
"order_number": "ORD-001",
"status": "fulfilled",
"raw_status": "shipped",
"channel": "shopify",
"channel_object": {
"channel_id": "Online Store",
"channel_name": "shopify"
},
"type": "d2c",
"trading_partner": "Direct",
"shipping_method": "fedex_ground",
"is_third_party_freight": false,
"third_party_freight_account_number": null,
"first_party_freight_account_number": null,
"invoice_currency_code": "USD",
"total_price": 79.98,
"total_tax": 6.40,
"total_discount": 3.00,
"total_shipping": 5.99,
"ship_to_address": {
"name": "John Doe",
"company": null,
"address1": "123 Main St",
"address2": "Apt 4B",
"city": "Anytown",
"state": "NY",
"zip_code": "12345",
"country": "US",
"phone_number": "+1234567890",
"email": "john@example.com"
},
"line_items": [
{
"product_id": "prod_widget_001",
"sku": "WIDGET-001",
"quantity": 2,
"unit_price": 29.99,
"is_picked": true,
"discount_amount": 1.5
},
{
"product_id": "prod_gadget_002",
"sku": "GADGET-002",
"quantity": 1,
"unit_price": 19.99,
"is_picked": true,
"discount_amount": 1.5
}
],
"tags": ["rush_order"],
"required_ship_date": "2024-01-18T00:00:00Z",
"saturday_delivery": false,
"signature_required": false,
"international_duty_paid_by": null,
"shipments": [
{
"shipment_id": "shipment_abc123",
"warehouse_id": "warehouse_main",
"shipped_date": "2024-01-16T15:45:00Z",
"raw_status": "shipped",
"status": "shipped",
"shipping_method": "fedex_ground",
"line_items": [
{
"inventory_item_id": "inv_widget001_main",
"sku": "WIDGET-001",
"quantity": 2,
"parent_product_id": null
},
{
"inventory_item_id": "inv_gadget002_main",
"sku": "GADGET-002",
"quantity": 1,
"parent_product_id": null
}
],
"ship_to_address": {
"full_name": "John Doe",
"company": null,
"address1": "123 Main St",
"address2": "Apt 4B",
"address3": null,
"city": "Anytown",
"state": "NY",
"postal_code": "12345",
"country": "US"
},
"ship_from_address": {
"address1": "456 Warehouse Blvd",
"address2": null,
"address3": null,
"city": "Distribution City",
"state": "NJ",
"postal_code": "07001",
"country": "US"
},
"packages": [
{
"package_id": "pkg_001",
"package_name": "12x9x4",
"tracking_number": "1Z999AA1234567890",
"tracking_url": "https://www.fedex.com/apps/fedextrack/?tracknumbers=1Z999AA1234567890",
"shipping_method": "fedex_ground",
"carrier": "FedEx",
"shipping_method_id": "fedex_ground",
"shipping_method_name": "FedEx Ground",
"carrier_id": "fedex",
"carrier_name": "FedEx",
"scac": "FEDX",
"shipping_cost": 8.95,
"measurements": {
"length": 12.0,
"width": 9.0,
"height": 4.0,
"unit": "in",
"weight": 2.5,
"weight_unit": "lb"
},
"line_items": [
{
"inventory_item_id": "inv_widget001_main",
"sku": "WIDGET-001",
"quantity": 2,
"lot_id": null,
"expiration_date": null,
"parent_product_id": null
},
{
"inventory_item_id": "inv_gadget002_main",
"sku": "GADGET-002",
"quantity": 1,
"lot_id": null,
"expiration_date": null,
"parent_product_id": null
}
]
}
]
}
],
"external_system_url": "https://wms.example.com/orders/order_abc123",
"trackstar_tags": ["high-priority", {"customer_type": "premium"}],
"additional_fields": {
"order_notes": "Handle with care",
"customer_tier": "gold"
}
}
}
```
### Real-time Updates
Utilize [webhooks](/how-to-guides/webhooks) to get notified each time there is an update to an order by subscribing to `order.updated` and/or `order.shipment.created` events.
## Order Status Workflow
Orders progress through various fulfillment stages as they move through the warehouse system. For detailed information about all available order statuses and their meanings, see the [Orders Info page](/api-reference/wms-api/orders/info).
# Overview
Source: https://docs.trackstarhq.com/use-cases/overview
Explore common use cases and implementation guides for the Trackstar API
## WMS API
Create orders and track fulfillments.
Keep stock in check.
Fulfill orders with tracking information.
Create RMAs and track disposition data.
Notify warehouses of incoming goods and track receipts.
## Cart API
Sync products, pull orders, and push back shipment and inventory updates.
## Carrier API
Retrieve invoice line items as JSON or download raw invoice files.
# Returns
Source: https://docs.trackstarhq.com/use-cases/returns
Learn how to create RMAs and track disposition data using the Trackstar API
Returns management is an essential part of the customer experience and inventory control. This guide shows you how to create Return Merchandise Authorizations (RMAs) and track return disposition data using the Trackstar API.
## Overview
The returns workflow typically involves:
1. Creating RMAs for customer return requests
2. Tracking return status and disposition data
3. Managing returned inventory
## Creating RMAs
Use the [Create Return endpoint](/api-reference/wms-api/returns/post) to create Return Merchandise Authorizations for customer return requests.
For a full list of fields that need to be passed in, see the [Programmatic Writes guide](/how-to-guides/programmatic-writes).
### Create the Return
```bash cURL theme={null}
curl -X POST https://production.trackstarhq.com/wms/returns \
-H "Content-Type: application/json" \
-H "x-trackstar-api-key: YOUR_API_KEY" \
-H "x-trackstar-access-token: YOUR_ACCESS_TOKEN" \
-d '{
"warehouse_id": "warehouse_main",
"order_id": "order_abc123",
"line_items": [
{"sku": "WIDGET-001", "quantity": 1},
{"sku": "GADGET-002", "quantity": 2}
]
}'
```
```python Python theme={null}
import requests
url = "https://production.trackstarhq.com/wms/returns"
headers = {
"Content-Type": "application/json",
"x-trackstar-api-key": "YOUR_API_KEY",
"x-trackstar-access-token": "YOUR_ACCESS_TOKEN"
}
payload = {
"warehouse_id": "warehouse_main",
"order_id": "order_abc123",
"line_items": [
{"sku": "WIDGET-001", "quantity": 1},
{"sku": "GADGET-002", "quantity": 2}
]
}
response = requests.post(url, headers=headers, json=payload)
print(response.json())
```
```javascript JavaScript theme={null}
const url = "https://production.trackstarhq.com/wms/returns";
const payload = {
warehouse_id: "warehouse_main",
order_id: "order_abc123",
line_items: [
{ sku: "WIDGET-001", quantity: 1 },
{ sku: "GADGET-002", quantity: 2 }
]
};
fetch(url, {
method: "POST",
headers: {
"Content-Type": "application/json",
"x-trackstar-api-key": "YOUR_API_KEY",
"x-trackstar-access-token": "YOUR_ACCESS_TOKEN"
},
body: JSON.stringify(payload)
})
.then(response => response.json())
.then(data => console.log(data));
```
```php PHP theme={null}
"warehouse_main",
"order_id" => "order_abc123",
"line_items" => [
["sku" => "WIDGET-001", "quantity" => 1],
["sku" => "GADGET-002", "quantity" => 2]
]
];
$options = [
"http" => [
"header" =>
"Content-Type: application/json\r\n" .
"x-trackstar-api-key: YOUR_API_KEY\r\n" .
"x-trackstar-access-token: YOUR_ACCESS_TOKEN\r\n",
"method" => "POST",
"content" => json_encode($payload)
]
];
$context = stream_context_create($options);
$response = file_get_contents($url, false, $context);
echo $response;
?>
```
```go Go theme={null}
package main
import (
"bytes"
"encoding/json"
"fmt"
"net/http"
)
type LineItem struct {
SKU string `json:"sku"`
Quantity int `json:"quantity"`
}
type ReturnRequest struct {
WarehouseID string `json:"warehouse_id"`
OrderID string `json:"order_id"`
LineItems []LineItem `json:"line_items"`
}
func main() {
url := "https://production.trackstarhq.com/wms/returns"
reqBody := ReturnRequest{
WarehouseID: "warehouse_main",
OrderID: "order_abc123",
LineItems: []LineItem{
{SKU: "WIDGET-001", Quantity: 1},
{SKU: "GADGET-002", Quantity: 2},
},
}
jsonData, _ := json.Marshal(reqBody)
req, _ := http.NewRequest("POST", url, bytes.NewBuffer(jsonData))
req.Header.Set("Content-Type", "application/json")
req.Header.Set("x-trackstar-api-key", "YOUR_API_KEY")
req.Header.Set("x-trackstar-access-token", "YOUR_ACCESS_TOKEN")
client := &http.Client{}
resp, err := client.Do(req)
if err != nil {
panic(err)
}
defer resp.Body.Close()
fmt.Println("Response Status:", resp.Status)
}
```
```java Java theme={null}
import java.io.IOException;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
public class TrackstarCreateReturnExample {
public static void main(String[] args) throws IOException, InterruptedException {
String url = "https://production.trackstarhq.com/wms/returns";
String jsonPayload = """
{
"warehouse_id": "warehouse_main",
"order_id": "order_abc123",
"line_items": [
{"sku": "WIDGET-001", "quantity": 1},
{"sku": "GADGET-002", "quantity": 2}
]
}
""";
HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create(url))
.header("Content-Type", "application/json")
.header("x-trackstar-api-key", "YOUR_API_KEY")
.header("x-trackstar-access-token", "YOUR_ACCESS_TOKEN")
.POST(HttpRequest.BodyPublishers.ofString(jsonPayload))
.build();
HttpResponse response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println("Status: " + response.statusCode());
System.out.println("Body: " + response.body());
}
}
```
```ruby Ruby theme={null}
require 'net/http'
require 'json'
require 'uri'
url = URI('https://production.trackstarhq.com/wms/returns')
payload = {
warehouse_id: "warehouse_main",
order_id: "order_abc123",
line_items: [
{ sku: "WIDGET-001", quantity: 1 },
{ sku: "GADGET-002", quantity: 2 }
]
}
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request['Content-Type'] = 'application/json'
request['x-trackstar-api-key'] = 'YOUR_API_KEY'
request['x-trackstar-access-token'] = 'YOUR_ACCESS_TOKEN'
request.body = payload.to_json
response = http.request(request)
puts "Status: #{response.code}"
puts "Response: #{response.body}"
```
### Sample Response
```json theme={null}
{
"data": {
"id": "return_abc123",
"warehouse_customer_id": "customer_12345",
"created_date": "2024-01-20T10:00:00Z",
"updated_date": "2024-01-20T10:00:00Z",
"status": "open",
"raw_status": "awaiting_return",
"order_id": "order_abc123",
"notes": ["Customer reported item too small"],
"line_items": [
{
"inventory_item_id": "inv_widget001_main",
"sku": "WIDGET-001",
"expected_quantity": 1,
"received_quantity": 0,
"restocked_quantity": 0,
"return_reason": "Too Small",
"quantity": 0
},
{
"inventory_item_id": "inv_gadget002_main",
"sku": "GADGET-002",
"expected_quantity": 2,
"received_quantity": 0,
"restocked_quantity": 0,
"return_reason": "Defective",
"quantity": 0
}
],
"shipments": [],
"external_system_url": "https://wms.example.com/returns/return_abc123",
"trackstar_tags": ["priority", {"type": "quality_issue"}],
"additional_fields": {
"return_notes": "Handle with care - inspect for defects",
"customer_tier": "gold"
}
}
}
```
## Tracking Return Disposition Data
Once RMAs are created, you can track their progress and disposition using the [Get Return endpoint](/api-reference/wms-api/returns/get-item).
### Fetch the Return
```bash cURL theme={null}
curl -X GET https://production.trackstarhq.com/wms/returns/return_abc123 \
-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/wms/returns/return_abc123"
headers = {
"x-trackstar-api-key": "YOUR_API_KEY",
"x-trackstar-access-token": "YOUR_ACCESS_TOKEN"
}
response = requests.get(url, headers=headers)
print(response.json())
```
```javascript JavaScript theme={null}
const url = "https://production.trackstarhq.com/wms/returns/return_abc123";
fetch(url, {
method: "GET",
headers: {
"x-trackstar-api-key": "YOUR_API_KEY",
"x-trackstar-access-token": "YOUR_ACCESS_TOKEN"
}
})
.then(response => response.json())
.then(data => console.log(data));
```
```php PHP theme={null}
[
"header" =>
"x-trackstar-api-key: YOUR_API_KEY\r\n" .
"x-trackstar-access-token: YOUR_ACCESS_TOKEN\r\n",
"method" => "GET"
]
];
$context = stream_context_create($options);
$response = file_get_contents($url, false, $context);
$response === false ? print_r(error_get_last()) : print($response);
?>
```
```go Go theme={null}
package main
import (
"fmt"
"io"
"net/http"
)
func main() {
url := "https://production.trackstarhq.com/wms/returns/return_abc123"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Set("x-trackstar-api-key", "YOUR_API_KEY")
req.Header.Set("x-trackstar-access-token", "YOUR_ACCESS_TOKEN")
client := &http.Client{}
resp, err := client.Do(req)
if err != nil {
panic(err)
}
defer resp.Body.Close()
body, _ := io.ReadAll(resp.Body)
fmt.Println(string(body))
}
```
```java Java theme={null}
import java.io.IOException;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
public class TrackstarGetReturnExample {
public static void main(String[] args) throws IOException, InterruptedException {
String url = "https://production.trackstarhq.com/wms/returns/return_abc123";
HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create(url))
.header("x-trackstar-api-key", "YOUR_API_KEY")
.header("x-trackstar-access-token", "YOUR_ACCESS_TOKEN")
.GET()
.build();
HttpResponse response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println("Status: " + response.statusCode());
System.out.println("Body: " + response.body());
}
}
```
```ruby Ruby theme={null}
require 'net/http'
require 'uri'
url = URI('https://production.trackstarhq.com/wms/returns/return_abc123')
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request['x-trackstar-api-key'] = 'YOUR_API_KEY'
request['x-trackstar-access-token'] = 'YOUR_ACCESS_TOKEN'
response = http.request(request)
puts "Status: #{response.code}"
puts "Response: #{response.body}"
```
### Sample Response
```json theme={null}
{
"data": {
"id": "return_abc123",
"warehouse_customer_id": "customer_12345",
"created_date": "2024-01-20T10:00:00Z",
"updated_date": "2024-01-22T15:30:00Z",
"status": "received",
"raw_status": "processing_complete",
"order_id": "order_abc123",
"notes": ["Customer reported item too small", "Items received and processed"],
"line_items": [
{
"inventory_item_id": "inv_widget001_main",
"sku": "WIDGET-001",
"expected_quantity": 1,
"received_quantity": 1,
"restocked_quantity": 1,
"return_reason": "Too Small",
"quantity": 1
},
{
"inventory_item_id": "inv_gadget002_main",
"sku": "GADGET-002",
"expected_quantity": 1,
"received_quantity": 1,
"restocked_quantity": 0,
"return_reason": "Defective",
"quantity": 1
}
],
"shipments": [
{
"tracking_number": "1Z999AA1234567890",
"shipped_date": "2024-01-21T09:00:00Z",
"arrived_date": "2024-01-22T14:00:00Z",
"warehouse_id": "warehouse_main",
"carrier": "UPS",
"shipping_cost": 12.50,
"measurements": {
"length": 12.0,
"width": 8.0,
"height": 6.0,
"unit": "in",
"weight": 3.5,
"weight_unit": "lb"
},
"line_items": [
{
"inventory_item_id": "inv_widget001_main",
"sku": "WIDGET-001",
"quantity": 1,
"receiving_details": [
{
"quantity": 1,
"condition": "good",
"disposition": "restocked"
}
]
},
{
"inventory_item_id": "inv_gadget002_main",
"sku": "GADGET-002",
"quantity": 1,
"receiving_details": [
{
"quantity": 1,
"condition": "damaged",
"disposition": "scrapped"
}
]
}
]
}
],
"external_system_url": "https://wms.example.com/returns/return_abc123",
"trackstar_tags": ["priority", {"type": "quality_issue"}],
"additional_fields": {
"return_notes": "Handle with care - inspect for defects",
"customer_tier": "gold"
}
}
}
```
### Real-time Updates
Utilize [webhooks](/how-to-guides/webhooks) to get notified each time there is an update to an RMA by subscribing to `return.updated` events.
## Return Status Workflow
Returns progress through various stages as they move through the processing system. For detailed information about all available return statuses and their meanings, see the [Returns Info page](/api-reference/wms-api/returns/info).
## Best Practices
### Return Creation
* Always link returns to the original order using `order_id`
* Specify the correct warehouse that will receive the return
* Validate SKUs and quantities before creating returns
* Ensure line items match products from the original order
### Disposition Tracking
* Regularly fetch return status updates to monitor progress
* Track individual line item statuses within returns
* Monitor the overall return workflow from creation to completion
# Shipping Solutions
Source: https://docs.trackstarhq.com/use-cases/shipping-solutions
Learn how to fulfill orders with tracking information using the Trackstar API
Shipping is a critical component of order fulfillment. This guide shows you how to ship orders and attach shipping labels using the Trackstar API.
## Overview
The shipping workflow typically involves:
1. Creating shipments with tracking information
2. Attaching shipping labels and documentation
3. Providing tracking details to customers
## Shipping an Order
Use the [Create Shipment endpoint](/api-reference/wms-api/orders/create-shipment) to mark an order as fulfilled and provide shipment and tracking information.
For a full list of fields that need to be passed in, see the [Programmatic Writes guide](/how-to-guides/programmatic-writes).
### Create an Order Shipment
```bash cURL theme={null}
curl -X POST https://production.trackstarhq.com/wms/orders/order_abc123/shipments \
-H "Content-Type: application/json" \
-H "x-trackstar-api-key: YOUR_API_KEY" \
-H "x-trackstar-access-token: YOUR_ACCESS_TOKEN" \
-d '{
"shipped_date": "2024-01-15T14:30:00Z",
"carrier_id": "fedex",
"shipping_method_id": "fedex_ground",
"warehouse_id": "warehouse_main",
"packages": [
{
"package_id": "pkg_001",
"tracking_number": "1Z999AA1234567890"
}
]
}'
```
```python Python theme={null}
import requests
import json
url = "https://production.trackstarhq.com/wms/orders/order_abc123/shipments"
headers = {
"Content-Type": "application/json",
"x-trackstar-api-key": "YOUR_API_KEY",
"x-trackstar-access-token": "YOUR_ACCESS_TOKEN"
}
payload = {
"shipped_date": "2024-01-15T14:30:00Z",
"carrier_id": "fedex",
"shipping_method_id": "fedex_ground",
"warehouse_id": "warehouse_main",
"packages": [
{
"package_id": "pkg_001",
"tracking_number": "1Z999AA1234567890"
}
]
}
response = requests.post(url, headers=headers, json=payload)
print(response.json())
```
```javascript JavaScript theme={null}
const url = "https://production.trackstarhq.com/wms/orders/order_abc123/shipments";
const payload = {
shipped_date: "2024-01-15T14:30:00Z",
carrier_id: "fedex",
shipping_method_id: "fedex_ground",
warehouse_id: "warehouse_main",
packages: [
{
package_id: "pkg_001",
tracking_number: "1Z999AA1234567890"
}
]
};
fetch(url, {
method: "POST",
headers: {
"Content-Type": "application/json",
"x-trackstar-api-key": "YOUR_API_KEY",
"x-trackstar-access-token": "YOUR_ACCESS_TOKEN"
},
body: JSON.stringify(payload)
})
.then(response => response.json())
.then(data => console.log(data));
```
```php PHP theme={null}
"2024-01-15T14:30:00Z",
"carrier_id" => "fedex",
"shipping_method_id" => "fedex_ground",
"warehouse_id" => "warehouse_main",
"packages" => [
[
"package_id" => "pkg_001",
"tracking_number" => "1Z999AA1234567890"
]
]
];
$options = [
"http" => [
"header" => "Content-Type: application/json\r\n" .
"x-trackstar-api-key: YOUR_API_KEY\r\n" .
"x-trackstar-access-token: YOUR_ACCESS_TOKEN\r\n",
"method" => "POST",
"content" => json_encode($payload)
]
];
$context = stream_context_create($options);
$response = file_get_contents($url, false, $context);
echo $response;
?>
```
```go Go theme={null}
package main
import (
"bytes"
"encoding/json"
"fmt"
"net/http"
)
type ShipmentRequest struct {
ShippedDate string `json:"shipped_date"`
CarrierID string `json:"carrier_id"`
ShippingMethodID string `json:"shipping_method_id"`
WarehouseID string `json:"warehouse_id"`
Packages []Package `json:"packages"`
}
type Package struct {
PackageID string `json:"package_id"`
TrackingNumber string `json:"tracking_number"`
}
func main() {
url := "https://production.trackstarhq.com/wms/orders/order_abc123/shipments"
shipmentReq := ShipmentRequest{
ShippedDate: "2024-01-15T14:30:00Z",
CarrierID: "fedex",
ShippingMethodID: "fedex_ground",
WarehouseID: "warehouse_main",
Packages: []Package{
{
PackageID: "pkg_001",
TrackingNumber: "1Z999AA1234567890",
},
},
}
jsonData, _ := json.Marshal(shipmentReq)
req, _ := http.NewRequest("POST", url, bytes.NewBuffer(jsonData))
req.Header.Set("Content-Type", "application/json")
req.Header.Set("x-trackstar-api-key", "YOUR_API_KEY")
req.Header.Set("x-trackstar-access-token", "YOUR_ACCESS_TOKEN")
client := &http.Client{}
resp, err := client.Do(req)
if err != nil {
panic(err)
}
defer resp.Body.Close()
fmt.Println("Response Status:", resp.Status)
}
```
```java Java theme={null}
import java.io.IOException;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.URI;
public class TrackstarShipmentExample {
public static void main(String[] args) throws IOException, InterruptedException {
String url = "https://production.trackstarhq.com/wms/orders/order_abc123/shipments";
String jsonPayload = """
{
"shipped_date": "2024-01-15T14:30:00Z",
"carrier_id": "fedex",
"shipping_method_id": "fedex_ground",
"warehouse_id": "warehouse_main",
"packages": [
{
"package_id": "pkg_001",
"tracking_number": "1Z999AA1234567890"
}
]
}
""";
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create(url))
.header("Content-Type", "application/json")
.header("x-trackstar-api-key", "YOUR_API_KEY")
.header("x-trackstar-access-token", "YOUR_ACCESS_TOKEN")
.POST(HttpRequest.BodyPublishers.ofString(jsonPayload))
.build();
HttpClient client = HttpClient.newHttpClient();
HttpResponse response = client.send(request,
HttpResponse.BodyHandlers.ofString());
System.out.println("Status Code: " + response.statusCode());
System.out.println("Response: " + response.body());
}
}
```
```ruby Ruby theme={null}
require 'net/http'
require 'json'
url = URI('https://production.trackstarhq.com/wms/orders/order_abc123/shipments')
payload = {
shipped_date: "2024-01-15T14:30:00Z",
carrier_id: "fedex",
shipping_method_id: "fedex_ground",
warehouse_id: "warehouse_main",
packages: [
{
package_id: "pkg_001",
tracking_number: "1Z999AA1234567890"
}
]
}
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request['Content-Type'] = 'application/json'
request['x-trackstar-api-key'] = 'YOUR_API_KEY'
request['x-trackstar-access-token'] = 'YOUR_ACCESS_TOKEN'
request.body = payload.to_json
response = http.request(request)
puts "Status: #{response.code}"
puts "Response: #{response.body}"
```
### Sample Response
```json theme={null}
{
"data": {
"id": "order_abc123",
"warehouse_customer_id": "customer_12345",
"warehouse_id": "warehouse_main",
"created_date": "2024-01-15T10:00:00Z",
"updated_date": "2024-01-15T14:35:00Z",
"reference_id": "order_2024_001",
"order_number": "ORD-001",
"status": "fulfilled",
"raw_status": "shipped",
"channel": "shopify",
"channel_object": {
"channel_id": "Online Store",
"channel_name": "shopify"
},
"type": "d2c",
"trading_partner": "Direct",
"shipping_method": "fedex_ground",
"service_level": "Standard",
"shipping_method_id": "fedex_ground",
"shipping_method_name": "FedEx Ground",
"carrier_id": "fedex",
"carrier_name": "FedEx",
"scac": "FEDX",
"is_third_party_freight": false,
"third_party_freight_account_number": null,
"first_party_freight_account_number": null,
"invoice_currency_code": "USD",
"total_price": 79.98,
"total_tax": 6.40,
"total_discount": 3.00,
"total_shipping": 8.95,
"ship_to_address": {
"full_name": "John Doe",
"company": null,
"address1": "123 Main St",
"address2": "Apt 4B",
"address3": null,
"city": "Anytown",
"state": "NY",
"postal_code": "12345",
"country": "US",
"phone_number": "123-456-7890",
"email_address": "john@example.com"
},
"line_items": [
{
"product_id": "prod_widget_001",
"sku": "WIDGET-001",
"quantity": 2,
"unit_price": 29.99,
"is_picked": true,
"discount_amount": 1.5
},
{
"product_id": "prod_gadget_002",
"sku": "GADGET-002",
"quantity": 1,
"unit_price": 19.99,
"is_picked": true,
"discount_amount": 1.5
}
],
"tags": ["rush_order"],
"required_ship_date": "2024-01-18T00:00:00Z",
"saturday_delivery": false,
"signature_required": false,
"international_duty_paid_by": null,
"shipments": [
{
"shipment_id": "shipment_abc123",
"warehouse_id": "warehouse_main",
"shipped_date": "2024-01-15T14:30:00Z",
"raw_status": "shipped",
"status": "shipped",
"shipping_method": "fedex_ground",
"line_items": [
{
"inventory_item_id": "inv_widget001_main",
"sku": "WIDGET-001",
"quantity": 2,
"parent_product_id": null
},
{
"inventory_item_id": "inv_gadget002_main",
"sku": "GADGET-002",
"quantity": 1,
"parent_product_id": null
}
],
"ship_to_address": {
"full_name": "John Doe",
"company": null,
"address1": "123 Main St",
"address2": "Apt 4B",
"address3": null,
"city": "Anytown",
"state": "NY",
"postal_code": "12345",
"country": "US"
},
"ship_from_address": {
"address1": "456 Warehouse Blvd",
"address2": null,
"address3": null,
"city": "Distribution City",
"state": "NJ",
"postal_code": "07001",
"country": "US"
},
"packages": [
{
"package_id": "pkg_001",
"package_name": "12x9x4",
"tracking_number": "1Z999AA1234567890",
"tracking_url": "https://www.fedex.com/apps/fedextrack/?tracknumbers=1Z999AA1234567890",
"shipping_method": "fedex_ground",
"carrier": "FedEx",
"shipping_method_id": "fedex_ground",
"shipping_method_name": "FedEx Ground",
"carrier_id": "fedex",
"carrier_name": "FedEx",
"scac": "FEDX",
"shipping_cost": 8.95,
"measurements": {
"length": 12.0,
"width": 9.0,
"height": 4.0,
"unit": "in",
"weight": 2.5,
"weight_unit": "lb"
},
"line_items": [
{
"inventory_item_id": "inv_widget001_main",
"sku": "WIDGET-001",
"quantity": 2,
"lot_id": null,
"expiration_date": null,
"parent_product_id": null
},
{
"inventory_item_id": "inv_gadget002_main",
"sku": "GADGET-002",
"quantity": 1,
"lot_id": null,
"expiration_date": null,
"parent_product_id": null
}
]
}
]
}
],
"external_system_url": "https://wms.example.com/orders/order_abc123",
"trackstar_tags": ["high-priority", {"customer_type": "premium"}],
"additional_fields": {
"order_notes": "Handle with care",
"customer_tier": "gold"
}
}
}
```
### Multi-Package Shipment
For orders that ship in multiple packages, you can include each under `packages` in your request body:
```json theme={null}
{
"packages": [
{
"package_id": "pkg_001",
"tracking_number": "1Z999AA1234567890"
},
{
"package_id": "pkg_002",
"tracking_number": "1Z999AA1234567891"
}
]
}
```
## Adding Shipping Labels
Use the [Attach File endpoint](/api-reference/wms-api/orders/attach-file) to attach shipping labels and other documentation to orders.
### Attach File
```bash cURL theme={null}
curl -X POST https://production.trackstarhq.com/wms/orders/order_abc123/file \
-H "x-trackstar-api-key: YOUR_API_KEY" \
-H "x-trackstar-access-token: YOUR_ACCESS_TOKEN" \
-F "file=@/path/to/shipping_label.pdf" \
-F "file_name=shipping_label.pdf" \
-F "file_url=https://labels.example.com/shipping_label_123.pdf"
```
```python Python theme={null}
import requests
url = "https://production.trackstarhq.com/wms/orders/order_abc123/file"
headers = {
"x-trackstar-api-key": "YOUR_API_KEY",
"x-trackstar-access-token": "YOUR_ACCESS_TOKEN"
}
# Upload file from local path
with open('/path/to/shipping_label.pdf', 'rb') as f:
files = {
'file': ('shipping_label.pdf', f, 'application/pdf')
}
data = {
'file_name': 'shipping_label.pdf',
'file_url': 'https://labels.example.com/shipping_label_123.pdf'
}
response = requests.post(url, headers=headers, files=files, data=data)
print(response.json())
```
```javascript JavaScript theme={null}
const url = "https://production.trackstarhq.com/wms/orders/order_abc123/file";
// Using FormData for file upload
const formData = new FormData();
formData.append('file_name', 'shipping_label.pdf');
formData.append('file_url', 'https://labels.example.com/shipping_label_123.pdf');
// Assuming you have a file input element with id 'fileInput'
const fileInput = document.getElementById('fileInput');
if (fileInput.files.length > 0) {
formData.append('file', fileInput.files[0]);
}
fetch(url, {
method: "POST",
headers: {
"x-trackstar-api-key": "YOUR_API_KEY",
"x-trackstar-access-token": "YOUR_ACCESS_TOKEN"
// Don't set Content-Type for FormData - let browser set it
},
body: formData
})
.then(response => response.json())
.then(data => console.log(data));
```
```php PHP theme={null}
new CURLFile('/path/to/shipping_label.pdf', 'application/pdf', 'shipping_label.pdf'),
'file_name' => 'shipping_label.pdf',
'file_url' => 'https://labels.example.com/shipping_label_123.pdf'
];
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $postFields);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);
echo $response;
?>
```
```go Go theme={null}
package main
import (
"bytes"
"fmt"
"io"
"mime/multipart"
"net/http"
"os"
)
func main() {
url := "https://production.trackstarhq.com/wms/orders/order_abc123/file"
// Create multipart form
var b bytes.Buffer
writer := multipart.NewWriter(&b)
// Add form fields
writer.WriteField("file_name", "shipping_label.pdf")
writer.WriteField("file_url", "https://labels.example.com/shipping_label_123.pdf")
// Add file
file, err := os.Open("/path/to/shipping_label.pdf")
if err != nil {
panic(err)
}
defer file.Close()
part, err := writer.CreateFormFile("file", "shipping_label.pdf")
if err != nil {
panic(err)
}
io.Copy(part, file)
writer.Close()
// Create request
req, _ := http.NewRequest("POST", url, &b)
req.Header.Set("Content-Type", writer.FormDataContentType())
req.Header.Set("x-trackstar-api-key", "YOUR_API_KEY")
req.Header.Set("x-trackstar-access-token", "YOUR_ACCESS_TOKEN")
client := &http.Client{}
resp, err := client.Do(req)
if err != nil {
panic(err)
}
defer resp.Body.Close()
fmt.Println("Response Status:", resp.Status)
}
```
```java Java theme={null}
import java.io.File;
import java.io.IOException;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.URI;
import java.nio.file.Files;
public class TrackstarFileUploadExample {
public static void main(String[] args) throws IOException, InterruptedException {
String url = "https://production.trackstarhq.com/wms/orders/order_abc123/file";
String boundary = "----TrackstarFormBoundary" + System.currentTimeMillis();
// Read file content
File file = new File("/path/to/shipping_label.pdf");
byte[] fileContent = Files.readAllBytes(file.toPath());
// Build multipart form data
StringBuilder formData = new StringBuilder();
formData.append("--").append(boundary).append("\r\n");
formData.append("Content-Disposition: form-data; name=\"file_name\"\r\n\r\n");
formData.append("shipping_label.pdf\r\n");
formData.append("--").append(boundary).append("\r\n");
formData.append("Content-Disposition: form-data; name=\"file_url\"\r\n\r\n");
formData.append("https://labels.example.com/shipping_label_123.pdf\r\n");
formData.append("--").append(boundary).append("\r\n");
formData.append("Content-Disposition: form-data; name=\"file\"; filename=\"shipping_label.pdf\"\r\n");
formData.append("Content-Type: application/pdf\r\n\r\n");
String formDataString = formData.toString();
String endBoundary = "\r\n--" + boundary + "--\r\n";
// Combine form data, file content, and end boundary
byte[] requestBody = new byte[formDataString.getBytes().length + fileContent.length + endBoundary.getBytes().length];
System.arraycopy(formDataString.getBytes(), 0, requestBody, 0, formDataString.getBytes().length);
System.arraycopy(fileContent, 0, requestBody, formDataString.getBytes().length, fileContent.length);
System.arraycopy(endBoundary.getBytes(), 0, requestBody, formDataString.getBytes().length + fileContent.length, endBoundary.getBytes().length);
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create(url))
.header("Content-Type", "multipart/form-data; boundary=" + boundary)
.header("x-trackstar-api-key", "YOUR_API_KEY")
.header("x-trackstar-access-token", "YOUR_ACCESS_TOKEN")
.POST(HttpRequest.BodyPublishers.ofByteArray(requestBody))
.build();
HttpClient client = HttpClient.newHttpClient();
HttpResponse response = client.send(request,
HttpResponse.BodyHandlers.ofString());
System.out.println("Status Code: " + response.statusCode());
System.out.println("Response: " + response.body());
}
}
```
```ruby Ruby theme={null}
require 'net/http'
require 'mime/types'
url = URI('https://production.trackstarhq.com/wms/orders/order_abc123/file')
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request['x-trackstar-api-key'] = 'YOUR_API_KEY'
request['x-trackstar-access-token'] = 'YOUR_ACCESS_TOKEN'
# Create multipart form data
boundary = "----RubyFormBoundary#{rand(1000000)}"
request['Content-Type'] = "multipart/form-data; boundary=#{boundary}"
file_path = '/path/to/shipping_label.pdf'
file_content = File.read(file_path)
form_data = []
form_data << "--#{boundary}\r\n"
form_data << "Content-Disposition: form-data; name=\"file_name\"\r\n\r\n"
form_data << "shipping_label.pdf\r\n"
form_data << "--#{boundary}\r\n"
form_data << "Content-Disposition: form-data; name=\"file_url\"\r\n\r\n"
form_data << "https://labels.example.com/shipping_label_123.pdf\r\n"
form_data << "--#{boundary}\r\n"
form_data << "Content-Disposition: form-data; name=\"file\"; filename=\"shipping_label.pdf\"\r\n"
form_data << "Content-Type: application/pdf\r\n\r\n"
form_data << file_content
form_data << "\r\n--#{boundary}--\r\n"
request.body = form_data.join
response = http.request(request)
puts "Status: #{response.code}"
puts "Response: #{response.body}"
```
**Sample Response:**
```json theme={null}
{
"data": "",
"id": "id",
"unused_fields": [
""
]
}
```
## Order Status Updates
Creating a shipment automatically updates the order status to "fulfilled" in Trackstar. This status change will trigger [webhooks](/how-to-guides/webhooks) to keep your systems synchronized.
# Warehouse ASNs
Source: https://docs.trackstarhq.com/use-cases/warehouse-asns
Learn how to notify warehouses of incoming goods and track receipts using the Trackstar API
Advance Shipping Notices (ASNs) are critical for efficient warehouse operations. This guide shows you how to create inbound shipments and track their progress using the Trackstar API.
## Overview
The ASN workflow typically involves:
1. Creating inbound shipments for incoming goods
2. Tracking receipt and processing status
## Creating Inbound Shipments
Use the [Create Inbound Shipment endpoint](/api-reference/wms-api/inbound-shipments/post) to create ASNs before goods arrive at the warehouse.
For a full list of fields that need to be passed in, see the [Programmatic Writes guide](/how-to-guides/programmatic-writes).
### Create the Inbound Shipment
```bash cURL theme={null}
curl -X POST https://production.trackstarhq.com/wms/inbound-shipments \
-H "Content-Type: application/json" \
-H "x-trackstar-api-key: YOUR_API_KEY" \
-H "x-trackstar-access-token: YOUR_ACCESS_TOKEN" \
-d '{
"supplier_object": {"supplier_id": "ACME001", "supplier_name": "Acme Suppliers Inc"},
"purchase_order_number": "PO-2024-001",
"expected_arrival_date": "2024-01-20T09:00:00Z",
"warehouse_id": "warehouse_main",
"tracking_number": "1234567890",
"line_items": [
{"sku": "WIDGET-001", "expected_quantity": 100},
{"sku": "GADGET-002", "expected_quantity": 50}
]
}'
```
```python Python theme={null}
import requests
url = "https://production.trackstarhq.com/wms/inbound-shipments"
headers = {
"Content-Type": "application/json",
"x-trackstar-api-key": "YOUR_API_KEY",
"x-trackstar-access-token": "YOUR_ACCESS_TOKEN"
}
payload = {
"supplier_object": {"supplier_id": "ACME001", "supplier_name": "Acme Suppliers Inc"},
"purchase_order_number": "PO-2024-001",
"expected_arrival_date": "2024-01-20T09:00:00Z",
"warehouse_id": "warehouse_main",
"tracking_number": "1234567890",
"line_items": [
{"sku": "WIDGET-001", "expected_quantity": 100},
{"sku": "GADGET-002", "expected_quantity": 50}
]
}
response = requests.post(url, headers=headers, json=payload)
print(response.json())
```
```javascript JavaScript theme={null}
const url = "https://production.trackstarhq.com/wms/inbound-shipments";
const payload = {
supplier_object: { supplier_id: "ACME001", supplier_name: "Acme Suppliers Inc" },
purchase_order_number: "PO-2024-001",
expected_arrival_date: "2024-01-20T09:00:00Z",
warehouse_id: "warehouse_main",
tracking_number: "1234567890",
line_items: [
{ sku: "WIDGET-001", expected_quantity: 100 },
{ sku: "GADGET-002", expected_quantity: 50 }
]
};
fetch(url, {
method: "POST",
headers: {
"Content-Type": "application/json",
"x-trackstar-api-key": "YOUR_API_KEY",
"x-trackstar-access-token": "YOUR_ACCESS_TOKEN"
},
body: JSON.stringify(payload)
})
.then(response => response.json())
.then(data => console.log(data));
```
```php PHP theme={null}
["supplier_id" => "ACME001", "supplier_name" => "Acme Suppliers Inc"],
"purchase_order_number" => "PO-2024-001",
"expected_arrival_date" => "2024-01-20T09:00:00Z",
"warehouse_id" => "warehouse_main",
"tracking_number" => "1234567890",
"line_items" => [
["sku" => "WIDGET-001", "expected_quantity" => 100],
["sku" => "GADGET-002", "expected_quantity" => 50]
]
];
$options = [
"http" => [
"header" =>
"Content-Type: application/json\r\n" .
"x-trackstar-api-key: YOUR_API_KEY\r\n" .
"x-trackstar-access-token: YOUR_ACCESS_TOKEN\r\n",
"method" => "POST",
"content" => json_encode($payload)
]
];
$context = stream_context_create($options);
$response = file_get_contents($url, false, $context);
echo $response;
?>
```
```go Go theme={null}
package main
import (
"bytes"
"encoding/json"
"fmt"
"net/http"
)
type Supplier struct {
SupplierID string `json:"supplier_id"`
SupplierName string `json:"supplier_name"`
}
type LineItem struct {
SKU string `json:"sku"`
ExpectedQuantity int `json:"expected_quantity"`
}
type InboundShipmentRequest struct {
SupplierObject Supplier `json:"supplier_object"`
PurchaseOrderNumber string `json:"purchase_order_number"`
ExpectedArrivalDate string `json:"expected_arrival_date"`
WarehouseID string `json:"warehouse_id"`
TrackingNumber string `json:"tracking_number"`
LineItems []LineItem `json:"line_items"`
}
func main() {
url := "https://production.trackstarhq.com/wms/inbound-shipments"
body := InboundShipmentRequest{
SupplierObject: Supplier{SupplierID: "ACME001", SupplierName: "Acme Suppliers Inc"},
PurchaseOrderNumber: "PO-2024-001",
ExpectedArrivalDate: "2024-01-20T09:00:00Z",
WarehouseID: "warehouse_main",
TrackingNumber: "1234567890",
LineItems: []LineItem{
{SKU: "WIDGET-001", ExpectedQuantity: 100},
{SKU: "GADGET-002", ExpectedQuantity: 50},
},
}
jsonData, _ := json.Marshal(body)
req, _ := http.NewRequest("POST", url, bytes.NewBuffer(jsonData))
req.Header.Set("Content-Type", "application/json")
req.Header.Set("x-trackstar-api-key", "YOUR_API_KEY")
req.Header.Set("x-trackstar-access-token", "YOUR_ACCESS_TOKEN")
client := &http.Client{}
resp, err := client.Do(req)
if err != nil {
panic(err)
}
defer resp.Body.Close()
fmt.Println("Response Status:", resp.Status)
}
```
```java Java theme={null}
import java.io.IOException;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
public class TrackstarCreateInboundShipmentExample {
public static void main(String[] args) throws IOException, InterruptedException {
String url = "https://production.trackstarhq.com/wms/inbound-shipments";
String jsonPayload = """
{
"supplier_object": {"supplier_id": "ACME001", "supplier_name": "Acme Suppliers Inc"},
"purchase_order_number": "PO-2024-001",
"expected_arrival_date": "2024-01-20T09:00:00Z",
"warehouse_id": "warehouse_main",
"tracking_number": "1234567890",
"line_items": [
{"sku": "WIDGET-001", "expected_quantity": 100},
{"sku": "GADGET-002", "expected_quantity": 50}
]
}
""";
HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create(url))
.header("Content-Type", "application/json")
.header("x-trackstar-api-key", "YOUR_API_KEY")
.header("x-trackstar-access-token", "YOUR_ACCESS_TOKEN")
.POST(HttpRequest.BodyPublishers.ofString(jsonPayload))
.build();
HttpResponse response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println("Status: " + response.statusCode());
System.out.println("Body: " + response.body());
}
}
```
```ruby Ruby theme={null}
require 'net/http'
require 'json'
require 'uri'
url = URI('https://production.trackstarhq.com/wms/inbound-shipments')
payload = {
supplier_object: { supplier_id: "ACME001", supplier_name: "Acme Suppliers Inc" },
purchase_order_number: "PO-2024-001",
expected_arrival_date: "2024-01-20T09:00:00Z",
warehouse_id: "warehouse_main",
tracking_number: "1234567890",
line_items: [
{ sku: "WIDGET-001", expected_quantity: 100 },
{ sku: "GADGET-002", expected_quantity: 50 }
]
}
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request['Content-Type'] = 'application/json'
request['x-trackstar-api-key'] = 'YOUR_API_KEY'
request['x-trackstar-access-token'] = 'YOUR_ACCESS_TOKEN'
request.body = payload.to_json
response = http.request(request)
puts "Status: #{response.code}"
puts "Response: #{response.body}"
```
### Sample Response
```json theme={null}
{
"data": {
"id": "inbound_shipment_abc123",
"warehouse_customer_id": "customer_12345",
"created_date": "2024-01-18T10:00:00Z",
"updated_date": "2024-01-18T10:00:00Z",
"purchase_order_number": "PO-2024-001",
"status": "open",
"raw_status": "awaiting_shipment",
"supplier": "ACME001",
"supplier_object": {
"supplier_id": "ACME001",
"supplier_name": "Acme Suppliers Inc"
},
"expected_arrival_date": "2024-01-20T09:00:00Z",
"warehouse_id": "warehouse_main",
"line_items": [
{
"inventory_item_id": "inv_widget001_main",
"sku": "WIDGET-001",
"expected_quantity": 100,
"received_quantity": 0,
"unit_cost": 25.00,
"external_id": "WIDGET-001-ACME"
},
{
"inventory_item_id": "inv_gadget002_main",
"sku": "GADGET-002",
"expected_quantity": 50,
"received_quantity": 0,
"unit_cost": 45.00,
"external_id": "GADGET-002-ACME"
}
],
"receipts": [],
"ship_from_address": {
"address1": "100 Supplier Blvd",
"address2": null,
"address3": null,
"city": "Supplier City",
"state": "CA",
"postal_code": "90210",
"country": "US"
},
"tracking_numbers": ["1234567890"],
"notes": ["Priority shipment - expedite receiving"],
"external_system_url": "https://wms.example.com/inbound/inbound_shipment_abc123",
"trackstar_tags": ["priority", {"supplier": "acme"}],
"additional_fields": {
"supplier_contact": "jane.doe@acme.com",
"special_handling": "fragile"
}
}
}
```
## Tracking Inbound Shipment Updates
Once inbound shipments are created, you can track their progress using the [Get Inbound Shipment endpoint](/api-reference/wms-api/inbound-shipments/get-item).
### Fetch the Inbound Shipment
```bash cURL theme={null}
curl -X GET https://production.trackstarhq.com/wms/inbound-shipments/inbound_shipment_abc123 \
-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/wms/inbound-shipments/inbound_shipment_abc123"
headers = {
"x-trackstar-api-key": "YOUR_API_KEY",
"x-trackstar-access-token": "YOUR_ACCESS_TOKEN"
}
response = requests.get(url, headers=headers)
print(response.json())
```
```javascript JavaScript theme={null}
const url = "https://production.trackstarhq.com/wms/inbound-shipments/inbound_shipment_abc123";
fetch(url, {
method: "GET",
headers: {
"x-trackstar-api-key": "YOUR_API_KEY",
"x-trackstar-access-token": "YOUR_ACCESS_TOKEN"
}
})
.then(response => response.json())
.then(data => console.log(data));
```
```php PHP theme={null}
[
"header" =>
"x-trackstar-api-key: YOUR_API_KEY\r\n" .
"x-trackstar-access-token: YOUR_ACCESS_TOKEN\r\n",
"method" => "GET"
]
];
$context = stream_context_create($options);
$response = file_get_contents($url, false, $context);
echo $response;
?>
```
```go Go theme={null}
package main
import (
"fmt"
"io"
"net/http"
)
func main() {
url := "https://production.trackstarhq.com/wms/inbound-shipments/inbound_shipment_abc123"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Set("x-trackstar-api-key", "YOUR_API_KEY")
req.Header.Set("x-trackstar-access-token", "YOUR_ACCESS_TOKEN")
client := &http.Client{}
resp, err := client.Do(req)
if err != nil {
panic(err)
}
defer resp.Body.Close()
body, _ := io.ReadAll(resp.Body)
fmt.Println(string(body))
}
```
```java Java theme={null}
import java.io.IOException;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
public class TrackstarGetInboundShipmentExample {
public static void main(String[] args) throws IOException, InterruptedException {
String url = "https://production.trackstarhq.com/wms/inbound-shipments/inbound_shipment_abc123";
HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create(url))
.header("x-trackstar-api-key", "YOUR_API_KEY")
.header("x-trackstar-access-token", "YOUR_ACCESS_TOKEN")
.GET()
.build();
HttpResponse response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println("Status: " + response.statusCode());
System.out.println("Body: " + response.body());
}
}
```
```ruby Ruby theme={null}
require 'net/http'
require 'uri'
url = URI('https://production.trackstarhq.com/wms/inbound-shipments/inbound_shipment_abc123')
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request['x-trackstar-api-key'] = 'YOUR_API_KEY'
request['x-trackstar-access-token'] = 'YOUR_ACCESS_TOKEN'
response = http.request(request)
puts "Status: #{response.code}"
puts "Response: #{response.body}"
```
### Sample Response
```json theme={null}
{
"data": {
"id": "inbound_shipment_abc123",
"warehouse_customer_id": "customer_12345",
"created_date": "2024-01-18T10:00:00Z",
"updated_date": "2024-01-20T15:30:00Z",
"purchase_order_number": "PO-2024-001",
"status": "received",
"raw_status": "fully_received",
"supplier": "ACME001",
"supplier_object": {
"supplier_id": "ACME001",
"supplier_name": "Acme Suppliers Inc"
},
"expected_arrival_date": "2024-01-20T09:00:00Z",
"warehouse_id": "warehouse_main",
"line_items": [
{
"inventory_item_id": "inv_widget001_main",
"sku": "WIDGET-001",
"expected_quantity": 100,
"received_quantity": 100,
"unit_cost": 25.00,
"external_id": "WIDGET-001-ACME"
},
{
"inventory_item_id": "inv_gadget002_main",
"sku": "GADGET-002",
"expected_quantity": 50,
"received_quantity": 50,
"unit_cost": 45.00,
"external_id": "GADGET-002-ACME"
}
],
"receipts": [
{
"id": "receipt_001",
"arrived_date": "2024-01-20T10:15:00Z",
"line_items": [
{
"inventory_item_id": "inv_widget001_main",
"sku": "WIDGET-001",
"quantity": 100
},
{
"inventory_item_id": "inv_gadget002_main",
"sku": "GADGET-002",
"quantity": 50
}
]
}
],
"ship_from_address": {
"address1": "100 Supplier Blvd",
"address2": null,
"address3": null,
"city": "Supplier City",
"state": "CA",
"postal_code": "90210",
"country": "US"
},
"tracking_numbers": ["1234567890"],
"notes": ["Priority shipment - expedite receiving", "All items received in good condition"],
"external_system_url": "https://wms.example.com/inbound/inbound_shipment_abc123",
"trackstar_tags": ["priority", {"supplier": "acme"}],
"additional_fields": {
"supplier_contact": "jane.doe@acme.com",
"special_handling": "fragile"
}
}
}
```
### Real-time Updates
Utilize [webhooks](/how-to-guides/webhooks) to get notified each time there is an update to an ASN by subscribing to `inbound-shipment.updated` and/or `inbound-shipment.receipt.created` events.
## Fetching ASNs
For detailed information about all available inbound shipment statuses and their meanings, see the [Inbound Shipments Info page](/api-reference/wms-api/inbound-shipments/info).