---
title: "Suspend a passport (by serial)."
method: POST
path: "/api/v1/passports/by-serial/{serial}/suspend"
tags: ["Passports"]
---

# Suspend a passport (by serial).

`POST /api/v1/passports/by-serial/{serial}/suspend`

## Request

- Base URL: `https://app.tracepass.eu`
- URL: `https://app.tracepass.eu/api/v1/passports/by-serial/{serial}/suspend`
- Auth: one of:
  - HTTP bearer
  - OAuth 2 (authorization code, authorization URL `https://app.tracepass.eu/api/oauth/authorize`, token URL `https://app.tracepass.eu/api/oauth/token`, scopes: `passports:write`)

Same shape as POST `/api/v1/passports/{id}/suspend`.

## Request body

- object
  - `reason` string

## Response `200`

Suspended.

- Passport
  - `_id` string: MongoDB ObjectId hex string (24 chars).
  - `companyId` string: MongoDB ObjectId hex string (24 chars).
  - `productId` string: MongoDB ObjectId hex string (24 chars).
  - `templateId` string: MongoDB ObjectId hex string (24 chars).
  - `identifier` union
    - object: GS1 GTIN + serial number (scheme "gs1"). Required for battery passports.
      - `scheme` 'gs1', required
      - `gtin` string, required: GS1 GTIN with a valid check digit. Accepts 8 digits (GTIN-8), 12 digits (GTIN-12/UPC-A), 13 digits (GTIN-13/EAN-13), or 14 digits (GTIN-14). All forms are left-padded to 14 digits before storage; stored and returned values are always 14 digits.
      - `serialNumber` string, required
      - `digitalLinkUri` string, uri
    - object: ISO/IEC 15459 identifier (scheme "iso15459"). Also valid for battery passports.
      - `scheme` 'iso15459', required
      - `issuingAgencyCode` string, required
      - `primaryId` string, required
      - `serial` string
      - `raw` string: The ISO/IEC 15459 unique identifier: issuing agency code + primary id + serial, concatenated. Always derived by the server from the parts; a value sent on create is ignored. Present on every read.
      - `uri` string, uri: The ISO/IEC 18975 Data-Identifier query-form resolver URL generated by the server, following EN 18219 Table B.12: `https://id.tracepass.eu/?.25P=<IAC><primaryId>&.S=<serial>` (`.S` component omitted when there is no serial; parameter values are percent-encoded). Always derived by the server from the identifier parts; present on every read.
    - object: IEC 61406 Identification Link — an https URI (scheme "iec61406"). Not valid for battery passports (Battery Regulation Art. 77(3) requires gs1 or iso15459).
      - `scheme` 'iec61406', required
      - `uri` string, uri, required
    - object: W3C DID Core identifier (scheme "did"). Not valid for battery passports (Battery Regulation Art. 77(3) requires gs1 or iso15459).
      - `scheme` 'did', required
      - `did` string, required
      - `method` string, required
    - object: Digital Object Identifier — ISO 26324 (scheme "doi"). Stored as bare `10.<registrant>/<suffix>`. Any `https://doi.org/` or `doi:` prefix is stripped on input; the DOI resolves as `https://doi.org/<doi>`. `granularity` is REQUIRED per EN 18219 §5.6.2(b): a DOI product identifier must declare whether it identifies the product model, a production batch, or an individual item. Not valid for battery passports (Battery Regulation Art. 77(3) requires gs1 or iso15459).
      - `scheme` 'doi', required
      - `doi` string, required
      - `granularity` 'model' | 'batch' | 'item', required: Whether the DOI identifies the product model, a production batch, or an individual item (EN 18219 §5.6.2(b)). Must be supplied on create; returned unchanged on read.
  - `identifierKey` string: Canonical dedup key in `<scheme>:<parts>` form, e.g. `gs1:00012345678905:SN-001` or `did:did:example:123`. Globally unique (sparse index) — the same identifier cannot exist across different accounts.
  - `gs1` GS1Block
    - `gtin` string, required: GS1 GTIN with a valid check digit. Accepts 8 digits (GTIN-8), 12 digits (GTIN-12/UPC-A), 13 digits (GTIN-13/EAN-13), or 14 digits (GTIN-14). All forms are left-padded to 14 digits before storage; stored and returned values are always 14 digits.
    - `serialNumber` string, required
    - `digitalLinkUri` string, uri
  - `status` 'draft' | 'in_review' | 'approved' | 'published' | 'suspended' | 'expired' | 'archived'
  - `completionPercentage` integer
  - `fieldCounts` object
    - `total` integer
    - `empty` integer
    - `approved` integer
    - `pendingReview` integer
    - `flagged` integer
  - `fields` object
  - `parties` PartyMap: Map of role → Party. Each role appears at most once.
  - `lineage` PassportLineage: The stored, immutable lineage block of a successor battery passport.
    - `predecessors` object[]
      - `identifier` string
      - `trigger` 'preparation_for_reuse' | 'preparation_for_repurposing' | 'repurposing' | 'remanufacturing': The Art. 77(7) operation that produced the successor battery.
      - `internalPassportId` string: MongoDB ObjectId hex string (24 chars).
    - `noPredecessorReason` string
  - `dynamicDataAsOf` string, date-time, nullable: `measuredAt` of the newest battery measurement applied to this passport; null before the first one. Returned with `format=full`.
  - `successors` PassportSuccessor[]: Forward links to successor passports created from this one (same account only). Never changes this passport's fields.
    - `passportId` string: MongoDB ObjectId hex string (24 chars).
    - `identifier` string: Canonical resolvable URI of the successor passport.
    - `addedAt` string, date-time
  - `publishedAt` string, date-time
  - `suspendedAt` string, date-time
  - `suspensionReason` string
  - `archivedAt` string, date-time
  - `createdAt` string, date-time
  - `updatedAt` string, date-time

## Other responses

- `401`: Missing or invalid API key.
- `404`: Resource doesn't exist or is in a different workspace.
- `409`: The serial maps to more than one passport in your account (serials are unique per GTIN, not per account). The request is rejected rather than acting on the wrong passport. Pass `?gtin=<gtin>` to disambiguate, or address the passport by its id instead. `count` is how many passports the serial matched.
- `422`: Wrong status to suspend from.
- `429`: Daily v1 write or passport-read budget exhausted. Resets at 00:00 UTC.

---

[API](https://skmtc.dev/tracepass/apis/tracepass-api.md) · [All operations](https://skmtc.dev/tracepass/apis/tracepass-api/llms.txt) · [OpenAPI document](https://skmtc.dev/tracepass/apis/tracepass-api/revisions/60ddeb25638b?raw)