Settings

• 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

• 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
• Bonus Credits Topup Configuration (bonus_credits_topup_config) — Slab-based bonus credit rules applied automatically to purchased wallet top-ups

​

Subscription Configuration

​

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

{
  "grace_period_days": 3,
  "auto_cancellation_enabled": false
}

​

What Happens When Auto-Cancellation Is Enabled

• 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

​

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

{
  "prefix": "INV",
  "format": "YYYYMM",
  "start_sequence": 1,
  "timezone": "UTC",
  "separator": "-",
  "suffix_length": 5,
  "due_date_days": 1
}

​

What You Get

​

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

​

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.

​

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

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

​

Bonus Credits Topup Configuration

​

Schema

{
  "enabled": boolean,
  "slabs": [
    {
      "threshold": string,
      "operator": "gte",
      "bonus": { "type": "flat" | "percentage", "value": string },
      "expiration_duration": number,
      "expiration_duration_unit": "DAY" | "WEEK" | "MONTH" | "YEAR"
    }
  ]
}

• enabled — Required. Boolean. Turn automatic slab-based bonus resolution on or off for this tenant and environment.
• slabs — Required and non-empty if enabled is true; optional otherwise. Array of slab objects, evaluated in list order, so they must be sorted descending by threshold. The first slab a top-up’s credit amount clears is the one that applies.
  • threshold — Required. Decimal string ≥ 0. The credit amount being purchased is compared against this value.
  • operator — Required. Only gte is accepted; the top-up’s credit amount must be greater than or equal to threshold to match.
  • bonus.type — Required. flat or percentage.
  • bonus.value — Required. Decimal string ≥ 0. For flat, this is the bonus credit amount added as-is. For percentage, this is a percentage of the credits being purchased.
  • expiration_duration / expiration_duration_unit — Optional; must be set together or not at all. Sets an expiry for bonus credits granted from this slab, unless the top-up request already sets bonus_credits_expiry_date_utc explicitly. Unit is one of DAY, WEEK, MONTH, YEAR.

​

Default Values

{
  "enabled": false,
  "slabs": []
}

​

What Happens When Enabled

• Applies only to purchased credits — Slab resolution runs only for top-ups with transaction_reason set to PURCHASED_CREDIT_DIRECT or PURCHASED_CREDIT_INVOICED (including pay-first checkout). Free credit top-ups never receive a bonus.
• Manual override skips resolution — If the top-up request sets bonus_credits_to_add directly, slab resolution does not run for that top-up.
• Bonus is a separate transaction — The bonus is recorded as its own wallet transaction with transaction_reason: PURCHASED_CREDIT_BONUS, linked to the purchase transaction via parent_transaction_id. It shares the purchase transaction’s status and completes with it.

​

Validation

• New settings: enabled required, boolean. If enabled is true, slabs required, non-empty.
• Slab constraints: operator must be gte; threshold ≥ 0; bonus.type one of flat, percentage; bonus.value ≥ 0; expiration_duration and expiration_duration_unit must both be set or both omitted; slabs must be sorted strictly descending by threshold.
• Updates: Partial updates allowed; only provided fields validated; omitted fields unchanged.

​

API Endpoints

​

Get Setting

GET /v1/settings/:key

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

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

• 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

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

{
  "value": {
    // Setting specific fields based on key type
  }
}

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

• 400 Bad Request: Invalid setting key or validation failed
• 403 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

DELETE /v1/settings/:key

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

{
  "message": "Setting deleted successfully"
}

• 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

​

Bonus Credits on Top-Up

• Volume incentives — Grant a larger bonus on bigger top-ups (e.g. 10% bonus at $200+) to encourage customers to purchase more credits at once
• Flat promotional bonus — Grant a fixed bonus amount for top-ups that clear a lower threshold (e.g. 50 bonus credits at $100+)
• Automatic, no per-request work — Configure the slab table once; the bonus is resolved on every purchased-credit top-up without callers passing bonus fields

​

Best Practices

​

Related Documentation

• Wallet Sentinel Alerts — Configure per-wallet balance alerts
• Top-Up Wallet — Slab-based and manual bonus credits on purchased wallet top-ups
• Subscriptions — Manage customer subscriptions
• Invoices — Invoice lifecycle and payment tracking