Preview Granularity Change
POST/api/ledger/settings/granularity/preview
Show what saving a batching matrix would change — row by row — and how many existing documents a change applied now would re-batch. Read-only: validates exactly like Update Granularity Matrix and saves nothing.
accounting:writeGrant this scope to your token under Settings → Developer → Personal Access Tokens.
Authentication: Requires Bearer token.
Request body fields: same matrix as Update Granularity Matrix (apply_from is ignored).
matrix(present, object) — MAY be an empty object{}: an empty matrix clears all stored settings back to the per-type defaultsmatrix.<type>(object) — keyed by accounting transaction type (e.g. inventory_adjustment, sales_order_fulfillment, fba_shipments); unknown types are rejectedmatrix.<type>.default(required, string) —off|per_document|daily|monthlymatrix.<type>.channels(optional, object) — per-channel overrides keyed by an EXISTING sales channel integration instance ID (string keys); unknown IDs are rejectedmatrix.<type>.channels.<id>(string) —off|per_document|daily|monthlymatrix.<type>.history— ignored if sent; the server keeps it (see below)
Response (data.preview):
next_period_starts(date) — the 1st of next month, when anext_periodchange startsfirst_open_day(date|null) — the day after the accounting lock date; null when nothing is locked (anowchange would then re-batch every month)lock_date(date|null) — books are locked through this datetiming_choice_available(bool) — false when every changed row is an Amazon FBA/AWD row (those always start next month)changes[]— one per changed row (rows identical to what is saved are left out):type,label— the rowfrom,to— the default before and afterchannel_changes[]—{ channel_id, from, to }per changed channel cell (inherit= no override)channel_specific(bool) — only channel cells changed; the counts below then cover every channel, so treat them as an upper boundnext_period_only(bool) — an Amazon FBA/AWD rowopen_month_documents— documents of the type (and types that batch with it) dated in an open monthbatches_affected— summaries those documents sit in todaybatches_in_provider— of those, how many are already in the accounting provider (each would be updated or reversed by anowchange)individually_synced— documents already sent on their ownnew_summaries— about how many entries the new setting would send for the same documents (0 foroff, one per document forper_document)
Returns 404 when no accounting connection is configured; 422 for the same validation errors as Update.
Permission: requires accounting.manage_settings. Returns 403 without it.
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.
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.