Expense Metadata — Proposed Guide

Expense Metadata: Expense metadata can hold an integration correlation value or a bounded annotation. It should not duplicate the entire source receipt or…

Overview

Expense metadata can hold an integration correlation value or a bounded annotation. It should not duplicate the entire source receipt or contain payment credentials.

Key concepts

Namespace integration-owned keys and document merge behavior. Keep structured financial fields outside arbitrary metadata.

Implementation considerations

Treat metadata as untrusted input when displaying or exporting it. Never allow it to override amount, approval state or organization identity.

Proposed API behavior

PATCH /v1/expenses/{expense_id}/metadata is an illustrative design for this topic. Path and field names may change before implementation. Access would require an authorized organization context and operation-specific permission; no public API or authorization grant is available here.

Static example requests

# Proposed request text only; this reserved host is not a live API.
curl -X PATCH 'https://api.remizen.example/v1/expenses/exp_example_123/metadata' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  --data '{
  "metadata": {
    "example.source": "local-fixture"
  },
  "version": 1
}'

Fictional response example

{
  "data": {
    "expense_id": "exp_example_123",
    "metadata": {
      "example.source": "local-fixture"
    },
    "version": 1,
    "id": "exp_example_123",
    "organization_id": "org_example_123",
    "merchant": "Example Office Supply",
    "amount_minor": 12550,
    "currency": "USD",
    "status": "draft"
  },
  "meta": {
    "request_id": "req_example_123",
    "reference_only": true
  }
}

Illustrative error case

Review this failure case in context: Treat metadata as untrusted input when displaying or exporting it. Never allow it to override amount, approval state or organization identity.

{
  "error": {
    "code": "validation_error",
    "message": "The proposed expense metadata operation requires review of its input or authorization.",
    "request_id": "req_example_123"
  }
}

Proposed data types

Related documentation