Batch Allocate to Purchase Invoice
POST/api/vendor-credits/allocate-batch
Apply several vendor credits to a single purchase invoice (bill) in one atomic batch. Powers the "Credit this bill" allocation flow, where a buyer distributes multiple outstanding credits from the same supplier against one bill at once. The whole batch is all-or-nothing: if any single allocation fails validation or over-allocates, none of them are saved.
Required fields:
purchase_invoice_id(int) — The bill to credit. Must exist.allocations(array, min 1) — One entry per credit to apply.allocations[].vendor_credit_id(int) — Must exist and belong to the same supplier and currency as the bill. Cannot be repeated within one request.allocations[].amount(float, >= 0.01) — Amount to allocate from that credit. Cannot exceed the credit's remaining balance.
Optional fields:
allocated_at(date) — Applied to every allocation in the batch. Defaults to now.notes(string, max 1000) — Applied to every allocation in the batch.
Validation: the sum of all amount values cannot exceed the bill's outstanding balance (gross total less cash paid, applied deposits, and already-applied credits). A violation returns 422 with no allocations saved.
Request
Responses
- 200
- 401
- 403
- 422
- 429
OK
Response Headers
Unauthenticated — the bearer token is missing, revoked, expired, or malformed. Never retry automatically; fix the credential. See the Errors guide.
Forbidden — the token lacks a required scope, the endpoint is not available to API tokens, or the user behind the token lacks the permission. A human must adjust the token scopes or user permissions; do not retry.
Unprocessable Entity
Response Headers
Rate limited — platform limit is 1,000 requests/min; individual tokens may carry lower limits. Honor the Retry-After header before retrying. See the Rate Limits guide.