Refresh Journal Entry
POST/api/ledger/entries/:entry/refresh
Refresh this entry's amounts from its SOURCE document IN PLACE — the light counterpart to Rebuild. Where Rebuild corrects a posted entry by writing a reversal + a replacement, Refresh re-derives the entry's lines and totals and writes them onto the SAME entry: its id, status and accounting-provider link are all kept, so a posted, already-synced entry whose local figure drifted is corrected WITHOUT creating a new entry and WITHOUT touching the linked Xero / QuickBooks document. After the rewrite the sync state is re-graded — a still-editable remote is offered an update, while a settled/locked or voided remote is left as-is (nothing is pushed).
Authentication: Requires Bearer token.
Request body: none.
Response: 200 with data.refresh ({ refreshed, reason, period_locked }) and data.entry (the refreshed entry object). refreshed is false with a reason when there is nothing to do: already_current (the entry already matches its source), batched (the entry rolls into a batch aggregate — rebuild the batch instead), generation_disabled, or source_no_longer_produces_entry (the source stopped producing this entry — use Rebuild to reverse it). period_locked is reported (never enforced): true when the entry is dated in a locked accounting period, so the caller can warn that an in-place edit changes a closed period. message summarises the outcome.
Permission: requires accounting.sync (granular permissions; admins bypass; unenforced when the tenant's granular_permissions feature flag is off). Returns 403 without it; 404 when the entry does not exist.
Request
Responses
- 200
- 401
- 403
- 404
- 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.
Not found — no record with the given identifier (or the route does not exist). Verify the ID before retrying.
Validation failed — the body is a field → messages map (Laravel shape) or the platform envelope with a stable machine-readable code. Fix the payload and resubmit.
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.