Regulatory boundary

Availability

The Integration API (Phase 1 core and Phase 1.5 endpoints) is GA on production (app.traceable.digital) as of v0.99.6.1. The API returns 503 FEATURE_DISABLED on any environment where it is not enabled. See Availability.

The Integration API is designed around the obligations imposed by EU Battery Regulation 2023/1542 (and its implementing acts). This page explains the regulatory constraints that shape what the API can and cannot do, and why some of those constraints are deliberate design choices, not merely Phase 1 limitations.

The API cannot publish

Every write through the Integration API terminates at Submitted status. There is no API call that transitions a DPP to Approved or Published.

The portal user whose action publishes the DPP is recorded as the actor of the publication entry in the audit trail. That record shows who performed the publication; it does not make that person responsible for the passport information, which Art. 77(4) places on the economic operator placing the battery on the market (see below).

There is no dpp:publish scope in Phase 1: publication is deliberately a human action in the portal today. (A future phase may introduce operator-controlled publish-via-API; it is not available today.)

Art. 77(4): Economic operator responsibility

The Economic Operator (typically the battery manufacturer or EU-market importer) is the entity legally responsible for the DPP. This is the company whose Traceable operator account holds the Integration API key. Data written through the API is attributed to that operator account, not to the third-party ERP system or integration vendor that makes the API call.

If your integration writes incorrect data to a DPP, the economic operator (your customer) is the party whose compliance record reflects that data. Ensure your field mapping and data quality controls are robust before submitting for review.

Attribution and audit trail

Writes through the Integration API are recorded in the platform audit trail with attribution to the named person who minted the API key. The audit trail records are linked by a hash chain. If a key is shared across multiple systems or users, the attribution granularity is limited to the key holder.

Recommendation: mint a separate key for each integration point and name each key to identify its source (e.g. odoo-prod-erp, plm-system). This preserves per-system attribution in the audit trail.

Annex XIII: Field completeness at submission

The EU Battery Regulation Annex XIII sets out the information to be included in the battery passport, which Art. 77(1) requires for each LMT battery, each industrial battery with a capacity greater than 2 kWh and each electric vehicle battery; SLI and portable batteries have no passport obligation. The API enforces the platform's mandatory-field set for the product's category (EV, LMT, Industrial, Stationary, SLI, Portable) at the submit step. A 422 SUBMIT_BLOCKED response lists the specific mandatory fields that are missing.

The gate is date-aware: it does not block a field whose underlying obligation has not yet reached its compliance date under the Regulation. Carbon footprint (Art. 7(1), suspended pending the implementing act per the Commission's 28 July 2026 data-points guidance, for all categories including EV), supply chain due diligence (Art. 48, postponed by Regulation (EU) 2025/1561), and the recycled-content declarations (per the guidance's 15 August 2026 update) are the obligation groups this currently affects; see Enforcement timeline for the exact dates per category. Two things stay constant regardless of date:

• Suspension is dated, not permanent. Each suppressed obligation carries its recorded resume date, and blocking resumes automatically on that date. Data a caller does submit in a suspended section is still validated for internal consistency.
• An unresolved or unknown battery category fails closed. If the gate cannot determine which category a product belongs to, it treats every mandatory field as blocking rather than assuming a date-gated obligation does not apply.

For voluntary-scope categories (SLI, portable, industrial ≤2 kWh), which have no Art. 77(1) passport obligation, the gate additionally applies the voluntary rule-set: only a fixed safety and consumer-information keep-list of fields remains required, and the gap list a GET /products/{id}/gate call returns reflects that reduced set.

The gate endpoint (GET /api/v1/products/{id}/gate) provides the same check before submission so you can surface gaps to your user early, rather than discovering them at submit time. A field that is not yet due appears in the gate response as informational, not as a blocking gap.

Do not retry-loop on a 422 SUBMIT_BLOCKED. The list of missing fields does not change until you supply the missing data through PATCH or document upload, or until a date-gated obligation's compliance date arrives.

GTIN and GS1 registration (platform rule)

For EV, LMT, Industrial (>2 kWh) and Stationary products, a GTIN is required for publication on Traceable. For Industrial (2 kWh or less), SLI and Portable products the gate does not require one. Whenever a GTIN is entered, the gate flags it if it does not begin with one of your company's registered GS1 prefixes, and publication is blocked for any company with no verified GS1 prefix. These are Traceable rules, not requirements of the Regulation: no provision requires a GTIN or GS1 registration, and Art. 77(3) requires the QR code and the unique identifier to comply with the ISO/IEC 15459 standards or their equivalent.

Operators manage their GS1 prefix registration in the Traceable portal under Settings → GS1 Prefixes. Through the API you can declare prefix claims, but the licence upload that verification needs is available in the portal only. The API does not mint GS1 prefixes or verify them.

Carbon footprint methodology

For battery categories where a carbon footprint declaration is mandatory, EU Battery Regulation 2023/1542 requires the value to be calculated using the methodology set out in the Commission's implementing measures (life-cycle based, with the prescribed system boundary and reference values). The carbon footprint is more than a number: it is a declaration computed a specific way.

