> For the complete documentation index, see [llms.txt](https://docs.tiny.plus/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.tiny.plus/api/endpoints/fee-templates.md).

# Fee templates and rate cards

{% hint style="warning" %}
Submission packs are invite only for now, so these requests answer only for accounts we've invited; [`/me`](https://docs.tiny.plus/api/endpoints/me.md#integrations) carries `integrations.submissions`.
{% endhint %}

A [fee proposal](https://docs.tiny.plus/api/endpoints/packs.md#fee-proposals) starts from a fee template: the stages a fee is split into, the lines under each, how disbursements are charged, and the letter, understanding and terms with tokens for the project's name, client and figures. Time-charge lines take their hourly rates from a rate card, a schedule of rates by role; an account keeps as many as it needs and picks one per proposal.

Both are set up on the web, under Account Settings → Submissions → Fees, by account admins. The API reads them, so an integration can show which template a proposal came from, or open one from a chosen template; it doesn't change them. `POST`, `PATCH` and `DELETE` on these paths answer `404`.

| Request                      | What it does                                                  |
| ---------------------------- | ------------------------------------------------------------- |
| `GET /v2/fee_templates`      | [The account's fee templates](#the-fee-templates).            |
| `GET /v2/fee_templates/{id}` | [One template](#one-fee-template), with its stages and lines. |
| `GET /v2/rate_cards`         | [The account's rate cards](#rate-cards), live ones first.     |
| `GET /v2/rate_cards/{id}`    | [One rate card](#one-rate-card), with its roles and rates.    |

They come with submission packs, so they answer `403` with "Submission packs aren't available on this account." while packs are off; [`/me`](https://docs.tiny.plus/api/endpoints/me.md#integrations) carries `integrations.submissions`. Anyone whose token can read the account's records can read them. Ids are numbers, text is plain, times are UTC.

## The fee templates

<mark style="color:blue;">`GET`</mark> `https://api.tiny.plus/v2/fee_templates`

```bash
curl "https://api.tiny.plus/v2/fee_templates" \
  -H "Authorization: Bearer {{user_access_token}}"
```

```json
{
    "total_records": 1,
    "records": [
        {
            "id": 73,
            "name": "Harbourside standard",
            "description": "A lump sum for each of five stages, disbursements at 5%, the programme shown.",
            "is_default": true,
            "style": "proposal",
            "grouping": "stages",
            "percent_of": "project_value",
            "disbursement_kind": "percent",
            "disbursement_value": 5,
            "programme_on": true,
            "validity_days": 30,
            "sections": {"letter": true, "understanding": true, "scope": true, "fee": true, "programme": true, "terms": true, "statement": false, "sheets": true, "cvs": true, "closing": true},
            "letter_text": "Thank you for asking %firm% to put forward a fee for %name%. …",
            "understanding_text": "%client% is looking for a design team for %name%. …",
            "assumptions_text": "Our fee assumes the scope described above…",
            "exclusions_text": "Authority fees and charges…",
            "payment_text": "Fees are invoiced monthly against the progress of each stage and are payable within 14 days.",
            "variations_text": "Work outside the scope above is undertaken on written instruction…",
            "stages": [
                {"position": 1, "name": "Concept design", "percent_fee": 15, "scope_text": "Site and brief analysis, concept options, a preferred concept and an order-of-cost estimate."},
                {"position": 2, "name": "Design development", "percent_fee": 20, "scope_text": "The preferred concept developed…"}
            ],
            "lines": [
                {"stage_position": 1, "position": 1, "title": "Professional fee", "basis": "lump", "percent_fee": 15, "percent": null, "amount": null, "hours": null, "role": null, "note": null},
                {"stage_position": 2, "position": 1, "title": "Professional fee", "basis": "lump", "percent_fee": 20, "percent": null, "amount": null, "hours": null, "role": null, "note": null}
            ],
            "stage_count": 5,
            "line_count": 5,
            "created_date": "2026-11-06T08:11:02Z",
            "modified_date": "2026-11-06T08:11:02Z"
        }
    ]
}
```

| Field                                                                                                         | What it is                                                                                                                                                                                                                                                                                                       |
| ------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`, `description`, `is_default`                                                                           | The template. A new proposal starts from the default when no template is named.                                                                                                                                                                                                                                  |
| `style`                                                                                                       | `proposal` or `letter`: whether new proposals from it start as a full proposal or a [fee letter](https://docs.tiny.plus/api/endpoints/packs.md#fee-proposals). Each proposal can change its own.                                                                                                                 |
| `grouping`                                                                                                    | `stages` (lines grouped by stage) or `flat` (one list).                                                                                                                                                                                                                                                          |
| `percent_of`                                                                                                  | What a percentage line is a percentage of: `project_value`, the project's construction value; `value_rate`, a fee that is `percent_of_rate` percent of the construction value; `project_fee`, the fee set on the project when the proposal is started; or `typed`, a figure typed on the proposal.               |
| `percent_of_rate`                                                                                             | With `value_rate`, the percentage of the construction value the fee is, such as `4.5`; otherwise `null`.                                                                                                                                                                                                         |
| `disbursement_kind`, `disbursement_value`                                                                     | `none`, `percent` (of the fee), `at_cost` or `amount`.                                                                                                                                                                                                                                                           |
| `programme_on`                                                                                                | Whether a proposal from it shows the programme page.                                                                                                                                                                                                                                                             |
| `validity_days`                                                                                               | How many days a proposal from it stands.                                                                                                                                                                                                                                                                         |
| `sections`                                                                                                    | Which parts a proposal from it has to begin with, each `true` or `false`.                                                                                                                                                                                                                                        |
| `letter_text`, `understanding_text`, `assumptions_text`, `exclusions_text`, `payment_text`, `variations_text` | The words, with their tokens unfilled: `%name%`, `%client%`, `%contact%`, `%firm%`, `%date%`, `%fee_total%`, `%validity_days%`, `%signatory%` and any field of the project as `%field%`. A proposal fills them in when it starts.                                                                                |
| `stages`                                                                                                      | The template's stages in order: `position`, `name`, `percent_fee` (its share of the headline fee, or `null`) and `scope_text`.                                                                                                                                                                                   |
| `lines`                                                                                                       | The lines in order: `stage_position` (`null` for Other services, or every line of a flat template), `position`, `title`, `basis` (`lump`, `percent`, `time`, `provisional` or `excluded`), `percent_fee` (a lump or provisional line's share of the headline fee), `percent`, `amount`, `hours`, `role`, `note`. |
| `stage_count`, `line_count`                                                                                   | How many of each.                                                                                                                                                                                                                                                                                                |

## One fee template

<mark style="color:blue;">`GET`</mark> `https://api.tiny.plus/v2/fee_templates/{{id}}`

```bash
curl "https://api.tiny.plus/v2/fee_templates/{{id}}" \
  -H "Authorization: Bearer {{user_access_token}}"
```

One entry of the list above. A template that isn't the account's, or was removed, answers `404`.

## Rate cards

<mark style="color:blue;">`GET`</mark> `https://api.tiny.plus/v2/rate_cards`

Live cards first, then retired ones, which a proposal keeps using until its card is changed.

```bash
curl "https://api.tiny.plus/v2/rate_cards" \
  -H "Authorization: Bearer {{user_access_token}}"
```

```json
{
    "total_records": 1,
    "records": [
        {
            "id": 58,
            "name": "Harbourside rates 2026",
            "is_default": true,
            "retired": false,
            "lines": [
                {"position": 1, "role": "Director", "hourly_rate": 320},
                {"position": 2, "role": "Associate", "hourly_rate": 240},
                {"position": 3, "role": "Graduate", "hourly_rate": 150}
            ],
            "created_date": "2026-11-06T08:11:02Z",
            "modified_date": "2026-11-06T08:11:02Z"
        }
    ]
}
```

`hourly_rate` is in the account's currency. A new proposal takes the default card; a time-charge line names one of its roles.

## One rate card

<mark style="color:blue;">`GET`</mark> `https://api.tiny.plus/v2/rate_cards/{{id}}`

```bash
curl "https://api.tiny.plus/v2/rate_cards/{{id}}" \
  -H "Authorization: Bearer {{user_access_token}}"
```

One entry of the list above, retired or not. A card that isn't the account's answers `404`.

## Errors

| Status | When                                                    |
| ------ | ------------------------------------------------------- |
| `400`  | The id isn't a number.                                  |
| `403`  | Submission packs aren't on for the account.             |
| `404`  | No such template or card, or a method other than `GET`. |
