Proposal budgets

A proposal budget prices a proposal and sets the structure of the project it becomes. These endpoints write a live proposal’s budget one row at a time, through the same code as the budget editor in Drum. To read the whole budget, use GET /proposals/:id.

In the budget editor, the rows under a deliverable are called tasks. The API calls them items.

Money is integer cents, tax exclusive. You send cents in fields ending _cents. Results show money as an object: {"cents": 120000, "currency": "AUD", "formatted": "$1,200.00"}. Quantities are decimals.

A proposal template’s budget is written with the same row shapes, on its own paths: see Proposal templates.

Endpoints

All paths start with /api/v1/proposals/:proposal_id/budget.

How the budget fits together

Budget
├── Phases            labels that group deliverables
└── Deliverables      one list, in order; each may name a phase
    └── Items         the tasks of the deliverable
        ├── Resource lines   hours or days of a role or person, at a rate
        └── Cost lines       expenses, at a billable rate

• A phase is a label. A deliverable names at most one phase with budget_phase_id. Deleting a phase keeps its deliverables.
• A deliverable becomes a deliverable of the project when the proposal is converted. Its budget_type is fixed_price (the default) or time_and_materials.
• An item becomes a task. Its kind decides where its value comes from (see below).
• Resource lines and cost lines sit under an item. They make up the item’s internal budget, and for a dynamic item its price as well.

Fixed and dynamic items

Every item has two values. contract_value is the sell price the client sees. internal_budget is what the work is budgeted to cost inside the business.

• A fixed item is a lump sum until it has lines. Once it has lines, its price and its budget can differ.
• A dynamic item takes its value from its lines. With no lines it is worth zero, and the budget reports an empty_dynamic_item warning.
• A non_financial item is an internal process (item_type: process_only). It has no price and takes no lines.

Switching kind. Changing a dynamic item to fixed sets quantity to 1, quantity_unit to per_item, and billable_rate_cents to the current total of its lines (0 when it has none). Send quantity, quantity_unit or billable_rate_cents in the same request to use your own values instead. Changing a fixed item to dynamic clears its own quantity and rate: its value comes from its lines from then on.

How the budget reaches the fees

A budget write does not change the proposal’s fee stages and lines directly. When the proposal uses live pricing (see Set the pricing layout), the fees follow the budget a moment after each write. Otherwise they change only when someone updates them in Drum.

Permissions

The token’s user must also be able to read the proposal’s opportunity or project. Otherwise the answer is 404 proposal_not_found. See Which proposals you can reach. The proposal builder is not needed.

Rules for every row

• Send the fields at the top level of the JSON body. A key that the row type does not take is refused with 422 invalid_input and that field.
• PATCH changes only the keys you send. null clears only the fields marked “Can be null” below. Any other null is 422 invalid_input.
• position places the row in its list. 1 is first. A position past the end puts the row last. Without it, a new row goes last.
• A row of another budget is not found, with the code of its type, for example 404 budget_deliverable_not_found.
• A finalised budget (approved or rejected) refuses every write with 409 budget_finalised.
• The budget must exist. A proposal with no budget answers 404 proposal_budget_not_found. Add the budget in Drum.
• New children ride along on a create only. A new deliverable can carry items, and a new item can carry resources and costs. On a PATCH, a child list is refused with 422 invalid_input: add or change each child at its own path.
• Writes are not idempotent. These creates take no Idempotency-Key. After a timeout, read the proposal before you retry.

Results

A POST returns 201, and a PATCH returns 200, with the row as the budget document shows it:

{
  "proposal_id": 18342,
  "row_type": "budget_item",
  "record_kind": "budget_item",
  "row": {
    "id": 66120,
    "record_kind": "budget_item",
    "kind": "fixed",
    "name": "Site survey",
    "item_type": "task",
    "position": 1,
    "description": null,
    "delivery_task_name": null,
    "quantity": 2.0,
    "quantity_unit": "per_item",
    "billable_rate": {"cents": 60000, "currency": "AUD", "formatted": "$600.00"},
    "contract_value": {"cents": 120000, "currency": "AUD", "formatted": "$1,200.00"},
    "internal_budget": {"cents": 120000, "currency": "AUD", "formatted": "$1,200.00"},
    "resources": [],
    "costs": []
  },
  "warnings": []
}

