Skip to main content

Update Granularity Matrix

PUT 
/api/ledger/settings/granularity

Validate, clamp and persist the type × channel granularity matrix. Returns the matrix AS SAVED — the client must re-render from the response because of the server-side clamp.

Authorization

Any valid API token can call this endpoint — no specific scope required. Manage tokens.

Authentication: Requires Bearer token.

Request body fields:

  • matrix (present, object) — MAY be an empty object {}: an empty matrix clears all stored overrides back to the legacy per-type defaults
  • matrix.<type> (object) — keyed by AccountingTransactionTypeEnum value (e.g. sales_order_invoice, 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 EXISTING integration instance ID (string keys); unknown IDs are rejected
  • matrix.<type>.channels.<id> (string) — off | per_document | daily | monthly

Server-side FBA clamp: FBA monthly-only types (fba_adjustments, fba_customer_returns, fba_receipts, fba_shipments, fba_vendor_returns, fba_warehouse_transfers, amazon_pending_inbound_shipment) are clamped server-side — daily / per_document become monthly; off survives. The clamp is never trusted to the client.

Validation errors (422): unknown type key, invalid granularity value, non-object type/channels config, or non-existent channel integration instance ID — all reported under the matrix key.

Returns 404 when no accounting connection is configured.

Permission: requires accounting.manage_settings (granular permissions; admins bypass; unenforced when the tenant's granular_permissions feature flag is off). Returns 403 without it.

Request​

Responses​

OK

Response Headers
    Content-Type