---
title: "Patches contract metadata"
method: PATCH
path: "/contracts/{contract_id}/metadata"
tags: ["Contracts"]
---

# Patches contract metadata

`PATCH /contracts/{contract_id}/metadata`

## Request

- Base URL: `https://api.rillet.com`
- URL: `https://api.rillet.com/contracts/{contract_id}/metadata`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/rillet/apis/rillet-accounting-api/docs/contracts/:contract_id/metadata/patch.ts> (a function with typed inputs; its response is checked against the schema)

Partial update. Keys omitted from the request body are left unchanged; send a key with a
null, empty, or whitespace-only value to clear it. Prefer this over
update-contract-metadata when setting or clearing individual keys, as it cannot disturb
keys you did not name. Archived keys may only be cleared, never changed. Every key must
name a definition assigned to contracts: 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.
A matching contract "Edit or amend" approval rule holds the change: the request answers 202 with the approval request, and the
contract keeps its values until the request is approved. While another change to the contract waits for approval, the request
is refused.

## Path parameters

- `contract_id` string, required

## Request body

- PatchMetadataValuesRequest
  - `metadata` object, required: Values keyed by definition key. A partial update: keys omitted here are left unchanged, and null, empty, or whitespace-only values clear one key. Values are trimmed; TEXT values allow at most 256 characters and no line breaks.

## Response `200`

OK

- union
  - MetadataValues
    - `metadata` object, required: Values keyed by definition key. A key with no value on this record is omitted. Use list-all-metadata-definitions for definition names, types and status.
  - ContractPendingApproval: A new contract, or an update to a contract, waiting for approval instead of being applied.
    - `contract_id` string, uuid, required: The id of the contract. A new contract waits as a draft with this id and keeps it once the request is approved; an updated contract keeps its id.
    - `approval_request_id` string, uuid, required: The approval request the contract waits on.

## Other responses

- `202`: Metadata changes are held for approval; the contract keeps its values until the request is approved.
- `default`: Error

## Changes

- **2026-11-03** `c393d0102005`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/rillet/apis/rillet-accounting-api/changes/contracts/:contract_id/metadata/patch.md)

---

[API](https://skmtc.dev/rillet/apis/rillet-accounting-api.md) - [All operations](https://skmtc.dev/rillet/apis/rillet-accounting-api/llms.txt) - [OpenAPI document](https://skmtc.dev/rillet/apis/rillet-accounting-api/revisions/c393d0102005?raw)