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

# Updates bill metadata

`PUT /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/put.ts> (a function with typed inputs; its response is checked against the schema)

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

- UpdateMetadataValuesRequest
  - `metadata` object, required: Values keyed by definition key. A full replacement: every active key omitted here is cleared, 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/put.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)