---
title: "Virtual Allocate"
method: POST
path: "/api/payday/virtual-allocate"
tags: ["Payday"]
---

# Virtual Allocate

`POST /api/payday/virtual-allocate`

## 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/virtual-allocate`
- Auth: HTTP bearer

Process virtual pot allocations on payday.

For each rule linked to a budget category:
1. Find the matching budget for the current user. PIS-off savings /
   investments rules arrive without a budget row: that tracking row is
   created. With ?mode=propose a SPENDING category with no budget is not
   created here — the rule comes back as "needs_budget" and the user
   confirms the budget from the proposal the rules PUT returned (EQ-72
   ruling 4). An older client gets the budget created as before.
2. Reset period_start_date to today (new period)
3. Mark virtual_pot_funded_at = now
4. Return confirmation

monthly_limit is never changed here. No money moves — this is purely
tracking.

## Query parameters

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

## Request body

- VirtualPotRequest
  - `rules` VirtualPotRule[], required
    - `rule_id` string, required
    - `category` string, required
    - `amount` number, required
    - `label` string, required

## Response `200`

Successful Response

- VirtualPotResponse
  - `results` VirtualPotResult[], required
    - `rule_id` string, required
    - `category` string, required
    - `amount` number, required
    - `label` string, required
    - `status` string, required

## 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)