---
title: "Updates invoice metadata"
method: PUT
path: "/invoices/{invoice_id}/metadata"
tags: ["Invoices"]
---

# Updates invoice metadata

`PUT /invoices/{invoice_id}/metadata`

## Request

- Base URL: `https://api.rillet.com`
- URL: `https://api.rillet.com/invoices/{invoice_id}/metadata`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/rillet/apis/rillet-accounting-api/docs/invoices/:invoice_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-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.

## Path parameters

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

- 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.
  - InvoiceUpdateProposal: Proposed edits awaiting approval. These changes have not been applied to the invoice.
    - `invoice_id` string, uuid, required
    - `approval_request_id` string, uuid, required
    - `status` 'PENDING', required

## Other responses

- `202`: Metadata changes are held for approval; effective values are unchanged.
- `default`: Error

## Changes

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

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