---
title: "Apply Suggestion"
method: POST
path: "/api/payday/apply-suggestion"
tags: ["Payday"]
---

# Apply Suggestion

`POST /api/payday/apply-suggestion`

## Request

- Base URL: `https://api.earmarkiq.app` (the document declares no server; this is the origin it was published from)
- URL: `https://api.earmarkiq.app/api/payday/apply-suggestion`
- Auth: HTTP bearer

Apply AI suggestion: creates allocation rules and the plan's budgets.

For each suggestion category:
- Bills → virtual pot rule, and a 'utilities' budget
- Savings → transfer rule (real money movement)
- Investments → transfer rule (real money movement)
- Discretionary → per-category budgets from spending analysis

EQ-72 ruling 4 (13 Oct 2026): this endpoint used to create budgets and
OVERWRITE the limits the user had set (the founder's eight budgets were
rewritten on 28 Sep). Now:

- ?mode=propose (the app): no budget is written. Every budget the plan
  wants is returned in budget_proposals; the app shows them and the
  user confirms per budget through PATCH /api/budgets/bulk-update.
- no mode (web app, older phones): today's behaviour, except a user-set
  limit is never overwritten or deleted — it is skipped and proposed —
  and a £0 budget is never created. The plan still creates budgets that
  do not exist, and may resize or remove one only while it is the
  plan's own: created by the previous Apply and still at the limit
  that Apply wrote (owned.budget_limits). See _BudgetWrites.

## Query parameters

- `mode` string, nullable: 'propose': budgets are proposed, never written (EQ-72)

## Request body

- ApplySuggestionRequest
  - `allocations` SuggestionAllocation[], required
    - `category` string, required
    - `amount` number, required
    - `percentage` number, required
  - `summary` string, nullable
  - `goal_split` GoalSplit[]
    - `goal_id` string, required
    - `name` string, required
    - `amount` number, required
  - `buffer` CoachBuffer: The cash buffer the coach measures Savings against, in pounds (26 Sep 2026).
    - `cash_saved` number, required
    - `target` number, required
    - `months` number, required
    - `target_months` integer, required

## Response `200`

Successful Response

- ApplySuggestionResponse
  - `budgets_created` integer, required
  - `budgets_updated` integer, required
  - `rules_created` integer, required
  - `rules_updated` integer
  - `budgets_removed` integer
  - `rules_deactivated` integer
  - `budgets_proposed` integer
  - `budget_proposals` BudgetProposal[]
    - `category` string, required
    - `proposed_limit` number, required
    - `current_limit` number, nullable
    - `source` string, required
  - `items` CreatedItem[], required
    - `type` string, required
    - `category` string, required
    - `amount` number, required
    - `label` string, nullable
  - `rules` PaydayRule[], required
    - `id` string, required
    - `type` string, required
    - `amount` number, required
    - `timing` string, required
    - `timing_label` string, required
    - `active` boolean, required
    - `description` string, nullable
    - `target_id` string, nullable
    - `target_label` string, nullable
    - `virtual_budget_category` string, nullable
    - `pot_category` string, nullable
    - `goal_id` string, nullable
    - `goal_name` string, nullable

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/earmarkiq/apis/earmark-api.md) · [All operations](https://skmtc.dev/earmarkiq/apis/earmark-api/llms.txt) · [OpenAPI document](https://skmtc.dev/earmarkiq/apis/earmark-api/revisions/4a2c41907105?raw)