> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flexprice.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Settings

> Configure subscription auto-cancellation, invoice numbering, and wallet balance alerts at the tenant and environment level.

Settings in Flexprice control behavior for respective environment against tenant, providing complete isolation between different environments within and across tenants. All settings are scoped to per (tenant, environment) pair, validated on write, cached for one hour, and audited.

**Benefits:**

* **Tenant and environment isolation** — Each tenant and environment has its own settings; no cross-contamination
* **Flexible updates** — Partial updates supported; only send the fields you want to change
* **Automatic caching** — Settings are cached for one hour to reduce latency
* **Audit trail** — All changes tracked with user and timestamp
* **Validated on write** — Strict type checking and value constraints prevent invalid configuration

## Available Settings

Flexprice supports three setting keys:

* **Subscription Configuration** (`subscription_config`) — Controls subscription auto-cancellation for unpaid invoices
* **Invoice Configuration** (`invoice_config`) — Controls invoice number generation and due date calculation
* **Wallet Balance Alert Configuration** (`wallet_balance_alert_config`) —  Wallet balance alert thresholds configurations per tenant per environment

***

## Subscription Configuration

**Key:** `subscription_config`

Controls subscription auto-cancellation for unpaid invoices. When enabled, subscriptions are automatically cancelled after grace period if invoices remain unpaid.

### Schema

```json theme={null}
{
  "grace_period_days": number,
  "auto_cancellation_enabled": boolean
}
```

* **`grace_period_days`** — Required for new settings; optional on update. Integer ≥ 1, no decimals. Number of days after invoice due date before auto-cancellation.
* **`auto_cancellation_enabled`** — Optional; defaults to `false`. Boolean. Enable or disable auto-cancellation for this tenant and environment.

### Default Values

When creating a new setting via API, defaults are:

```json theme={null}
{
  "grace_period_days": 3,
  "auto_cancellation_enabled": false
}
```

### What Happens When Auto-Cancellation Is Enabled

When you enable auto-cancellation and set a grace period:

* **Subscriptions with overdue unpaid invoices** — If an invoice remains unpaid past its due date plus the grace period, the subscription is cancelled immediately (not at the end of the billing period).
* **You get notified** — A `subscription.canceled` webhook is sent so you can sync your systems.
* **Clean shutdown** — Future credit grants for that subscription are cancelled, and a final invoice is generated for any partial period used.
* **Audit trail** — Cancellations are recorded with reason and metadata so you can see why and when a subscription was cancelled.

### Validation

* **New settings:** `grace_period_days` required, integer ≥ 1, no decimals. `auto_cancellation_enabled` optional, boolean, default `false`.
* **Updates:** Partial updates allowed; only provided fields validated; omitted fields unchanged.

***

## Invoice Configuration

**Key:** `invoice_config`

Controls invoice number generation (prefix, format, sequence, timezone) and due date calculation.

### Schema

```json theme={null}
{
  "prefix": string,
  "format": string,
  "start_sequence": number,
  "timezone": string,
  "separator": string,
  "suffix_length": number,
  "due_date_days": number
}
```

* **`prefix`** — Required for new settings; optional on update. Non-empty string, not only whitespace. Invoice number prefix (e.g. `"INV"`).
* **`format`** — Required for new settings; optional on update. One of `YYYYMM`, `YYYYMMDD`, `YYMMDD`, `YY`, `YYYY`. Date format in invoice number.
* **`start_sequence`** — Required for new settings; optional on update. Integer ≥ 0, no decimals. Starting sequence number.
* **`timezone`** — Required for new settings; optional on update. Valid IANA timezone (e.g. `America/New_York`, `UTC`) or common abbreviation (e.g. `EST`, `GMT`). Timezone for date formatting.
* **`separator`** — Required for new settings; optional on update. String (empty allowed). Character(s) between prefix, date, and sequence (e.g. `"-"`).
* **`suffix_length`** — Required for new settings; optional on update. Integer 1–10. Number of digits for sequence (padded with zeros).
* **`due_date_days`** — Optional; defaults to `1`. Integer ≥ 0, no decimals. Number of days after invoice creation to set due date.

### Default Values

When creating a new setting via API, defaults are:

