Platform

Organization settings

An organization is the top-level tenant boundary in Kontorion. The /v1/organization-settings surface exposes a typed catalog of well-known keys - payment terms, webhook retry budgets, FX / price / tax resolution policies, wallet limit defaults, and more. Every value is stored as a string and validated against its catalog entry on write. Catalog entries that aren't overridden fall back to documented defaults.

Adjacent endpoints (/v1/organization, /v1/organization/tax-profile, /v1/organization-security, /v1/organization/domains) cover org metadata and identity-side configuration that doesn't fit the key/value catalog.

Reading settings

Code
curl https://api.kontorion.eu/v1/organization-settings \
  -H "Authorization: Bearer sk_…"

Returns the effective value for every catalog key - overrides where the org has set one, defaults everywhere else - with a source field per key:


Code
[
  { "key": "payment_terms_days",     "value": "30",   "source": "default",  "type": "int",    "category": "invoicing", "label": "Payment Terms (days)" },
  { "key": "webhook_max_retries",    "value": "10",   "source": "override", "type": "int",    "category": "webhooks",  "label": "Max Retries" },
  { "key": "fx_policy",              "value": "period_start", "source": "override", "type": "string", "category": "invoicing", "label": "FX Policy" }
]

source: "default" means the org has never written this key - the catalog default applies. source: "override" means the org has an explicit value.

Writing settings

Settings are upserted in bulk through a single map of key → string value:

Code
curl -X PUT https://api.kontorion.eu/v1/organization-settings \
  -H "Authorization: Bearer sk_…" \
  -d '{
    "settings": {
      "payment_terms_days":  "45",
      "webhook_max_retries": "10",
      "fx_policy":           "period_start"
    }
  }'

Per-key validation runs against the catalog before any write - an invalid value rejects the whole request with a field-level error pointing at the offending key. Per-key PUT/GET endpoints don't exist; use the bulk shape and pick the keys you care about.

All values are sent as strings, regardless of their declared type:

`type`	Wire format
`string`	Literal string
`int`	Integer as string, e.g. `"30"`
`bool`	`"true"` / `"false"`
`duration`	Go duration syntax: `"5m"`, `"1h"`
`json`	JSON document as a string, e.g. `"[7200, 43200, 86400]"`

The catalog

Code
curl https://api.kontorion.eu/v1/organization-settings/catalog \
  -H "Authorization: Bearer sk_…"

Returns every well-known key with its type, default, category, label, and description. Use it to drive a settings UI without hard-coding the list client-side - new keys ship in the catalog without any client change.

Category	Examples
`invoicing`	`invoice_prefix`, `payment_terms_days`, `auto_finalize_invoices`, `invoice_footer`, `date_format`, `default_expense_markup`, `fx_policy`, `price_resolution_policy`, `line_grouping`
`billing`	`grace_period_days`, `suspension_delay_days`, `hold_duration_minutes`, `default_timezone`, wallet limit defaults (`default_credit_limit`, `default_max_balance`, `default_max_single_credit`, `default_low_balance_threshold`, `default_auto_topup_enabled`, `default_auto_topup_amount`), `payment_retry_schedule_seconds`, `subscription_pause_on_payment_error`
`webhooks`	`webhook_max_retries`, `webhook_timeout_secs`
`tax`	`tax_inclusive`, `tax_resolution_policy`
`notifications`	`send_payment_reminders`, `notify_invoice_created`, `notify_payment_failed`

Selected entries

