Invoice Metadata

Overview

Context and purpose

Examples include order IDs, customer references, project codes, campaign IDs, source channels, and custom attributes. Metadata should not replace core invoice fields and should not contain secrets, raw payment credentials, private keys, or sensitive data that downstream systems cannot adequately protect. Metadata is often represented as key-value pairs and passed through APIs, webhooks, exports, or provider dashboards. Naming, type, length, and allowed characters should be documented. The merchant should know whether metadata is customer-visible, searchable by provider staff, copied to callbacks, or retained after invoice deletion. Mutable metadata can support workflow updates, but changes should not alter the legal or financial meaning of an issued invoice without a formal revision. Risks include personal-data leakage, inconsistent schemas, key collisions, untrusted values used in queries or logs, and integrations depending on undocumented provider behavior. Systems should define namespace, schema, ownership, visibility, validation, retention, versioning, indexing, and propagation to payment and accounting records.

How it works

Metadata stores additional business context alongside an invoice, such as order references or internal campaign tags, without redefining its financial amount or payment status. It should be treated as structured data with explicit access and retention rules.

Practical checks and failure points

Avoid putting personal secrets into public payment URLs or webhook payloads. Validate length, type and tenant scope; never trust arbitrary client metadata to change pricing.

Related concepts

Invoice Merchant Reference · Invoice Settlement