TracePass
Get started
Passports

Suspend a passport

Reversible suspend. The public viewer flips to the suspended state page (HTTP 423 with structured body); QR scans effectively die without the URL going to 404. Use for recalls, disputes, internal holds, or product-quality investigations. Republish from the dashboard once resolved.

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

Suspend a passport

Reversible suspend. The public viewer flips to the suspended state page (HTTP 423 with structured body); QR scans effectively die without the URL going to 404. Use for recalls, disputes, internal holds, or product-quality investigations. Republish from the dashboard once resolved.

Optional body `{ reason: string }` — surfaces in the `passport.suspended` webhook payload and the dashboard audit trail (truncated at 500 chars). Empty body is fine; the suspend still fires the webhook. Counts as one v1 write. Honours `Idempotency-Key`. The matching `POST /api/v1/passports/by-serial/{serial}/suspend` is the by-serial alternate.

Path parameters

  • idrequired

    ObjectId

    Passport ID.

Headers

  • Authorizationrequired

    string

    `Bearer <api-key>`.

  • Idempotency-Key

    string

    UUID v4.

Body fields

  • reason

    string (≤ 500)

    Free-text suspension reason.

    e.g. Quality investigation pending — batch BB-2026-04-12.

Request

curl -sS -X POST \
  https://app.tracepass.eu/api/v1/passports/6650b2c3d4e5f6a7b8c9d0e1/suspend \
  -H "Authorization: Bearer tp_REDACTED_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "Quality investigation pending — batch BB-2026-04-12." }'

Response

{
  "_id": "6650b2c3d4e5f6a7b8c9d0e1",
  "status": "suspended",
  "suspendedAt": "2026-05-09T16:00:00.000Z",
  "suspensionReason": "Quality investigation pending — batch BB-2026-04-12."
}

Related endpoints