Key	Type	Default	What it controls
`payment_terms_days`	int	`30`	Default `due_date = invoice.issued_at + N days`. Bounded `[0, 365]`
`auto_finalize_invoices`	bool	`false`	Auto-finalize draft invoices after generation
`invoice_prefix`	string	`INV`	Prefix for the invoice-number sequence (1–10 chars)
`webhook_max_retries`	int	`6`	Cap on retry attempts before webhook deliveries are exhausted. Bounded `[1, 20]`
`webhook_timeout_secs`	int	`30`	HTTP timeout per webhook delivery attempt. Bounded `[5, 120]`
`fx_policy`	string	`invoice_issue`	Which FX timestamp shapes converted amounts - see Exchange rates
`price_resolution_policy`	string	`per_segment`	Which point-in-time the pricing resolver uses (`per_segment`, `period_start`, `invoice_issue`)
`tax_resolution_policy`	string	`period_start`	Same axis for tax rule selection
`line_grouping`	string	`expanded`	How invoice lines are grouped from atoms (`expanded`, `per_key`, `per_product`)
`tax_inclusive`	bool	`false`	When true, displayed prices are gross (tax included)
`payment_retry_schedule_seconds`	json	`[7200, 43200, 86400]`	Delays (in seconds from failure) at which the payment-retry worker re-attempts a failed charge. Empty array disables retry
`subscription_pause_on_payment_error`	bool	`true`	When true, exhausting an invoice's retry budget escalates the subscription to `ERRORED`; when false the invoice errors but the subscription is left for operator action
`default_credit_limit`, `default_max_balance`, `default_max_single_credit`, `default_low_balance_threshold`, `default_auto_topup_enabled`, `default_auto_topup_amount`	string / bool	empty / `false`	Per-org defaults for the wallet limit cascade
`default_timezone`	string	`UTC`	Timezone used for billing-cycle calculations when a customer doesn't specify
`date_format`	string	`2006-01-02`	Go time format for dates on invoices and PDFs (allowed values enforced)

The catalog is the source of truth - GET /v1/organization-settings/catalog returns the live list with current types, defaults, and per-key descriptions. The table above is a static snapshot.

Adjacent surfaces

Some org-level configuration lives outside the key/value catalog:

Endpoint	Purpose
`GET / PUT /v1/organization`	Org profile - name, support email, locale, address
`GET / PUT /v1/organization/tax-profile`	`OrgTaxProfile` - VAT ID, supplier tax number, default supply type, regime (`STANDARD`, `KLEINUNTERNEHMER`, `OSS`, `NON_EU`)
`GET / PATCH /v1/organization-security`	Security policy - password rules, session policies
`GET / PUT /v1/organization/domains`	Email-domain → identity-provider mapping for SSO routing

Endpoints

All Organization Settings endpoints - the catalog GET, the effective-list GET, the bulk PUT.

Webhooks - webhook_max_retries, webhook_timeout_secs
Exchange rates - fx_policy selects which candidate shapes invoice totals
Pricing (advanced) - price_resolution_policy axis
Taxes - tax_resolution_policy and tax_inclusive
Wallets - the default_* wallet keys feed the per-customer / org cascade
Dunning - grace_period_days, suspension_delay_days interact with policy steps

Last modified on June 4, 2026

Custom Fields Members

Platform

Organization settings

Reading settings

Code
curl https://api.kontorion.eu/v1/organization-settings \
  -H "Authorization: Bearer sk_…"

Returns the effective value for every catalog key - overrides where the org has set one, defaults everywhere else - with a source field per key:


Code
[
  { "key": "payment_terms_days",     "value": "30",   "source": "default",  "type": "int",    "category": "invoicing", "label": "Payment Terms (days)" },
  { "key": "webhook_max_retries",    "value": "10",   "source": "override", "type": "int",    "category": "webhooks",  "label": "Max Retries" },
  { "key": "fx_policy",              "value": "period_start", "source": "override", "type": "string", "category": "invoicing", "label": "FX Policy" }
]

source: "default" means the org has never written this key - the catalog default applies. source: "override" means the org has an explicit value.

Writing settings

Settings are upserted in bulk through a single map of key → string value:

Code
curl -X PUT https://api.kontorion.eu/v1/organization-settings \
  -H "Authorization: Bearer sk_…" \
  -d '{
    "settings": {
      "payment_terms_days":  "45",
      "webhook_max_retries": "10",
      "fx_policy":           "period_start"
    }
  }'

All values are sent as strings, regardless of their declared type:

`type`	Wire format
`string`	Literal string
`int`	Integer as string, e.g. `"30"`
`bool`	`"true"` / `"false"`
`duration`	Go duration syntax: `"5m"`, `"1h"`
`json`	JSON document as a string, e.g. `"[7200, 43200, 86400]"`

The catalog

Code
curl https://api.kontorion.eu/v1/organization-settings/catalog \
  -H "Authorization: Bearer sk_…"