The Integration API ingests the declared carbon footprint value and its supporting fields (for example the methodology reference and any verification details) as data. It does not compute the carbon footprint for you, and it does not certify that your calculation followed the prescribed methodology. Responsibility for using the correct methodology rests with the economic operator. As with every other field, the value is evaluated downstream by the publish gate and the human reviewer, not validated by the act of ingestion. Submit the figure you have calculated and declared, not a placeholder.

EU data residency and GDPR

All DPP data written through the Integration API is stored within EU data centres. The data residency policy for Traceable is described in the GDPR and Data Processing section of this guide.

Language requirements

Art. 77, Art. 78 and Annex XIII set no language requirement of their own. However, two items the battery passport must contain carry one from their source provision. The first is the EU declaration of conformity (Annex XIII, point 1(r)), which Art. 18(2) requires to be translated into the language or languages required by the Member State. The second is the waste-battery information in Art. 74(1), points (a) to (f) (Annex XIII, point 1(s)), which must be in a language or languages determined by the Member State. Language rules also apply outside the passport, to the instructions and safety information and the manufacturer's contact details (Art. 38(1) and (7)). The Integration API accepts data in any language. Ensuring that these fields meet the applicable language requirements is the responsibility of the economic operator.

No compliance claims by proxy

Ingesting data through the Integration API does not constitute a claim that the data meets EU Battery Regulation requirements. Regulatory conformance is evaluated by:

1. The publish gate (automated field completeness check against Annex XIII)
2. The human reviewer in the Traceable portal
3. The verifier (where applicable) who signs off on specific technical claims

The act of submitting data through the API is a data transfer. The act of publishing a DPP is a regulatory declaration made by the economic operator. These are distinct steps for a reason.

Withdrawal

Withdrawing a published DPP is available over the API as of Phase 1.5: POST /api/v1/products/{id}/withdraw (dpp:withdraw). After withdrawal, the public DPP stays online as an archived passport (except a passport withdrawn as counterfeit, which shows a notice only): it answers HTTP 200 with an availability block and the header X-DPP-Availability: archived. Withdrawal uses its own least-privilege scope, separate from dpp:submit, so you can grant the ability to pull a passport without granting the ability to submit one. This endpoint is GA on production as of v0.99.6.1; see Availability.

There is no single article that withdrawal happens "under". The legal basis depends on the withdrawal reason you supply, and for the six commercial reasons (end of life, market withdrawal, supersession, customer complaint, operator request, and informal regulatory direction), the platform asserts no regulatory basis, because citing one would publicly claim a non-conformity that did not occur, to an audience that includes market-surveillance authorities. Where a basis does apply, the withdrawn passport page states it.

Withdrawing because of a regulatory directive

Use the reason RegulatoryDirective when an authority has directed you informally to take a passport out of use. The platform records the directive. It does not notify the authority and it does not treat the directive as a formal order.

A RegulatoryDirective request carries three more fields, all flat in the request body:

Field	Required	What it holds
freezeOrdered	Yes	true or false: whether the directive orders the battery data frozen. It must be a boolean.
directiveAuthority	Yes	The authority that issued the directive. After trimming, 2 to 120 characters. It starts with a letter or digit, ends with a letter, digit, . or ), and in between holds only letters, digits, spaces and . , ' & ( ) / -.
directiveReference	No	The directive's reference number, for example Az.: 52-8856.30. After trimming, 1 to 64 characters. It starts and ends with a letter or digit, and in between holds only letters, digits, spaces and . / _ : , ( ) -.

For every other reason, send none of the three or send them as null. A request that sends one with another reason is refused.

{
  "reason": "RegulatoryDirective",
  "details": "Withdrawn following an informal request from the authority.",
  "freezeOrdered": true,
  "directiveAuthority": "Example Market Surveillance Authority",
  "directiveReference": "Az.: 52-8856.30"
}

A missing, malformed or misplaced field answers 400 with the code VALIDATION_ERROR, and the message names each problem. See Errors and conventions.

What freezeOrdered changes:

• true: the product stops accepting battery management system (BMS) updates. POST /api/v1/products/{id}/bms-update and its batch route answer 410 with PRODUCT_FROZEN. See BMS endpoints.
• false: BMS updates keep being accepted.
• Nothing else changes. The freeze does not lock the passport, its content or its edits, and it does not change what the public passport shows. A withdrawal made under a directive before the platform recorded this answer is treated as frozen.

The authority and the reference are stored with the withdrawal and written to the audit trail. They are not shown on the public passport, in its machine-readable data, or in the withdrawal webhook and email. The free-text details you send is different: the passport's withdrawal notice shows it, so write it for the public.

The freeze has no separate switch. It ends when you republish the passport, which needs the Approver role or above in the portal and an open edit window, or when you withdraw the product again with a new answer. Republishing takes the product out of the withdrawn state, so the freeze stops applying, but it does not erase the record: the answer, the authority and the reference stay with the withdrawal and in the audit trail. A new withdrawal replaces all three fields, and for any reason other than RegulatoryDirective they become empty.

Amendments to already-published data remain operator actions in the portal. A submitted DPP that a reviewer returns for revision can be updated via PATCH while it is in Draft state.