---
title: "Set or clear condition flags (by serial)."
method: PATCH
path: "/api/v1/passports/by-serial/{serial}/condition-flags"
tags: ["Passports"]
---

# Set or clear condition flags (by serial).

`PATCH /api/v1/passports/by-serial/{serial}/condition-flags`

## Request

- Base URL: `https://app.tracepass.eu`
- URL: `https://app.tracepass.eu/api/v1/passports/by-serial/{serial}/condition-flags`
- 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 contract as
`PATCH /api/v1/passports/{id}/condition-flags`, addressed
by your own serial number. See the by-id operation for the
full warning about flag approval making fields required and
potentially blocking publishing.

Supports `Idempotency-Key`. Counts as one v1 write.

## Request body

- ConditionFlagsPatch: Partial update for the condition profile. Each key must be registered for the passport's category (unknown keys return 400). Set a flag with `true`/`false`; clear it with `null`. Provide at least one key.

## Response `200`

Condition profile after the update.

- object
  - `passportId` string, required: MongoDB ObjectId hex string (24 chars).
  - `conditionProfile` ConditionProfile, required: A map of flagKey → ConditionFlag representing the resolved condition profile for a passport. Valid flag keys are category-specific: `battery` supports `hasBMS`, `rechargeable`, `externalStorageOnly`, and `isStationaryBess`. Categories with no flags return an empty object. The `audit` array is stripped from v1 responses.
  - `version` integer, required

## Other responses

- `400`: Validation error or malformed request.
- `401`: Missing or invalid API key.
- `402`: The subscription is past due, unpaid or canceled. Creating new content is blocked until billing is resolved; published passports stay accessible.
- `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`: Idempotency-Key reused with a different request body. Use a new key for the new request, or reuse the original body.
- `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)