🔁 POST /distribute

Distributes a specified amount from a parent account to its child accounts according to their allocation rules.

📌 Summary

Method: POST
URL: /distribute
Auth: Required
Tag: accounts

🔐 Headers

Authorization: Bearer <your-token>
Content-Type: application/json

📤 Request Parameters

Name	Type	Required	Description
`uuid`	string	✅	UUID of the parent account
`amount`	float	✅	Amount to distribute (must be > 0)
`transaction`	string	❌	Optional transaction reference (autogenerated if NULL)
`by`	string	❌	Who performed the distribution (default = “System”)

📥 Example Request

{
  "uuid": "parent-acc-2023-001",
  "amount": 5000,
  "transaction": "dist-INV004",
  "by": "System"
}

✅ Success Response

{
  "success": true,
  "status": 200,
  "message": "Distributed 5000 from Needs",
  "uuid": "parent-acc-2023-001",
  "start_time": "2025-07-10T10:01:15.120Z",
  "end_time": "2025-07-10T10:01:15.180Z",
  "execution_time": 0.06
}

❌ Failure Response Examples

Status	Reason
`403`	Unauthorized to access the account
`404`	Account not found
`500`	Invalid amount, zero, negative, or missing account

🧠 Notes

Automatically uses account$distribute_to_children() internally.
Locks the account tree for safe concurrent execution.
Will fail if amount is missing, zero, or negative.
If transaction reference is missing, one is auto-generated.

💖 Sponsors

Support my work through GitHub Sponsors!