x-cpod-domain: finance

Finance

Invoices, POs, expenses, budgets.

Try in explorer client.finance

Invoice

An invoice issued by or to the org.

REST path/api/v1/finance/invoices

Operations

listgetcreateupdatepay

SDK

// list — returns only your records; add filters/search:
await client.finance.invoices.list()

// create:
await client.finance.invoices.create({
  id: "rec_01HXEXAMPLE",
  tenant_id: "example tenant_id",
  created_at: "2026-01-01T00:00:00Z",
  updated_at: "2026-01-01T00:00:00Z",
  app_id: "example app_id",
  created_by: "rec_01HXEXAMPLE",
})

Field	Type	Description
id*	uuid	Server-assigned ULID with type prefix (e.g. per_…).
tenant_id*	string	Tenant scope — auto-stamped from the caller's JWT.
app_id	string	App scope. Stamped ONLY when the caller's JWT was minted for a specific Application (integration API keys). Absent for human-user sessions. Filters reads when present.
created_at*	date-time	Server stamp.
updated_at*	date-time	Server stamp; updated on every patch.
created_by	uuid	Person id from the caller's JWT (sub).
updated_by	uuid	Person id from the last writer's JWT (sub).
source	string	Provenance tag — defaults to 'edm'.
source_type	enum	Where the write originated. Defaults to 'api'.`frontendbackendserversystemapi`
is_deleted	boolean	Soft-delete flag. Excluded from default list queries.
deleted_at	date-time	Stamped when soft-deleted; null otherwise.
deleted_by	uuid	Person id who soft-deleted; null otherwise.
schema_version	number	Document schema version. Bumped on incompatible writes.
number	string	Human-readable unique invoice number (e.g. 'INV-2026-0042').
type	string	'customer' = accounts receivable (AR); 'supplier' = accounts payable (AP).
status	string	Lifecycle status of the invoice.
account_id	uuid	UUID of the customer Account (used when type='customer').
vendor_id	uuid	UUID of the Vendor (used when type='supplier').
issue_date	date-time	ISO 8601 date the invoice was issued.
due_date	date-time	ISO 8601 date the payment is due.
paid_date	date-time	ISO 8601 date the invoice was fully paid. Null if unpaid.
currency	string	ISO 4217 three-character currency code.
subtotal	number	Sum of all line item amounts before tax and discounts.
tax_amount	number	Total tax amount applied to the invoice.
discount_amount	number	Total discount amount applied to the invoice.
total	number	Final total: subtotal + taxAmount - discountAmount.
line_items	json	Ordered list of line items that make up this invoice.
notes	string	Free-form notes or payment terms shown on the invoice.
project_id	uuid	UUID of the Project this invoice is billed against.
contract_id	uuid	UUID of the Contract that authorises this invoice.
document_ref	string	MinIO path or external URL of the invoice PDF or document.
created_by_id	uuid	UUID of the Person who created this invoice.
counterparty_id	uuid	Customer (AR) or vendor (AP) the invoice is with.
direction	enum	AR (we are owed) vs AP (we owe).`receivablepayable`
amount	number	Invoice total.
paid_at	date-time	ISO 8601 timestamp the invoice was paid.
po_id	uuid	Purchase order this invoice bills against.
tags	json	Free-form tags for grouping and filtering.

PurchaseOrder

A purchase order issued to a vendor.

REST path/api/v1/finance/purchase-orders

Operations

listgetcreateupdateapprove

SDK

// list — returns only your records; add filters/search:
await client.finance.purchaseOrders.list()

// create:
await client.finance.purchaseOrders.create({
  id: "rec_01HXEXAMPLE",
  tenant_id: "example tenant_id",
  created_at: "2026-01-01T00:00:00Z",
  updated_at: "2026-01-01T00:00:00Z",
  app_id: "example app_id",
  created_by: "rec_01HXEXAMPLE",
})

