--- title: "Budgets API · COUNT Partner API" description: "Budgets let partners create workspace financial plans with versioned cell grids. Partner responses expose budget UUIDs as `id`, strip internal numeric foreign…" canonical: "https://developers.getcount.com/reference/budgets" source: "https://developers.getcount.com/reference/budgets" --- 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 ## Overview 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 `id` uuid Budget identifier (UUID). Use in path parameters. `name` string Display name. Must be unique among non-archived budgets in the workspace. `startPeriod` date First budget period start date (ISO date). `cadence` enum Period cadence. One of: `monthly`, `yearly` `actualPeriods` integer Number of historical actual periods included. `budgetPeriods` integer Number of forward budget periods (minimum 1). `currencyCode` string ISO 4217 currency code. `status` enum Budget lifecycle status. One of: `draft`, `published`, `archived` `lockedAt` datetime When the budget was locked, or null. `isOverall` boolean Whether this is the workspace Overall Budget (at most one per workspace). `versions` array Version summaries attached to the budget. `versionNumber` integer 1-based version number used in path parameters. `label` string Human-readable version label. `isPublished` boolean Whether this version is the published snapshot. `createdAt` datetime When the version was created. `createdAt` datetime ISO 8601 creation timestamp. `updatedAt` datetime ISO 8601 last update timestamp. Example ```json { "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. ## Related - [Chart of Accounts API](https://developers.getcount.com/reference/chart-of-accounts) - [Reports API](https://developers.getcount.com/reference/reports) ## 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. ## Endpoints [GET Get overall budget `/partners/budgets/overall` Returns the workspace Overall Budget, if one exists.](https://developers.getcount.com/reference/budgets/get-overall-budget) [GET List budgets `/partners/budgets` Returns all budgets in the workspace, optionally filtered by status.](https://developers.getcount.com/reference/budgets/list-budgets) [POST Create budget `/partners/budgets` Creates a budget and its initial version.](https://developers.getcount.com/reference/budgets/create-budget) [GET Get budget `/partners/budgets/{uuid}` Retrieves a single budget by UUID.](https://developers.getcount.com/reference/budgets/get-budget) [PATCH Update budget metadata `/partners/budgets/{uuid}` Updates budget metadata. Rejected when the budget is published or locked.](https://developers.getcount.com/reference/budgets/update-budget) [DELETE Delete budget `/partners/budgets/{uuid}` Deletes a draft budget.](https://developers.getcount.com/reference/budgets/delete-budget) [GET Get budget grid `/partners/budgets/{uuid}/grid` Returns the budget cell grid for a version, with optional actuals.](https://developers.getcount.com/reference/budgets/get-budget-grid) [GET List budget versions `/partners/budgets/{uuid}/versions` Returns version summaries for a budget.](https://developers.getcount.com/reference/budgets/list-budget-versions) [POST Create budget version `/partners/budgets/{uuid}/versions` Creates a new numbered version for the budget.](https://developers.getcount.com/reference/budgets/create-budget-version) [PATCH Update budget cells `/partners/budgets/{uuid}/versions/{versionNumber}/cells` Updates one or more cells in a budget version.](https://developers.getcount.com/reference/budgets/update-budget-cells) [POST Bulk update budget cells `/partners/budgets/{uuid}/versions/{versionNumber}/cells/bulk` Applies many cell updates in one request with per-row success/failure results.](https://developers.getcount.com/reference/budgets/bulk-update-budget-cells) [POST Publish budget `/partners/budgets/{uuid}/publish` Publishes a budget version snapshot.](https://developers.getcount.com/reference/budgets/publish-budget) [POST Archive budget `/partners/budgets/{uuid}/archive` Archives a budget.](https://developers.getcount.com/reference/budgets/archive-budget) [POST Duplicate budget `/partners/budgets/{uuid}/duplicate` Creates a copy of a budget, optionally carrying cell values forward.](https://developers.getcount.com/reference/budgets/duplicate-budget)