Skip to main content

Budget Categories

Budget Categories (technically known as Budget Heads in accounting) form the backbone of how your organization tracks, allocates, and analyzes project expenditure.

Unlike ad-hoc expenses, Budget Categories act as your standardized, organization-wide "Chart of Accounts" for project budgeting.

By defining these at the organization level, you ensure that every project manager, employee, and financial report speaks the same language. For example, if one project logs an expense as "Travel" and another logs it as "Flights & Hotels," cross-company financial reporting becomes incredibly difficult. Budget Categories solve this by forcing all projects to align under standard, immutable classification buckets.

The Lifecycle of a Budget Category​

To understand why this configuration is so critical, here is the complete lifecycle of how a Budget Category is consumed across Orbit Resolve:

  1. Organization Setup: An administrator creates a category here (e.g., "Travel & Lodging").
  2. Expense Mapping: In Settings → Finance → Expense Categories, an admin creates a specific expense type (e.g., "Airfare" or "Meals") and strictly maps it to the parent "Travel & Lodging" budget category.
  3. Project Allocation: A Project Manager goes to their specific project's Budget tab and allocates a hard $10,000 limit to the "Travel & Lodging" category.
  4. Consumption: An employee submits an expense claim for "Airfare." Because Airfare is inherently mapped to Travel & Lodging, the system automatically checks it against the $10,000 project limit.
  5. Analytics: The central organization dashboard groups all Airfare, Train, and Hotel expenses across all active projects under the single "Travel & Lodging" budget line for simplified executive reporting.

1. Managing Categories​

Navigate to Settings → Finance → Budget Categories.

The main dashboard showing active budget categories, their system keys, and descriptions.

Loading Standard Defaults​

If you are setting up a fresh organization, you do not need to build your chart of accounts from scratch. Click the Get Defaults button (or the lightning bolt icon on mobile).

A confirmation dialog will appear stating: "This will add the standard budget categories to your organization. Existing categories will not be affected."

Clicking Load Defaults automatically triggers a backend process (POST /org/budget-heads/seed) that seeds industry-standard categories into your organization.

  • Examples of defaults added:
    • Contingency Buffer (CONTINGENCY_RISK)
    • Equipment & Hardware (EQUIPMENT_ASSETS)
    • Software & Tools (SOFTWARE_SAAS)
  • Note on safety: This operation is strictly additive and idempotent. It will not delete, merge, or overwrite any existing custom categories you have already created. If you click it twice, it will silently ignore duplicates and only add what is missing.

Searching and Filtering​

As your organization grows, your list of budget heads may expand to dozens of items. Use the search bar labeled "Filter categories by name or key..." at the top of the table to instantly filter categories.

  • Behavior: The filter performs a live, client-side search.
  • Search targets: It searches against both the Category Name (e.g., "Travel") and the System Key (e.g., "TRAVEL_EXPENSE").
  • Case sensitivity: The search is completely case-insensitive and supports partial matching. Typing "tra" will match both "Travel" and "CONTINGENCY_RISK" (if 'tra' was in the description or name).

2. Adding a New Category​

To create a custom bucket for your expenditures, click the Add Category button.

The creation drawer requires you to fill out three fields. Before clicking Create Category, ensure you understand what each field controls:

Category Name (Required)​

  • What it is: The human-readable label displayed to Project Managers and Employees throughout the app.
  • Example: Travel & Lodging
  • Validation: Must not be empty. It can contain spaces, symbols, and standard text.

System Key (Required)​

  • What it is: A strict, machine-readable identifier. This is the most important field on the form.
  • Example: TRAVEL_EXPENSE
  • Validation: System Keys must be absolutely unique across your organization. It is highly recommended to use UPPERCASE_WITH_UNDERSCORES. No spaces are allowed. If you attempt to use a key that already exists, the API will reject the submission and display a red error notification.
  • Why it matters: The System Key acts as the permanent identifier for database lookups and external ERP integrations. (See Understanding System Keys below).

Description (Optional)​

  • What it is: An internal note explaining what should (and should not) be allocated to this budget.
  • Example: "Travel, accommodation, transportation, and related expenses incurred during project activities. Do not use for daily office commuting."

After Submission: When you click Create Category, the frontend sends a POST request to the backend. Upon success, you will see a green "Category created" toast notification at the top of your screen, and the drawer will close. The table refreshes automatically to display your newly created category.

3. Understanding System Keys (Immutable Identifiers)​

You will notice an amber warning on the creation form: "System keys are unique and cannot be changed after creation."

Why does this architectural decision exist?

Organizations frequently rebrand their internal terminology. What was called "External Consultants" in 2024 might be rebranded to "Contractor Staffing" in 2025.

If Orbit Resolve relied solely on the Category Name to link data, changing the name would break historical financial reports, detach existing project budgets, and destroy automated syncs to external accounting software (like Xero or QuickBooks).

By locking the System Key (e.g., RESOURCE_EXTERNAL):

  1. You are free to edit the Category Name at any time to match current business lingo.
  2. All technical references, backend mapping, historical reports, and API integrations remain perfectly stable, bound permanently to the immutable System Key.

4. Editing a Category​

If a business term changes or a description needs clarification, click the Edit (pencil) icon on any row to modify it.

When you open the Edit drawer for a category (e.g., Travel & Lodging), you will immediately notice the difference in available fields:

  • Category Name: Fully editable. You can safely change this to Business Travel & Lodging.
  • Description: Fully editable. You can update the guidelines.
  • System Key: Permanently Disabled (Read-only). The input field will be greyed out, preserving the original TRAVEL_EXPENSE key.

After Submission: Clicking Update Category commits the changes. The system will display a green "Category updated" notification. The table immediately updates to reflect the new name, while preserving the historical System Key. All downstream dashboards and project budgets will instantly reflect the new Category Name without breaking any underlying data links.

5. Deleting a Category​

Click the Delete (trash can) icon to remove a category.

A confirmation dialog will appear warning you: "Are you sure you want to delete this category? This action cannot be undone."

The Dependency Restriction (Backend Validation)​

Orbit Resolve's backend enforces strict relational integrity. Deletion is not always permitted.

If a Budget Category is already actively referenced downstream, the backend API will reject the DELETE request, and the UI will show an error notification (e.g., "Failed to delete category").

A category is considered "active" and cannot be deleted if:

  1. It is currently mapped to one or more Expense Categories.
  2. A Project has already allocated budget funds to this specific category.

How to handle obsolete categories: If you truly need to remove an actively used category, you must first manually audit the system: remove its budget allocations from all projects and unmap it from all expense categories.

Best Practice: If a category has historical financial data that you don't want to destroy, do not delete it. Instead, simply click Edit and rename the category to [DEPRECATED] Travel & Lodging and remove it from any active expense mappings. This prevents future usage while perfectly preserving your historical data and analytics.