Set Reference Override
POST/api/ledger/entries/:entry/reference-override
Set or clear the entry's durable reference override. The override is the custom reference shown in SKU and SENT TO THE ACCOUNTING PROVIDER (Xero/QBO) as the reference / invoice number, in place of the auto-derived reference. Like sync_override it is durable user intent — carried across draft regeneration and posted reversal+replacement — and the original reference is always retained for traceability.
Any valid API token can call this endpoint — no specific scope required. Manage tokens.
Authentication: Requires Bearer token.
Request body fields:
reference(required-present, nullable string, max 191) — the custom reference. Send an empty string ornullto clear the override back to the derived reference.
The key MUST be present (HTTP 422 if omitted). The response echoes the entry id, the derived reference, the saved reference_override, and display_reference (= override ?? reference, what the UI shows and what syncs). Returns 404 when the entry does not exist.
Permission: requires accounting.sync.
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.