API Reference

Budgets

Budgets let partners create workspace financial plans with versioned cell grids. Partner responses expose budget UUIDs as `id`, strip internal numeric foreign keys, and require `accountUuid` (not numeric `accountId`) on cell update payloads.

Last updated 2026-06-29

The Budgets API lets your integration list, create, update, publish, archive, and duplicate budgets in a workspace. Each budget carries metadata (name, cadence, period counts, currency) and one or more numbered versions with a cell grid keyed by chart-of-accounts UUIDs.

Cell updates accept `accountUuid` and reject bare numeric `accountId` fields. Use `GET /partners/budgets/{uuid}/grid` to read the grid with optional actuals, then patch individual cells or bulk-import many rows at once.

Key concepts

Overall Budget

Each workspace may have at most one Overall Budget (`isOverall: true`). Fetch it with `GET /partners/budgets/overall` or create it explicitly on `POST /partners/budgets`.

Versions and the grid

New budgets receive version 1 automatically. Create additional versions with `POST /partners/budgets/{uuid}/versions`, then read or update cells against a specific `versionNumber`.

Account UUIDs on cells

Cell update bodies must use `accountUuid` from the chart of accounts. Sending numeric `accountId` without `accountUuid` returns 400.

Publish and archive

Publishing locks a version snapshot. Archived budgets are excluded from name-uniqueness checks and can be recreated under the same name.

The budget object

Metadata returned on budget list and detail responses. Nested `versions` omit internal database ids.

Attributes

iduuid

Budget identifier (UUID). Use in path parameters.

namestring

Display name. Must be unique among non-archived budgets in the workspace.

startPerioddate

First budget period start date (ISO date).

cadenceenum

Period cadence.

One of: monthly, yearly

actualPeriodsinteger

Number of historical actual periods included.

budgetPeriodsinteger

Number of forward budget periods (minimum 1).

currencyCodestring

ISO 4217 currency code.

statusenum

Budget lifecycle status.

One of: draft, published, archived

lockedAtdatetime

When the budget was locked, or null.

isOverallboolean

Whether this is the workspace Overall Budget (at most one per workspace).

versionsarray

Version summaries attached to the budget.

versionNumberinteger

1-based version number used in path parameters.

labelstring

Human-readable version label.

isPublishedboolean

Whether this version is the published snapshot.

createdAtdatetime

When the version was created.

createdAtdatetime

ISO 8601 creation timestamp.

updatedAtdatetime

ISO 8601 last update timestamp.

Example

{
  "id": "55667788-99aa-bbcc-ddee-ff0011223344",
  "name": "FY 2026 Operating Budget",
  "startPeriod": "2026-01-01",
  "cadence": "monthly",
  "actualPeriods": 3,
  "budgetPeriods": 12,
  "currencyCode": "USD",
  "status": "draft",
  "lockedAt": null,
  "isOverall": false,
  "versions": [
    {
      "versionNumber": 1,
      "label": "Initial",
      "isPublished": false,
      "createdAt": "2026-01-15T10:30:00.000Z"
    }
  ],
  "createdAt": "2026-01-15T10:30:00.000Z",
  "updatedAt": "2026-01-28T14:22:30.000Z"
}

Grid actuals

Pass `includeActuals=false` on the grid route to omit actual-period columns. `reportType` accepts `accrual` (default) or `cash`.

Published budgets

Metadata updates are rejected when `status` is `published` or `lockedAt` is set. Duplicate or create a new version instead.

Recent changes

2026-06-29

Budgets API and documentation parity

Added the Budgets API reference (14 endpoints), invoice send-history, and account sub-types list. Introduced an automated parity check (`npm run check:parity`) that compares documented routes against count-dev. Normalized customer path parameters to `{uuid}` and fixed the documents chunk-upload progress path.