# Projects

> Group invoices, quotes and incoming invoices by project and read totals per project.

Source: /docs/guides/projects

A project is a first-class resource with a code, a customer, a status, dates and a budget. Its code doubles as the PINT AE project reference (BT-11, `cac:ProjectReference/cbc:ID`) on invoices.

## Routes

```bash
curl "$BASE/projects?status=active&includeTotals=true" -H "X-API-KEY: $KEY"
curl -X POST "$BASE/projects" -H "X-API-KEY: $KEY" -H "Content-Type: application/json" \
  -d '{ "name": "Tower A fit-out", "customerId": "…", "startDate": "2027-01-01", "budget": 250000 }'
curl "$BASE/projects/{id}/documents" -H "X-API-KEY: $KEY"
curl "$BASE/projects/{id}/invoices?paymentStatus=unpaid" -H "X-API-KEY: $KEY"
```

| Field | Notes |
| --- | --- |
| `code` | Unique per organization. Allocated from the `project` number series when omitted (`P-{n}` by default). |
| `name`, `nameAr`, `description`, `color` | Display |
| `customerId` | Optional contact |
| `status` | `active` (default), `on_hold`, `completed`, `archived` |
| `startDate`, `endDate`, `budget`, `currency` | Planning data |
| `metadata` | Free JSON |
| `totals` (response) | `invoiceCount`, `invoicedTotal` (issued invoices minus credit notes), `paidTotal`, `outstandingTotal`, `incomingCount`, `incomingTotal` (accepted supplier invoices), `quoteCount`. Test and archived documents are excluded. |

`DELETE /projects/{id}` deletes a project without documents; a project with linked documents is archived instead (`archived: true`).

## Linking documents

- `POST /invoices`: set `projectId` on the input. `projectReference` (BT-11) defaults to the project code and can be overridden. `PATCH /invoices/{id}` accepts `projectId` on issued invoices as well (it is housekeeping data, not part of the reported XML).
- `GET /invoices?projectId=` filters the list; `projectId=none` returns invoices without a project.
- Creating a project whose code matches existing `projectReference` values links those invoices automatically.
- Recurring invoices carry `projectId` and pass it to every generated invoice.

## Webhooks and MCP

`project.created` fires on creation. MCP tools: `list_projects`, `get_project`, `create_project`, `update_project`, `delete_project`, `list_project_documents`.