Category	Examples
`invoicing`	`invoice_prefix`, `payment_terms_days`, `auto_finalize_invoices`, `invoice_footer`, `date_format`, `default_expense_markup`, `fx_policy`, `price_resolution_policy`, `line_grouping`
`billing`	`grace_period_days`, `suspension_delay_days`, `hold_duration_minutes`, `default_timezone`, wallet limit defaults (`default_credit_limit`, `default_max_balance`, `default_max_single_credit`, `default_low_balance_threshold`, `default_auto_topup_enabled`, `default_auto_topup_amount`), `payment_retry_schedule_seconds`, `subscription_pause_on_payment_error`
`webhooks`	`webhook_max_retries`, `webhook_timeout_secs`
`tax`	`tax_inclusive`, `tax_resolution_policy`
`notifications`	`send_payment_reminders`, `notify_invoice_created`, `notify_payment_failed`

Selected entries

Key	Type	Default	What it controls
`payment_terms_days`	int	`30`	Default `due_date = invoice.issued_at + N days`. Bounded `[0, 365]`
`auto_finalize_invoices`	bool	`false`	Auto-finalize draft invoices after generation
`invoice_prefix`	string	`INV`	Prefix for the invoice-number sequence (1–10 chars)
`webhook_max_retries`	int	`6`	Cap on retry attempts before webhook deliveries are exhausted. Bounded `[1, 20]`
`webhook_timeout_secs`	int	`30`	HTTP timeout per webhook delivery attempt. Bounded `[5, 120]`
`fx_policy`	string	`invoice_issue`	Which FX timestamp shapes converted amounts - see Exchange rates
`price_resolution_policy`	string	`per_segment`	Which point-in-time the pricing resolver uses (`per_segment`, `period_start`, `invoice_issue`)
`tax_resolution_policy`	string	`period_start`	Same axis for tax rule selection
`line_grouping`	string	`expanded`	How invoice lines are grouped from atoms (`expanded`, `per_key`, `per_product`)
`tax_inclusive`	bool	`false`	When true, displayed prices are gross (tax included)
`payment_retry_schedule_seconds`	json	`[7200, 43200, 86400]`	Delays (in seconds from failure) at which the payment-retry worker re-attempts a failed charge. Empty array disables retry
`subscription_pause_on_payment_error`	bool	`true`	When true, exhausting an invoice's retry budget escalates the subscription to `ERRORED`; when false the invoice errors but the subscription is left for operator action
`default_credit_limit`, `default_max_balance`, `default_max_single_credit`, `default_low_balance_threshold`, `default_auto_topup_enabled`, `default_auto_topup_amount`	string / bool	empty / `false`	Per-org defaults for the wallet limit cascade
`default_timezone`	string	`UTC`	Timezone used for billing-cycle calculations when a customer doesn't specify
`date_format`	string	`2006-01-02`	Go time format for dates on invoices and PDFs (allowed values enforced)

The catalog is the source of truth - GET /v1/organization-settings/catalog returns the live list with current types, defaults, and per-key descriptions. The table above is a static snapshot.

Adjacent surfaces

Some org-level configuration lives outside the key/value catalog:

Endpoint	Purpose
`GET / PUT /v1/organization`	Org profile - name, support email, locale, address
`GET / PUT /v1/organization/tax-profile`	`OrgTaxProfile` - VAT ID, supplier tax number, default supply type, regime (`STANDARD`, `KLEINUNTERNEHMER`, `OSS`, `NON_EU`)
`GET / PATCH /v1/organization-security`	Security policy - password rules, session policies
`GET / PUT /v1/organization/domains`	Email-domain → identity-provider mapping for SSO routing

Endpoints

All Organization Settings endpoints - the catalog GET, the effective-list GET, the bulk PUT.

Webhooks - webhook_max_retries, webhook_timeout_secs
Exchange rates - fx_policy selects which candidate shapes invoice totals
Pricing (advanced) - price_resolution_policy axis
Taxes - tax_resolution_policy and tax_inclusive
Wallets - the default_* wallet keys feed the per-customer / org cascade
Dunning - grace_period_days, suspension_delay_days interact with policy steps

Last modified on June 4, 2026

Custom Fields Members

Organization settings

Reading settings

Writing settings

The catalog

Categories

Selected entries

Adjacent surfaces

Endpoints

Organization settings

Reading settings

Writing settings

The catalog

Categories

Selected entries

Adjacent surfaces

Endpoints

Reading settings

Writing settings

The catalog

Categories

Selected entries

Adjacent surfaces

Endpoints

Related

Reading settings

Writing settings

The catalog

Categories

Selected entries

Adjacent surfaces

Endpoints

Related