```json theme={null}
{
  "prefix": "INV",
  "format": "YYYYMM",
  "start_sequence": 1,
  "timezone": "UTC",
  "separator": "-",
  "suffix_length": 5,
  "due_date_days": 1
}
```

### What You Get

Invoice numbers are generated in the format you configure: prefix, optional separator, date (based on your format and timezone), then a zero-padded sequence. Each tenant and environment has its own sequence, so numbers stay unique and predictable. The sequence resets according to the date format (e.g. monthly for `YYYYMM`, daily for `YYYYMMDD`).

**Example with separator:**

Configuration: `prefix: "INV"`, `format: "YYYYMM"`, `separator: "-"`, `suffix_length: 5`.

Generated: `INV-202501-00001`, `INV-202501-00002`.

**Example without separator:**

Configuration: `prefix: "INV"`, `format: "YYYYMM"`, `separator: ""`, `suffix_length: 5`.

Generated: `INV20250100001`, `INV20250100002`.

### Supported Timezones

* **IANA names (recommended):** `America/New_York`, `Europe/London`, `Asia/Tokyo`, `UTC`.
* **Common abbreviations:** `EST`, `CST`, `MST`, `PST`, `GMT`, `CET`, `EET`, `IST`, `JST`, `KST`, `AEST`, `AWST`, and more.

### Validation

* **New settings:** All fields except `due_date_days` required; see constraints above.
* **Updates:** Partial updates allowed; same rules for provided fields; omitted fields unchanged.

***

## Wallet Balance Alert Configuration

**Key:** `wallet_balance_alert_config`

Sets the **default** balance alert configuration for the tenant and environment. It applies only to wallets that do not have their own alert settings. Per-wallet alert configuration is done via [Wallet Sentinel Alerts](/docs/wallet/low-balance-alert) (or `alert_settings` on the wallet in the API).

### What This Setting Controls

* **When enabled** — Wallets in this tenant and environment that have no per-wallet alert settings use this config as their default. Balance alerts run for those wallets using the thresholds you set here.
* **When disabled** — Wallets that would otherwise use this default do not receive balance alerts until they have their own alert settings or you turn this setting back on.
* **Per-wallet overrides** — Any wallet with its own `alert_settings` always uses those; this setting only applies to wallets without per-wallet config.

Resolution order for a given wallet: Flexprice uses the wallet’s own alert settings if present; otherwise it uses this tenant-and-environment default. If the default is disabled, wallets without per-wallet settings do not receive balance alerts.

### Schema

```json theme={null}
{
  "alert_enabled": boolean,
  "critical": { "threshold": string, "condition": "below" | "above" },
  "warning":  { "threshold": string, "condition": "below" | "above" },
  "info":     { "threshold": string, "condition": "below" | "above" }
}
```

* **`alert_enabled`** — Required. Boolean. Turn alerts on or off at tenant and environment level.
* **`critical`**, **`warning`**, **`info`** — Optional. Each has `threshold` (string, e.g. `"0"`, `"-5"`, `"10"`) and `condition` (`"below"` or `"above"`).

### Default Value

When no custom value is stored (or after DELETE), the default is:

```json theme={null}
{
  "critical": { "threshold": "0", "condition": "below" },
  "alert_enabled": false
}
```

### Validation

* If `alert_enabled` is `true`, at least one of `critical`, `warning`, or `info` must be present.
* Threshold ordering: for `"below"`, critical \< warning \< info; for `"above"`, critical > warning > info (as applicable).

### Alert behavior (same as per-wallet alerts)

Once a wallet is using alert config (either its own or this default), behavior matches [Wallet Sentinel Alerts](/docs/wallet/low-balance-alert): balance is monitored against the thresholds, **Info** / **Warning** / **Critical** are raised when thresholds are crossed, state is updated on the wallet, and webhooks are sent when alert state changes.

## API Endpoints

### Get Setting

```
GET /v1/settings/:key
```

**Parameters**:

* `key` (path): Required. One of: `subscription_config`, `invoice_config`

**Response**:

```json theme={null}
{
  "value": {
    // Setting specific fields based on key type
  },
  "tenant_id": "string",
  "environment_id": "string",
  "created_at": "2024-01-01T00:00:00Z",
  "updated_at": "2024-01-01T00:00:00Z"
}
```

**Error Responses**:

