---
title: "Patches bill metadata"
method: PATCH
path: "/bills/{bill_id}/metadata"
tags: ["Bills"]
---

# Patches bill metadata

`PATCH /bills/{bill_id}/metadata`

## Request

- Base URL: `https://api.rillet.com`
- URL: `https://api.rillet.com/bills/{bill_id}/metadata`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/rillet/apis/rillet-accounting-api/docs/bills/:bill_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-bill-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 bills: 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.
Writes are rejected with a 400 while the bill has a pending approval request.

## Path parameters

- `bill_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

- 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.

## Other responses

- `default`: Error

## Changes

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

[Operation history](https://skmtc.dev/rillet/apis/rillet-accounting-api/changes/bills/:bill_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)