TracePass
Get started
Passports

Archive a passport (irreversible)

Irreversible. Public viewer returns 404, the GS1 Digital Link URL stops resolving and the QR code dies for good, unless the passport has been forwarded to a new provider. Use ONLY for products that never shipped — archiving a passport for a product already in customers' hands breaks every QR scan they'll ever make of it.

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

Archive a passport (irreversible)

Irreversible. Public viewer returns 404, the GS1 Digital Link URL stops resolving and the QR code dies for good, unless the passport has been forwarded to a new provider. Use ONLY for products that never shipped — archiving a passport for a product already in customers' hands breaks every QR scan they'll ever make of it.

The HTTP method is POST and the path includes the literal archive segment — both intentional friction. To take a passport off the API and every public surface instead, delete it in two steps: POST /api/v1/passports/{id}/mark-for-deletion, then DELETE /api/v1/passports/{id}. A passport marked for deletion cannot be archived (409 passport_already_marked_for_deletion). Counts as one v1 write. Honours Idempotency-Key. Fires the passport.archived webhook. Idempotent: calling archive on an already-archived passport returns 200.

Battery passports need a reason. Under the Battery Regulation a battery passport ends only once the battery has been recycled (Art. 77(8)), so archiving one names why: recycled, never_placed (never placed on the market) or duplicate_or_error. Without one, a battery passport answers 400 reason_required. For other categories the body is optional; a reason, when given, must be one of the same three values. The reason is carried in the passport.archived webhook payload. POST /api/v1/passports/by-serial/{serial}/archive takes the same body.

never_placed is refused on a placed passport. A passport registered as placed on the market answers 409 reason_contradicts_placement for that reason. recycled and duplicate_or_error stay available.

Path parameters

  • idrequired

    string (24 hex chars)

    Passport ID.

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

  • reason

    enum

    recycled, never_placed or duplicate_or_error. Required for battery passports, optional for other categories.

    e.g. never_placed

Request

curl -sS -X POST \
  https://app.tracepass.eu/api/v1/passports/6650b2c3d4e5f6a7b8c9d0e1/archive \
  -H "Authorization: Bearer tp_REDACTED_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "never_placed" }'

Response

{
  "_id": "6650b2c3d4e5f6a7b8c9d0e1",
  "status": "archived",
  "archivedAt": "2026-05-09T17:00:00.000Z",
  "archiveReason": "never_placed"
}

Related endpoints