Adding deliverables from a project template also returns rows, every new deliverable. row is the first.

A DELETE returns 200:

{"proposal_id": 18342, "row_type": "budget_item", "id": 66120, "deleted": true, "permanently_deleted": true, "warnings": []}

warnings holds messages about the budget after the write. Each is {code, message}, with count, subject_id or subject_ids where they apply.

The budget document

GET /proposals/:id returns the budget under budget. Each row has record_kind.

Budget warnings

Phases

POST /api/v1/proposals/18342/budget/phases
{"name": "Concept", "colour": "blue"}

Deleting a phase keeps its deliverables, with no phase.

Deliverables

POST /api/v1/proposals/18342/budget/deliverables
{
  "name": "Design development",
  "budget_phase_name": "Concept",
  "items": [
    {"name": "Site survey", "kind": "fixed", "quantity": 1, "quantity_unit": "per_item", "billable_rate_cents": 150000},
    {"name": "Concept drawings", "resources": [{"resource_type_id": 77, "quantity": 24}]}
  ]
}

Deleting a deliverable deletes its items and their lines.

Copy a deliverable

Send only copy_from_id, a deliverable of this budget, and optionally position. Drum copies it with its items and lines, names it with “(Copy)”, and places it after the original, as Duplicate does in the editor. Change the copy by its new id afterwards.

POST /api/v1/proposals/18342/budget/deliverables
{"copy_from_id": 40210}

Add deliverables from a project template

Send from_project_template_deliverable_ids, a list of project template deliverable ids, and optionally budget_phase_id or budget_phase_name, and position. Drum adds one deliverable for each, with its tasks, resources and costs from the template, as Add from template does in the editor. They are added in the project template’s order, as one block at position. The result has every new deliverable in rows.

Project template deliverable ids come from the proposal_template_drift warning, or from the project template endpoints. An id that is not found is 404 project_template_deliverable_not_found.

include_quote_sections is refused on a live proposal (422 invalid_input).

Items

quantity, quantity_unit or billable_rate_cents on an item that is not fixed is 422 invalid_input. Send kind: "fixed" with them.

POST /api/v1/proposals/18342/budget/items
{"budget_deliverable_id": 40210, "name": "Site survey", "kind": "fixed", "quantity": 2, "billable_rate_cents": 60000}

PATCH /api/v1/proposals/18342/budget/items/66120
{"kind": "dynamic"}

An item that has lines cannot become non_financial (422 item_has_lines). Delete its lines first.

Resource lines

A resource line is time for a role, optionally a named person, at a rate.

Rates. When a line’s role or person changes and you send no rate_cents, Drum takes the rate from the budget’s rate cards: the proposal’s own rate card first, and a person’s rate before a role’s. source_rate_card shows the card the rate came from. A typed rate_cents sets source_rate_card to null, so a later rate card change leaves the line alone. The line total is quantity × rate.

POST /api/v1/proposals/18342/budget/resources
{"budget_item_id": 66125, "resource_type_id": 77, "preferred_member_id": 5501, "quantity": 16}

A line cannot be added to a non-financial item (422 item_process_only).

Cost lines

A cost line is an expense, such as a subcontractor fee or travel, at a billable rate.

The line total is quantity × billable_rate.

POST /api/v1/proposals/18342/budget/costs
{"budget_item_id": 66125, "cost_type_id": 610, "name": "Geotechnical report", "quantity": 1, "billable_rate_cents": 450000}

Errors

Error bodies are {"error", "code"}, with field on input and lookup errors. See Errors. Nothing is saved unless the whole request succeeds.