Expense Tags — Proposed Guide

Expense Tags: Tags add operational classification such as project or campaign. They are different from ledger coding and should have explicit validation rules.

Overview

Tags add operational classification such as project or campaign. They are different from ledger coding and should have explicit validation rules.

Key concepts

Use stable tag identities and distinguish adding a tag from replacing the complete set. Check organizational ownership.

Implementation considerations

A tag must not grant access or approve an expense. Preserve historical reporting semantics when a tag is renamed.

Proposed API behavior

PATCH /v1/expenses/{expense_id}/tags 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/tags' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  --data '{
  "tag_ids": [
    "tag_example_123"
  ],
  "version": 1
}'

Fictional response example

{
  "data": {
    "expense_id": "exp_example_123",
    "tag_ids": [
      "tag_example_123"
    ],
    "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: A tag must not grant access or approve an expense. Preserve historical reporting semantics when a tag is renamed.

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

Proposed data types

Related documentation