TracePass passports
tracepass_passportsManage Digital Product Passports — create, read, and run lifecycle actions.
IMPORTANT: create consumes a DPP slot on the account's plan and IS BILLABLE. Creating a passport beyond the included quota incurs a per-passport overage charge; if over quota the tool returns a 402-style message — only re-run with args.confirmOverage=true after the user explicitly agrees to the charge. archive is IRREVERSIBLE (the public QR permanently 404s); prefer suspend when a change might be undone.
Actions (pass via action, with args):
list — args: { page?, limit? (≤100), productId?, status?, search? }. status ∈ draft|in_review|approved|published|suspended|expired|archived. Read-only.
get — args: { id, format? (summary|full), lang? }. Read-only.
get_by_serial — args: { serial, format?, lang?, gtin? }. Read-only. Addresses the passport by your own serial. A serial is unique only WITHIN a GTIN — if the same serial exists under two GTINs in your account the call returns 409 ambiguous_serial; pass
gtin(or use the by-id action) to resolve exactly.compliance — args: { id }. Read-only. Returns a three-tier compliance verdict (compliant | compliant_with_warnings | incomplete) with regulation-cited findings — use to gap-check a passport against the rules for its category, fix the cited fields/parties, then re-check.
registry_readiness — args: { id }. Read-only. Returns { ready, findings[] } — whether the passport would pass the EU DPP Registry's FORMAL submission gate (mandatory fields present, correct formatting, a resolvable public link, item-level granularity via a serial number, and a well-formed commodity code where the category carries one). This is the registry's mechanical pre-submission check, NOT the substantive compliance verdict; a passport can be registry-ready yet not substantively compliant. Battery passports only.
create — args: { productId, gtin, serialNumber, confirmOverage? }. BILLABLE.
suspend — args: { id }. Reversible — public QR shows 'suspended'.
suspend_by_serial — args: { serial, gtin? }. Same as suspend, addressed by your serial. 409 ambiguous_serial if the serial isn't unique in your account — pass
gtin.archive — args: { id }. IRREVERSIBLE — confirm with the user first.
archive_by_serial — args: { serial, gtin? }. IRREVERSIBLE, addressed by your serial — confirm first. 409 ambiguous_serial if the serial isn't unique — pass
gtin.get_qr — args: { id, format? (svg|png) }. Read-only.
get_qr_by_serial — args: { serial, format? (svg|png), gtin? }. Read-only. Same as get_qr, addressed by your own serial. A serial is unique only WITHIN a GTIN — if the same serial exists under two GTINs in your account the call returns 409 ambiguous_serial; pass
gtin(or use get_qr by id) to resolve exactly.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| args | No | Arguments for the chosen action; required fields depend on `action` (see each action above). | |
| action | Yes | Which passport operation to run. Reads: list | get | get_by_serial | compliance | registry_readiness | get_qr | get_qr_by_serial. Lifecycle: create (BILLABLE) | suspend (reversible) | archive (IRREVERSIBLE), each with a _by_serial variant. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| id | No | The resource's TracePass id, when the response is a single entity. | |
| page | No | Current page number (list actions). | |
| error | No | Machine-readable error code, when the API rejected the request. | |
| items | No | The page of results, when the action is a list. | |
| limit | No | Page size (list actions). | |
| total | No | Total matching records across all pages (list actions). | |
| result | No | Wraps a non-object response body (e.g. a QR code string). | |
| message | No | Human-readable error or status detail, when present. | |
| totalPages | No | Total number of pages (list actions). |