FlexPrice Settings Guide
This guide documents the configuration settings available in FlexPrice, their usage, and implementation details. Settings are managed at the tenant × environment level, providing complete isolation between different environments within and across tenants.Table of Contents
Settings Overview
Settings in FlexPrice are:- Scoped: Per tenant and environment
- Cached: With 1-hour TTL
- Validated: With strict type checking and value constraints
- Audited: All changes are tracked
- Isolated: Complete tenant and environment isolation
- Mergeable: Support partial updates without losing existing values
Available Settings
Subscription Configuration
Key:subscription_config
Purpose: Controls subscription auto-cancellation behavior for unpaid invoices.
Schema:
-
For NEW settings:
grace_period_days
:- Required field
- Must be integer >= 1
- Must be a whole number (no decimals)
auto_cancellation_enabled
:- Optional field
- Must be boolean if provided
- Defaults to false if not provided
-
For UPDATES:
- Partial updates are supported
- Only provided fields are validated
- Same validation rules apply as for new settings
- Omitted fields preserve existing values
- System periodically checks all ACTIVE subscriptions in tenants with auto-cancellation enabled
- For each subscription, it evaluates unpaid invoices where:
- Invoice has remaining amount > 0 OR payment_status != succeeded
- Current time is after invoice due date
- Current time is after (due_date + grace_period_days)
- When eligible:
- Subscription is cancelled immediately (not at period end)
- Webhook event
subscription.canceled
is emitted - All future credit grants are cancelled
- Final invoice is generated for the partial period if not end-of-period cancellation
- System logs and metadata capture:
- In application logs:
- Cancellation reason: “grace_period_expired”
- Cancelled by: “auto_cancellation_system”
- Grace period duration
- Tenant and environment IDs
- In subscription metadata:
- Cancellation type: “immediate”
- Effective date (in RFC3339 format)
- Cancellation timestamp (in cancelled_at field)
- In application logs:
Invoice Configuration
Key:invoice_config
Purpose: Controls invoice number generation, formatting, and due date calculation.
Schema:
-
For NEW settings:
- Invoice Sequence Prefix Settings
prefix
:- Required field
- Must be non-empty string
- Cannot be only whitespace
format
:- Required field
- Must be one of:
YYYYMM
,YYYYMMDD
,YYMMDD
,YY
,YYYY
start_sequence
:- Required field
- Must be integer >= 0
- Must be a whole number (no decimals)
timezone
:- Required field
- Must be valid IANA timezone or common abbreviation
- Cannot be empty string
separator
:- Required field
- Must be string (empty string allowed)
suffix_length
:- Required field
- Must be integer between 1 and 10
- Auto Canellation Settings
due_date_days
:- Must be integer >= 0 if provided
- Must be a whole number (no decimals)
- Invoice Sequence Prefix Settings
-
For UPDATES:
- Partial updates are supported
- Only provided fields are validated
- Same validation rules apply as for new settings
- Omitted fields preserve existing values
- Can update only
due_date_days
without other fields
-
Format Pattern:
{prefix}{separator}{formatted_date}{separator}{padded_sequence}
-
Sequence numbers:
- Reset monthly based on the format (e.g., monthly for YYYYMM)
- Padded with zeros to match suffix_length
- Tenant and environment isolated
-
Example with separator:
-
Example without separator:
-
IANA Timezone Names (Recommended):
- America/New_York
- Europe/London
- Asia/Tokyo
- UTC
-
Common Abbreviations:
- US: EST, CST, MST, PST, HST, AKST
- Europe: GMT, CET, EET, WET, BST
- Asia: IST, JST, KST, CCT
- Australia: AEST, AWST
- Others: MSK, CAT, EAT, WAT
API Endpoints
Get Setting
key
(path): Required. One of:subscription_config
,invoice_config
404 Not Found
: Setting not found for tenant × environment400 Bad Request
: Invalid setting key403 Forbidden
: Missing tenant or environment context
Create/Update Setting
key
(path): Required. One of:subscription_config
,invoice_config
400 Bad Request
: Invalid setting key or validation failed403 Forbidden
: Missing tenant or environment context
- 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
key
(path): Required. One of:subscription_config
,invoice_config
404 Not Found
: Setting not found for tenant × environment400 Bad Request
: Invalid setting key403 Forbidden
: Missing tenant or environment context
- All endpoints require authentication
- All endpoints require tenant and environment context
- All operations are audited with:
- User ID performing the action
- Timestamp
- Previous and new values (for updates)
- Action type (create/update/delete)
- Settings are uniquely identified by (tenant_id, environment_id, key)
- All responses include standard error format for validation failures
- All endpoints respect tenant isolation
Best Practices
-
Initialization:
- Always provide all required fields when creating new settings
- Default values only apply when using API creation
- Validate all required fields before submission
- Use IANA timezone names instead of abbreviations when possible
-
Updates:
- Use partial updates to modify only needed fields
- Existing values are preserved automatically
- No need to provide all fields in updates
- Only provided fields are validated
-
Monitoring:
- Track setting changes in audit logs
- Monitor auto-cancellation events
- Review grace period effectiveness
- Watch for timezone-related issues
-
Security:
- Only admin users should modify settings
- Verify tenant context on all operations
- Use tenant-specific API keys
- Audit all setting changes
-
Performance:
- Settings are cached with 1-hour TTL
- Use partial updates to minimize data transfer
- Consider timezone impact on operations
- Monitor sequence number resets