Update Allowance — Proposed Guide

Update Allowance: An allowance update would change permitted future-facing attributes with version control. Reducing an allocation below already consumed…

Overview

An allowance update would change permitted future-facing attributes with version control. Reducing an allocation below already consumed amounts needs an explicit exception policy.

Key concepts

Distinguish the assigned amount from recorded consumption. Preserve the effective date of the change.

Implementation considerations

Do not rewrite historical transactions to make a new balance appear valid. Closed periods should remain protected from ordinary edits.

Proposed API behavior

PATCH /v1/allowances/{allowance_id} 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/allowances/allowance_example_123' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  --data '{
  "amount_minor": 12550,
  "effective_on": "2026-01-15",
  "version": 1
}'

Fictional response example

{
  "data": {
    "allowance_id": "allowance_example_123",
    "amount_minor": 12550,
    "effective_on": "2026-01-15",
    "version": 1,
    "id": "allowances_example_123",
    "organization_id": "org_example_123"
  },
  "meta": {
    "request_id": "req_example_123",
    "reference_only": true
  }
}

Illustrative error case

Review this failure case in context: Do not rewrite historical transactions to make a new balance appear valid. Closed periods should remain protected from ordinary edits.

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

Proposed data types

Related documentation