Field	Type	Description
id*	uuid	Server-assigned ULID with type prefix (e.g. per_…).
tenant_id*	string	Tenant scope — auto-stamped from the caller's JWT.
app_id	string	App scope. Stamped ONLY when the caller's JWT was minted for a specific Application (integration API keys). Absent for human-user sessions. Filters reads when present.
created_at*	date-time	Server stamp.
updated_at*	date-time	Server stamp; updated on every patch.
created_by	uuid	Person id from the caller's JWT (sub).
updated_by	uuid	Person id from the last writer's JWT (sub).
source	string	Provenance tag — defaults to 'edm'.
source_type	enum	Where the write originated. Defaults to 'api'.`frontendbackendserversystemapi`
is_deleted	boolean	Soft-delete flag. Excluded from default list queries.
deleted_at	date-time	Stamped when soft-deleted; null otherwise.
deleted_by	uuid	Person id who soft-deleted; null otherwise.
schema_version	number	Document schema version. Bumped on incompatible writes.
number	string	Human-readable unique purchase order number (e.g. 'PO-2026-0018').
vendor_id	uuid	UUID of the Vendor this PO is raised against.
status	string	Lifecycle status of the purchase order.
requested_by_id	uuid	UUID of the Person who raised this purchase order.
approved_by_id	uuid	UUID of the Person who approved this purchase order. Null until approved.
issued_date	date-time	ISO 8601 date the PO was formally issued to the vendor.
expected_delivery_date	date-time	ISO 8601 expected date for delivery or fulfilment.
currency	string	ISO 4217 three-character currency code.
total	number	Total value of the purchase order.
line_items	json	Ordered list of line items for this purchase order.
notes	string	Free-form notes or delivery instructions.
linked_contract_id	uuid	UUID of the Contract that covers this PO.
cost_center_id	uuid	UUID of the CostCenter to which this PO is charged.
supplier_id	uuid	Supplier / vendor the PO is raised against.
amount	number	PO total value.
order_date	date-time	ISO 8601 date the PO was placed.
budget_id	uuid	Budget this PO draws down.
requested_by	uuid	Person who raised this purchase order.
approved_by	uuid	Person who approved this purchase order.
tags	json	Free-form tags for grouping and filtering.

Expense

An expense claim.

REST path/api/v1/finance/expenses

Operations

listgetcreateupdateapprove

SDK

// list — returns only your records; add filters/search:
await client.finance.expenses.list()

// create:
await client.finance.expenses.create({
  id: "rec_01HXEXAMPLE",
  tenant_id: "example tenant_id",
  created_at: "2026-01-01T00:00:00Z",
  updated_at: "2026-01-01T00:00:00Z",
  app_id: "example app_id",
  created_by: "rec_01HXEXAMPLE",
})

Field	Type	Description
id*	uuid	Server-assigned ULID with type prefix (e.g. per_…).
tenant_id*	string	Tenant scope — auto-stamped from the caller's JWT.
app_id	string	App scope. Stamped ONLY when the caller's JWT was minted for a specific Application (integration API keys). Absent for human-user sessions. Filters reads when present.
created_at*	date-time	Server stamp.
updated_at*	date-time	Server stamp; updated on every patch.
created_by	uuid	Person id from the caller's JWT (sub).
updated_by	uuid	Person id from the last writer's JWT (sub).
source	string	Provenance tag — defaults to 'edm'.
source_type	enum	Where the write originated. Defaults to 'api'.`frontendbackendserversystemapi`
is_deleted	boolean	Soft-delete flag. Excluded from default list queries.
deleted_at	date-time	Stamped when soft-deleted; null otherwise.
deleted_by	uuid	Person id who soft-deleted; null otherwise.
schema_version	number	Document schema version. Bumped on incompatible writes.
submitted_by_id	uuid	UUID of the Person who submitted this expense.
approved_by_id	uuid	UUID of the Person who approved or rejected this expense. Null until actioned.
category	string	Expense category for grouping and policy enforcement.
description	string	Human-readable description of what was purchased and why.
amount	number	Expense amount in the stated currency.
currency	string	ISO 4217 three-character currency code.
expense_date	date-time	ISO 8601 date the expense was incurred.
status	string	Lifecycle status of the expense claim.
receipt_ref	string	MinIO path or external URL of the receipt image or PDF.
project_id	uuid	UUID of the Project this expense is charged against.
cost_center_id	uuid	UUID of the CostCenter this expense is charged against.
notes	string	Additional notes from the submitter or approver.
person_id	uuid	The person who incurred the expense.
date	date-time	ISO 8601 date of the expense.
merchant	string	Merchant or vendor the expense was paid to.
receipt_url	string	External URL of the receipt image or PDF.
approved_by	uuid	Person who approved this expense.
tags	json	Free-form tags for grouping and filtering.

Budget

A budget envelope for a period and owner.

REST path/api/v1/finance/budgets

Operations

listgetcreateupdate

SDK

// list — returns only your records; add filters/search:
await client.finance.budgets.list()

