Skip to main content

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.

Required scope: accounting:write

Grant 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 defaults
  • matrix.<type> (object) — keyed by accounting transaction type (e.g. inventory_adjustment, sales_order_fulfillment, fba_shipments); unknown types are rejected
  • matrix.<type>.default (required, string) — off | per_document | daily | monthly
  • matrix.<type>.channels (optional, object) — per-channel overrides keyed by an EXISTING sales channel integration instance ID (string keys); unknown IDs are rejected
  • matrix.<type>.channels.<id> (string) — off | per_document | daily | monthly
  • matrix.<type>.history — ignored if sent; the server keeps it (see below)

Response (data.preview):

  • next_period_starts (date) — the 1st of next month, when a next_period change starts
  • first_open_day (date|null) — the day after the accounting lock date; null when nothing is locked (a now change would then re-batch every month)
  • lock_date (date|null) — books are locked through this date
  • timing_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 row
    • from, to — the default before and after
    • channel_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 bound
    • next_period_only (bool) — an Amazon FBA/AWD row
    • open_month_documents — documents of the type (and types that batch with it) dated in an open month
    • batches_affected — summaries those documents sit in today
    • batches_in_provider — of those, how many are already in the accounting provider (each would be updated or reversed by a now change)
    • individually_synced — documents already sent on their own
    • new_summaries — about how many entries the new setting would send for the same documents (0 for off, one per document for per_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​

OK

Response Headers
    Content-Type