Skip to main content
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

{
  "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: 
{
  "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

{
  "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: 
{
  "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 (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

{
  "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: 
{
  "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: 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: 
{
  "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: 
{
  "value": {
    // Setting specific fields based on key type
  }
}
Response: 
{
  "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: 
{
  "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 where you need different thresholds.