// create:
await client.finance.budgets.create({
  id: "rec_01HXEXAMPLE",
  tenant_id: "example tenant_id",
  created_at: "2026-01-01T00:00:00Z",
  updated_at: "2026-01-01T00:00:00Z",
  app_id: "example app_id",
  created_by: "rec_01HXEXAMPLE",
})

Field	Type	Description
id*	uuid	Server-assigned ULID with type prefix (e.g. per_…).
tenant_id*	string	Tenant scope — auto-stamped from the caller's JWT.
app_id	string	App scope. Stamped ONLY when the caller's JWT was minted for a specific Application (integration API keys). Absent for human-user sessions. Filters reads when present.
created_at*	date-time	Server stamp.
updated_at*	date-time	Server stamp; updated on every patch.
created_by	uuid	Person id from the caller's JWT (sub).
updated_by	uuid	Person id from the last writer's JWT (sub).
source	string	Provenance tag — defaults to 'edm'.
source_type	enum	Where the write originated. Defaults to 'api'.`frontendbackendserversystemapi`
is_deleted	boolean	Soft-delete flag. Excluded from default list queries.
deleted_at	date-time	Stamped when soft-deleted; null otherwise.
deleted_by	uuid	Person id who soft-deleted; null otherwise.
schema_version	number	Document schema version. Bumped on incompatible writes.
name	string	Descriptive name for this budget (e.g. 'Engineering Q1 2026').
fiscal_year	string	Fiscal year label (e.g. '2026' or 'FY2026').
period	string	Budget period granularity.
cost_center_id	uuid	UUID of the CostCenter this budget belongs to. Null for company-wide budgets.
owner_id	uuid	UUID of the Person responsible for this budget.
total_amount	number	Total budget amount allocated for this period.
currency	string	ISO 4217 three-character currency code.
status	string	Lifecycle status of the budget.
notes	string	Free-form notes about this budget.
amount	number	Total budgeted amount.
start_date	date-time	ISO 8601 start date of the budget period.
end_date	date-time	ISO 8601 end date of the budget period.
tags	json	Free-form tags for grouping and filtering.

BudgetLine

A line item under a Budget.

REST path/api/v1/finance/budget-lines

Operations

listgetcreateupdate

SDK

// list — returns only your records; add filters/search:
await client.finance.budgetLines.list()

// create:
await client.finance.budgetLines.create({
  id: "rec_01HXEXAMPLE",
  tenant_id: "example tenant_id",
  created_at: "2026-01-01T00:00:00Z",
  updated_at: "2026-01-01T00:00:00Z",
  app_id: "example app_id",
  created_by: "rec_01HXEXAMPLE",
})

Field	Type	Description
id*	uuid	Server-assigned ULID with type prefix (e.g. per_…).
tenant_id*	string	Tenant scope — auto-stamped from the caller's JWT.
app_id	string	App scope. Stamped ONLY when the caller's JWT was minted for a specific Application (integration API keys). Absent for human-user sessions. Filters reads when present.
created_at*	date-time	Server stamp.
updated_at*	date-time	Server stamp; updated on every patch.
created_by	uuid	Person id from the caller's JWT (sub).
updated_by	uuid	Person id from the last writer's JWT (sub).
source	string	Provenance tag — defaults to 'edm'.
source_type	enum	Where the write originated. Defaults to 'api'.`frontendbackendserversystemapi`
is_deleted	boolean	Soft-delete flag. Excluded from default list queries.
deleted_at	date-time	Stamped when soft-deleted; null otherwise.
deleted_by	uuid	Person id who soft-deleted; null otherwise.
schema_version	number	Document schema version. Bumped on incompatible writes.
budget_id	uuid	UUID of the parent Budget.
category	string	Category label for this budget line (e.g. 'Software Licenses', 'Travel').
allocated_amount	number	Amount allocated to this budget line category.
spent_amount	number	Computed total actuals charged against this line. Read-only — maintained by the platform.
remaining_amount	number	Computed remaining balance (allocatedAmount - spentAmount). Read-only — maintained by the platform.
notes	string	Free-form notes about this budget line.
description	string	What this budget line covers.
amount	number	Budgeted amount for this line.
currency	string	ISO 4217 three-character currency code.
spent	number	Amount spent to date.
cost_center_id	uuid	UUID of the CostCenter this budget line belongs to.
tags	json	Free-form tags for grouping and filtering.

Docs

Invoice

PurchaseOrder

Expense

Budget

BudgetLine