TracePass
Get started
Passports

Record the EU DPP Registry result for a battery passport

Records what the economic operator reports from the EU DPP Registry website for one published **battery** passport. TracePass records the operator's statement and does not verify it with the Registry. The body takes one of two shapes, chosen by `environment`.

POST/api/v1/passports/{id}/registration
Download OpenAPI 3.1
POST/api/v1/passports/{id}/registration

Record the EU DPP Registry result for a battery passport

Records what the economic operator reports from the EU DPP Registry website for one published **battery** passport. TracePass records the operator's statement and does not verify it with the Registry. The body takes one of two shapes, chosen by `environment`.

**`environment: "production"`** — the passport is registered in the production Registry. Sets `placeOnMarketStatus: "placed"`, `registrationMode: "website"`, `placedOnMarketAt` and, if you send it, `registrationId` (the Registry's registration identifier, at most 200 characters). `placedOnMarketAt` is the date of placing on the market as `YYYY-MM-DD`: today by default, not in the future and not before the passport was first published. The operator and facility parties lock (a party write that would change a stored identifier answers 409 `operator_locked`), the passport's backup copy is queued and the `passport.placed_on_market` webhook fires.

**`environment: "acceptance"`** — a test in the Registry's acceptance environment: `result` is `passed` or `failed`, with the Registry's `errorCode` for a failure (at most 100 characters, e.g. `SEMANTIC_VALIDATION_UNAVAILABLE`). A test has no legal effect and changes nothing on the passport but `registryAcceptanceTest`.

**Refusals:** `400` for a body that fails validation or a refused date (`invalid_date` when it is not `YYYY-MM-DD`, `date_in_future`, `date_before_publication`, `registration_id_too_long`); `409` for `not_a_battery`, `not_published` or, for production, `already_registered` (the passport is already placed or being sent to an EN 18222 registry). A mistaken record is undone with `DELETE /api/v1/passports/{id}/registration`.

**Paid plans only** (`402` on Free). OAuth callers must act for an admin or owner. Returns the passport after the record. Counts as one v1 write, and only when the call succeeds. Honours `Idempotency-Key`.

Path parameters

  • idrequired

    string (24 hex chars)

    Passport ID of a published battery passport.

Headers

  • Authorizationrequired

    string

    `Bearer <token>` — either a `tp_` API key (Developer → API Keys; simplest, for server-to-server) or an OAuth 2.0 access token (Developer → OAuth Apps; for user-authorized apps, scoped + revocable). The Authentication page has the full OAuth flow and scope list.

    e.g. Bearer tp_REDACTED_xxxxxxxxxxxx

  • Idempotency-Key

    string

    UUID v4.

Body fields

  • environmentrequired

    "production" | "acceptance"

    Which Registry environment the result comes from. `acceptance` is a test with no legal effect.

    e.g. production

  • placedOnMarketAt

    string (YYYY-MM-DD)

    Production only. The date of placing on the market. Defaults to today; not in the future, not before the passport was first published.

    e.g. 2027-03-01

  • registrationId

    string (≤ 200 chars)

    Production only. The Registry's registration identifier, if you have it.

    e.g. URI-000-00-000

  • result

    "passed" | "failed"

    Acceptance only, and required there. The outcome of the test.

    e.g. failed

  • errorCode

    string (≤ 100 chars)

    Acceptance only. The Registry's error code for a failed test.

    e.g. SEMANTIC_VALIDATION_UNAVAILABLE

Request

curl -sS -X POST \
  https://app.tracepass.eu/api/v1/passports/6650b2c3d4e5f6a7b8c9d0e1/registration \
  -H "Authorization: Bearer tp_REDACTED_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 9e3b6c28-1f7a-4d52-b0e4-6a8c2d1f5b97" \
  -d '{ "environment": "production", "placedOnMarketAt": "2027-03-01", "registrationId": "URI-000-00-000" }'

Response

{
  "passport": {
    "_id": "6650b2c3d4e5f6a7b8c9d0e1",
    "status": "published",
    "placeOnMarketStatus": "placed",
    "registrationMode": "website",
    "placedOnMarketAt": "2027-03-01T00:00:00.000Z",
    "registrationId": "URI-000-00-000",
    "registryUpi": "https://id.tracepass.eu/01/04012345000016/21/A1B2C3",
    "registrationPreparedAt": "2027-02-26T09:12:00.000Z",
    "registrationPreparedVia": "form"
  }
}

Related endpoints