Costs

A cost is a supplier bill or an internal expense on a project. Every cost is allocated to one task and has at least one line item. Drum works out the cost total from its line items.

Money is integer cents, tax exclusive. Dates are yyyy-mm-dd. created_at, updated_at and approved_at are timestamps.

Endpoints

List costs

Newest issued date first, paginated (see Pagination). A cost raised by a variation is listed once the variation is approved. Deleted costs are left out.

curl -H "Authorization: Bearer $DRUM_API_TOKEN" \
  "https://app.getdrum.com/api/v1/projects/20488/costs?status=final&include_line_items=true"

The cost object

Money and markup fields:

Line item fields: id, name, position, line_type (line or heading), quantity (a decimal, as a string), tax_rate_id, tax_rate_name, finance_account_id, finance_account_name, line_item_code_id, line_item_code_name. With view_project_metrics also price_cents, discount_cents, total_cents and total_excluding_tax_cents.

account_user_id and project_procedure_id are deprecated copies of member_id and deliverable_id. Use the new names.

Create a cost

POST /api/v1/projects/:project_id/costs creates the cost and its line items in one transaction. Send fields flat or under cost. The project must be a delivery project.

Line item fields:

A line item with any other key fails the request with 422 invalid_input.

Defaults to know about:

• A line with no finance account takes the cost type’s default account, then its line item code’s account. With neither, the cost saves, but it cannot go to the accounting system until an account is set in Drum.
• A cost type with a line item code gives a line sent with price_cents: 0 the code’s price.
• A cost type set to add a summary line adds one more line with the project number.
• The cost takes the project’s currency.

Check the cost in the response to see the defaults that were applied.

POST /api/v1/projects/20488/costs
{
  "cost": {
    "task_id": 55120,
    "cost_type_id": 610,
    "name": "Steel package",
    "invoice_number": "INV-4471",
    "issued_date": "2026-09-08",
    "due_date": "2026-10-08",
    "status": "final",
    "company_id": 902,
    "line_items": [
      {"name": "Steel supply", "quantity": 2, "price_cents": 125000, "finance_account_id": 310},
      {"name": "Delivery", "quantity": 1, "price_cents": 15000, "finance_account_id": 310}
    ]
  }
}

Returns 201 with the cost and its line items. Send an Idempotency-Key header to make retries safe (see Idempotency keys). A replay does not raise approvals or push a bill again.

A created cost sends the cost.created webhook event.

Add a receipt to an expense claim

Send expense_claim_id to add the cost as a receipt on a draft expense claim, as Add Item on the claim page does. Drum creates a claim item for total_cents, allocated in full to task_id. From then on the claim sets the cost’s name, supplier, amount and status.

• Required: expense_claim_id, task_id, cost_type_id, name, total_cents.
• Optional: description, reference, issued_date, and company_id or new_supplier_name.
• Not accepted: line_items, purchase_order_id, member_id, invoice_number, due_date, status, billable, deliverable_id, markups, supplier_invoice_total_cents.
• The claim must be one the token’s user can see and change. A claim that is not a draft returns 422 expense_claim_not_draft. The account must use expense claims. create_costs is not needed.

Change a cost

PATCH /api/v1/projects/:project_id/costs/:id changes the fields you send. Send fields flat or under cost. Line items cannot be changed here.

Fields: name, description, reference, invoice_number, issued_date, due_date, bill_issue_date, status, billable, tax_rule, task_id, deliverable_id, cost_type_id, one of company_id, member_id or new_supplier_name, fixed_markup_cents, percentage_markup, supplier_invoice_total_cents.

• status: "approved" needs approve_costs. The token’s user becomes the approver, and the automatic bill push runs. A failed push is reported in warnings.
• status: "final" starts the approval workflow.
• A cost with a bill in the accounting system stays approved (422 status_locked_by_bill). A change to a field on the bill is sent to the accounting system.
• The markup of an invoiced cost cannot change (422 cost_invoiced).
• On a cost from an expense claim, the fields the claim sets return 422 cost_on_expense_claim. Change the claim in Drum instead.
• new_supplier_name creates a supplier and needs create_companies.

Returns 200 with the cost and its line items.

Attach a file

A cost or a receipt can carry one PDF or image (JPEG, PNG, GIF, WebP or HEIC). Send one of:

• document: {"filename": "receipt.pdf", "content_base64": "..."}, for a file of 1 MB or less. A larger file returns 422 file_too_large.
• document_signed_id: the signed_id from a direct upload, for a file of up to 20 MB.

For a direct upload, POST /api/v1/uploads with filename, byte_size (integer), checksum (base64 MD5 of the file) and content_type. It returns 201 with signed_id, url, headers and expires_at. PUT the file bytes to url with exactly those headers within 10 minutes, then send signed_id as document_signed_id within one day. A signed id works once, and only for the token’s user. An unknown, expired or used id returns 404 upload_not_found.

POST /uploads needs api_create and permission to create costs or expense claims. It accepts an Idempotency-Key.

Permissions

Errors

Error bodies are {"error", "code"}. Input and lookup errors add field, which for a line item reads like line_items[0].price_cents. Nothing is saved unless the whole request succeeds.