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

# Patches invoice metadata

`PATCH /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/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-invoice-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 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

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