A developer-friendly reference dataset for the 11 Incoterms® 2020 rules, available in JSON, CSV, and YAML for procurement, logistics, RFQ, quotation, ERP, B2B, and international-trade software.
Maintained by FirmaPanel, a B2B platform for supplier discovery, private inquiries, quotations, and trade workflows.
Incoterms® and the Incoterms® 2020 logo are trademarks of ICC. Use of these trademarks does not imply association with, approval of or sponsorship by ICC. The Incoterms® Rules are protected by copyright owned by ICC.
This independent project is not affiliated with or endorsed by ICC and is not a substitute for official ICC publications or professional advice.
Simple code-and-name lists are easy to find. Software usually needs more.
Procurement, logistics, RFQ, ERP, and marketplace applications need consistent fields for transport scope, main carriage, cargo insurance, customs clearance, named locations, unloading, risk transfer, filtering, and validation.
This repository turns those needs into a normalized machine-readable model while keeping the descriptions concise, original, and independent from the official ICC publication.
- all 11 rules in the 2020 edition;
- canonical JSON plus generated CSV and YAML;
- a compact machine-readable comparison matrix;
- JSON Schema Draft 2020-12;
- original risk-transfer and buyer/seller summaries;
- explicit transport, carriage, insurance, customs, and unloading fields;
- RFQ, quotation, purchase-order, and dropdown examples; and
- deterministic build and validation tooling with GitHub Actions checks.
| Format | Intended use | File |
|---|---|---|
| JSON | Canonical application and API data | incoterms-2020.json |
| CSV | Spreadsheets, databases, and analysis | incoterms-2020.csv |
| YAML | Human-friendly review and configuration | incoterms-2020.yaml |
| JSON | Compact filtering and comparison | comparison-matrix.json |
The record contract is published as JSON Schema Draft 2020-12. JSON is the source of truth; the other data files are generated and checked for exact consistency.
Clone and validate with Python 3.9 or later:
git clone https://github.com/FirmaPanel/incoterms-reference.git
cd incoterms-reference
python3 scripts/validate.pyRead the canonical JSON in Python:
import json
from pathlib import Path
rules = json.loads(
Path("data/incoterms-2020.json").read_text(encoding="utf-8")
)
fca = next(rule for rule in rules if rule["code"] == "FCA")
print(fca["risk_transfer_summary"])Or query the published file without cloning:
curl -fsSL \
https://raw.githubusercontent.com/FirmaPanel/incoterms-reference/main/data/incoterms-2020.json \
| jq '.[] | select(.code == "FCA")'For production use, pin a tagged release or vendor the data instead of tracking
the moving main branch.
| Code | Rule name |
|---|---|
| EXW | Ex Works |
| FCA | Free Carrier |
| CPT | Carriage Paid To |
| CIP | Carriage and Insurance Paid To |
| DAP | Delivered at Place |
| DPU | Delivered at Place Unloaded |
| DDP | Delivered Duty Paid |
| Code | Rule name |
|---|---|
| FAS | Free Alongside Ship |
| FOB | Free On Board |
| CFR | Cost and Freight |
| CIF | Cost, Insurance and Freight |
Transport compatibility alone does not select the right rule for a transaction. See transport modes for the containerized-shipment caveat and other implementation guidance.
A complete record looks like this:
{
"code": "FCA",
"name": "Free Carrier",
"version": "2020",
"transport_scope": "any-mode",
"seller_arranges_main_carriage": false,
"buyer_arranges_main_carriage": true,
"seller_arranges_insurance": false,
"buyer_arranges_insurance": null,
"seller_arranges_export_clearance": true,
"buyer_arranges_import_clearance": true,
"seller_pays_unloading_at_destination": false,
"delivery_location_type": "named-place",
"named_place_required": true,
"risk_transfer_summary": "At the seller's premises, risk passes after loading onto the buyer's collecting vehicle; at another agreed place, it passes when the goods arrive ready for unloading and are available to the buyer's nominated carrier or person.",
"buyer_summary": "The buyer normally nominates the carrier, arranges the main carriage from the delivery point, and completes import clearance.",
"seller_summary": "The seller delivers at the agreed point under the applicable loading condition and completes export clearance where required.",
"containerized_goods_note": "Often suitable when containers are handed to a carrier or terminal before vessel loading.",
"recommended_for_containerized_goods": true,
"notes": [
"Loading responsibility changes according to whether the agreed place is the seller's premises or another location.",
"The parties should identify a precise point within the named place."
]
}Read the field reference before consuming nullable booleans.
Here, null is meaningful: it indicates that a simplified mandatory yes/no
answer would be misleading, not that data is missing.
Store a code together with the edition and a precise named place or port:
{
"incoterm": {
"code": "FCA",
"version": "2020",
"named_place": "Bursa, Türkiye"
}
}This model can support:
- controlled selectors in RFQ and supplier quotation forms;
- checks that a code belongs to the expected transport family;
- warnings when supplier quotes use commercially different delivery terms;
- purchase-order and ERP master-data validation;
- logistics filters and documentation systems; and
- structured retrieval for search and AI applications.
See the integration guide and the working examples for practical patterns.
Cost, delivery, and risk are separate concepts. In particular, a seller can pay
carriage to a named destination while risk transfers much earlier. The dataset
therefore avoids a broad seller_pays field and does not calculate landed cost.
It also does not offer a “which rule should I use?” engine. That decision needs shipment, contract, payment, insurance, customs, local-law, and transport-chain context that a small reference record cannot supply.
incoterms-reference/
├── data/ # Canonical data and generated exports
├── docs/ # Field and integration documentation
├── examples/ # RFQ, quotation, PO, and UI payloads
├── schema/ # JSON Schema contract
├── scripts/ # Build and validation utilities
├── .github/ # CI and contribution templates
├── ATTRIBUTION.md
├── CHANGELOG.md
├── CITATION.cff
├── LICENSE
├── NOTICE.md
├── SOURCES.md
└── README.md
After editing the canonical JSON, regenerate all derived views:
python3 scripts/build_exports.py
python3 scripts/validate.pyRun the full standards-based check used in CI:
python3 -m pip install -r requirements-dev.txt
make checkThe core build and integrity checks use only the Python standard library. Development dependencies add JSON Schema and YAML semantic validation.
- Field reference
- Transport modes
- Responsibility fields
- Comparison matrix
- Integration guide
- Sources and methodology
- Disclaimer
To cite the archived v1.0.0 dataset:
FirmaPanel. (2026). FirmaPanel Reference Data for the Incoterms® 2020 Rules (Version 1.0.0) [Data set]. Zenodo. https://doi.org/10.5281/zenodo.22550404
Machine-readable citation metadata is available in
CITATION.cff.
Corrections, clearer original descriptions, integration examples, and tooling improvements are welcome. Read CONTRIBUTING.md and the Code of Conduct before opening a pull request.
Do not submit copied ICC text, proprietary training material, or unreviewed AI-generated descriptions. Factual changes should include an authoritative source for reviewers.
FirmaPanel's original dataset structure, descriptions, examples, and
documentation are available under the
Creative Commons Attribution 4.0 International License. Maintenance
utilities in scripts/ are available under the MIT License.
The preferred attribution is:
FirmaPanel Reference Data for the Incoterms® 2020 Rules by FirmaPanel, available from github.com/FirmaPanel/incoterms-reference, licensed under CC BY 4.0.
See ATTRIBUTION.md and NOTICE.md. Neither license grants rights in ICC trademarks or official publications.
This dataset is general informational material. It is not legal, customs, tax, insurance, logistics, compliance, or other professional advice. Consult the official ICC publication and qualified advisers before using a rule in a contract. See the full disclaimer.
FirmaPanel connects B2B product discovery with private buyer inquiries, supplier quotations, and trade tracking. This repository is maintained as an open reference for the wider procurement, logistics, and international-trade software community.