* `404 Not Found`: Setting not found for tenant × environment
* `400 Bad Request`: Invalid setting key
* `403 Forbidden`: Missing tenant or environment context

### Create/Update Setting

```
PUT /v1/settings/:key
```

**Parameters**:

* `key` (path): Required. One of: `subscription_config`, `invoice_config`

**Request**:

```json theme={null}
{
  "value": {
    // Setting specific fields based on key type
  }
}
```

**Response**:

```json theme={null}
{
  "value": {
    // Complete setting after operation
  },
  "tenant_id": "string",
  "environment_id": "string",
  "created_at": "2024-01-01T00:00:00Z",
  "updated_at": "2024-01-01T00:00:00Z"
}
```

**Error Responses**:

* `400 Bad Request`: Invalid setting key or validation failed
* `403 Forbidden`: Missing tenant or environment context

**Behavior**:

* Single endpoint handles both creation and updates
* If setting doesn't exist for tenant × environment:
  * Creates new setting
  * All required fields must be provided
  * Default values applied for optional fields
* If setting exists for tenant × environment:
  * Updates existing setting
  * Supports partial updates
  * Only provided fields are validated
  * Omitted fields retain their existing values
  * No defaults are applied

### Delete Setting

```
DELETE /v1/settings/:key
```

**Parameters**:

* `key` (path): Required. One of: `subscription_config`, `invoice_config`

**Response**:

```json theme={null}
{
  "message": "Setting deleted successfully"
}
```

**Error Responses**:

* `404 Not Found`: Setting not found for tenant × environment
* `400 Bad Request`: Invalid setting key
* `403 Forbidden`: Missing tenant or environment context

***

## Use Cases

### Subscription Auto-Cancellation

* **SaaS with trial plans** — Auto-cancel free trials after grace period if no payment method is added
* **B2B billing** — Cancel subscriptions with overdue invoices after a grace period (e.g. 30 days)
* **Compliance** — Automatically stop service for customers who haven't paid within the grace period

### Invoice Numbering

* **Multi-region operations** — Use timezone to generate invoice numbers in the customer's local time
* **Custom branding** — Set prefix and separator to match your invoice format (e.g. `ACME-202501-00001`)
* **Sequence isolation** — Each tenant and environment has its own sequence; no conflicts

### Wallet Balance Alerts (Tenant and Environment Default)

* **Enable alerts for all wallets** — Set tenant and environment default so new wallets inherit alert config
* **Disable alerts globally** — Turn off async consumer for that environment by setting `alert_enabled: false`
* **Fallback for wallets without config** — Wallets with no `alert_settings` use this default

***

## Best Practices

💡 **Send required fields on create** — When creating a new setting, include all required fields; defaults apply only on API create.

💡 **Use partial updates** — Send only the fields you want to change; omitted fields keep their existing values.

💡 **Prefer IANA timezones** — For `invoice_config`, use IANA names (e.g. `America/New_York`) instead of abbreviations for clarity and daylight saving time support.

💡 **Set a default for wallet balance alerts** — Use `wallet_balance_alert_config` to define default thresholds for all wallets in this tenant and environment that don’t have their own alert settings. Enable it so those wallets get balance alerts; disable or DELETE to turn alerts off for them.

💡 **Restrict who can change settings** — Limit setting changes to admin users; use tenant-scoped API keys and review audit logs.

💡 **Match grace period to your dunning process** — Set `grace_period_days` to align with how long you allow overdue invoices before cancelling (e.g. after how many reminder emails or days).

💡 **Monitor auto-cancellation outcomes** — Use `subscription.canceled` webhooks to see which subscriptions were cancelled and adjust grace period or dunning if needed.

💡 **Use invoice prefix and format for traceability** — A clear prefix and consistent date format in invoice numbers make it easier to match invoices to periods and environments.

💡 **Combine with per-wallet alerts** — Set `wallet_balance_alert_config` as the default, then override on specific wallets via [Wallet Sentinel Alerts](/docs/wallet/low-balance-alert) where you need different thresholds.

***

## Related Documentation

* [Wallet Sentinel Alerts](/docs/wallet/low-balance-alert) — Configure per-wallet balance alerts
* [Subscriptions](/docs/subscriptions/customers-create-subscription) — Manage customer subscriptions
* [Invoices](/docs/invoices/overview) — Invoice lifecycle and payment tracking