IMPORTANT: This is a full-replace operation (PUT semantics). Every active metadata key
omitted from the request body is cleared. To set or clear individual keys without
disturbing the rest, use patch-invoice-metadata instead. Null, empty, and
whitespace-only values clear a single key. Archived keys may only be cleared, never changed.
Every key must name a definition assigned to invoices: an unknown key, or one assigned
only to another entity type, fails the request with a 400. Keys are never silently
ignored. The write is atomic: if any key fails validation, nothing is written.