Create Expense — Proposed Guide

Planned API — Reference Only

Create Expense: Expense creation would create a draft record from an employee, business date and documented amount. Draft creation must remain separate…

Overview

Expense creation would create a draft record from an employee, business date and documented amount. Draft creation must remain separate from approval and reimbursement initiation.

Key concepts

Validate currency precision, employee membership and duplicate submission context. Use a client operation key for replay protection.

Implementation considerations

Do not silently round unsupported currency amounts or infer a category from merchant text alone. Preserve uncertain inputs for review.

Proposed API behavior

POST /v1/expenses 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.

Illustrative request fields
Name	Type	Description
user_id	string	Stable fictional user reference; not a secret and not evidence that a resource exists.
amount_minor	integer	Monetary amount in the documented currency minor unit; 12550 represents USD 125.50, not USD 12,550.
currency	string	Uppercase ISO 4217 currency code. Determine its minor-unit exponent before monetary conversion.
incurred_on	string (date)	Synthetic calendar date in YYYY-MM-DD form; period inclusivity must be defined by the future contract.
merchant	string	Fictional merchant label; it does not establish policy compliance or ledger coding.

Static example requests

Proposed, non-executing request examples

# Proposed request text only; this reserved host is not a live API.
curl -X POST 'https://api.remizen.example/v1/expenses' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: operation_example_123' \
  --data '{
  "user_id": "usr_example_123",
  "amount_minor": 12550,
  "currency": "USD",
  "incurred_on": "2026-01-15",
  "merchant": "Example Office Supply"
}'

Fictional response example

201 (proposed example)Static response fixture

Fictional documentation data only. No request was sent, record created, review performed, payment initiated or provider connection activated.

JSON

{
  "data": {
    "amount_minor": 12550,
    "currency": "USD",
    "incurred_on": "2026-01-15",
    "merchant": "Example Office Supply",
    "id": "exp_example_123",
    "organization_id": "org_example_123",
    "status": "draft"
  },
  "meta": {
    "request_id": "req_example_123",
    "reference_only": true
  }
}

Illustrative error case

Review this failure case in context: Do not silently round unsupported currency amounts or infer a category from merchant text alone. Preserve uncertain inputs for review.

422 (illustrative; final error contracts are undecided)Proposed error fixture

Synthetic diagnostic example. Human-readable messages must not be used as stable programmatic contracts.

JSON

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

Proposed data types

Illustrative field dictionary
Name	Type	Description
user_id	string	Stable fictional user reference; not a secret and not evidence that a resource exists.
amount_minor	integer	Monetary amount in the documented currency minor unit; 12550 represents USD 125.50, not USD 12,550.
currency	string	Uppercase ISO 4217 currency code. Determine its minor-unit exponent before monetary conversion.
incurred_on	string (date)	Synthetic calendar date in YYYY-MM-DD form; period inclusivity must be defined by the future contract.
merchant	string	Fictional merchant label; it does not establish policy compliance or ledger coding.
idempotency_key	string	Non-secret proposed operation key for controlled replay; supplied as an illustrative header.

Retrieve Expense

Expense Management

Update Expense