Available Policies
MIDDAG Account includes 10 configurable policies. Each policy controls a specific aspect of entitlement behavior. This page is the complete reference -- every field, every default, every option.
For how the override hierarchy works, see Policy Hierarchy. For step-by-step configuration, see Configuring Policies.
Renewal Policy
What it controls: Automatic renewal behavior, grace windows before expiration, and pricing on renewal.
When it matters: Every billing cycle, when an entitlement approaches its expiration date.
| Field | Default | Options / Range | Description |
|---|---|---|---|
auto_renew | true | true / false | Automatically renew before expiration |
grace_days_pre_expiry | 7 | Integer (days) | Days before expiry to attempt the renewal charge |
renewal_pricing | same | same / current | same = original price; current = current catalog price |
early_renewal_days | 30 | Integer (days) | How early a customer can manually renew |
renewal_reminder_days | [30, 7, 1] | List of integers | Days before expiry to send renewal reminders |
failed_renewal_retries | 3 | Integer | Retry attempts for a failed renewal charge |
block_downgrade_at_renewal | false | true / false | Prevent plan downgrades during the renewal window |
Example scenario: A service contract (SVC class) renews at the current catalog price instead of the original price, and downgrades are blocked during the renewal window. The SVC class overrides renewal_pricing: current and block_downgrade_at_renewal: true.
Payment Recovery Policy
What it controls: How the system responds to failed payments -- when to suspend, how long to wait before cancellation, and whether to auto-reactivate.
When it matters: When a credit card expires, a charge is declined, or a bank transfer fails.
| Field | Default | Options / Range | Description |
|---|---|---|---|
trigger | retry_exhausted | first_failure / retry_exhausted | When to suspend: on first failure or after all retries |
anticipate_suspension | false | true / false | Pre-suspend customers with a history of payment issues |
suspended_to_cancelled_days | 30 | Integer (days) | Days in suspended state before automatic cancellation |
auto_reactivate_on_payment | true | true / false | Reactivate automatically when payment succeeds |
Example scenario: Plugin entitlements (PLG class) use a shorter suspension window of 14 days because plugins are inexpensive and easily re-purchased. Environment entitlements (ENV class) use 15 days because a suspended hosting environment is urgent for the customer.
Cancellation Policy
What it controls: What happens after an entitlement expires -- portal visibility, automatic cancellation timing, and data retention.
When it matters: When an entitlement expires and is not renewed, or when a customer cancels.
| Field | Default | Options / Range | Description |
|---|---|---|---|
portal_visibility_days | 90 | Integer (days) | Days an expired entitlement stays visible in the portal |
expired_to_cancelled_days | 30 | Integer (days) | Days in expired state before automatic cancellation |
data_retention_days | 365 | Integer (days) | Days to keep operational data after cancellation |
data_action | export_and_delete | export_and_delete / archive / retain | What to do with customer data on cancellation |
offer_data_export | true | true / false | Offer data export during the cancellation flow |
Important: Tax and fiscal data follows legal retention periods (LGPD, tax law) and is NOT controlled by this policy. Only operational data is affected.
Example scenario: Plugin entitlements (PLG class) use archive instead of export_and_delete because license data is lightweight and customers may reactivate later. Data retention is set to 90 days instead of 365.
SLA Policy
What it controls: Service level targets for response times, resolution times, uptime, and escalation behavior. Uses a 4-tier model: Standard, Priority, Critical, and Dedicated.
When it matters: Every time a service request is created against an entitlement.
| Field | Default | Options / Range | Description |
|---|---|---|---|
sla_level | standard | standard / priority / critical / dedicated | Which SLA tier applies (determines response targets) |
response_time | (tiered, see below) | Object with per-level, per-priority targets | First response time targets |
resolution_time | (tiered, see below) | Object with per-level, per-priority targets | Resolution time targets |
uptime_target | 99.5% | Percentage string | Uptime target (managed environments only) |
support_hours | business_hours | business_hours / extended / 24x7 | Support availability window |
escalation_enabled | true | true / false | Auto-escalate when SLA breach is approaching |
escalation_after_pct | 80 | Integer (percentage) | Percentage of SLA time to trigger escalation |
priority_levels | [low, normal, high, urgent] | List of priorities | Available priority levels for service requests |
SLA tiers -- Standard response time targets:
| Priority | Response | Resolution |
|---|---|---|
| P1 | 8h | 2 days |
| P2 | 1 day | 3 days |
| P3 | 2 days | 5 days |
| P4 | 3 days | 7 days |
| P5 | 5 days | 10 days |
SLA tiers -- Priority response time targets:
| Priority | Response | Resolution |
|---|---|---|
| P1 | 4h | 1 day |
| P2 | 8h | 2 days |
| P3 | 1 day | 3 days |
| P4 | 2 days | 5 days |
| P5 | 3 days | 7 days |
SLA tiers -- Critical response time targets:
| Priority | Response | Resolution |
|---|---|---|
| P1 | 2h | 8h |
| P2 | 4h | 1 day |
| P3 | 8h | 2 days |
| P4 | 1 day | 3 days |
| P5 | 2 days | 5 days |
SLA tiers -- Dedicated response time targets:
| Priority | Response | Resolution |
|---|---|---|
| P1 | 30 min | 2h |
| P2 | 1h | 4h |
| P3 | 2h | 8h |
| P4 | 4h | 1 day |
| P5 | 8h | 2 days |
All times are in business hours (9:00-18:00 BRT, Mon-Fri) unless support_hours is set to extended or 24x7.
Example scenario: Service entitlements (SVC class) default to Priority SLA with extended support hours and earlier escalation (at 70% of SLA time instead of 80%). Environment entitlements (ENV class) use Standard SLA but with a higher uptime target of 99.9%.
Credit Policy
What it controls: How service credits (UST) behave -- expiration, grace periods, consumption order, and overdraft limits.
When it matters: For entitlements that include a credit balance, typically service contracts (SVC class).
| Field | Default | Options / Range | Description |
|---|---|---|---|
expiration_months | 12 | Integer (months) | Months until plan-included credits expire |
grace_before_days | 0 | Integer (days) | Grace days before expiration |
grace_after_days | 30 | Integer (days) | Grace days after expiration before credits are lost |
block_on_limit_exceeded | false | true / false | Block new service requests when balance is negative |
limit_threshold | 0 | Integer (credits) | Negative credit balance allowed before blocking (0 = none) |
avulso_expiration_months | 6 | Integer (months) | Expiration for credits purchased as one-off top-ups |
consumption_order | fifo | fifo / lifo | fifo = oldest credits used first; lifo = newest first |
Example scenario: An enterprise organization negotiates 24-month credit expiration instead of the standard 12 months. This is set as an organization-level override: expiration_months: 24.
Provisioning Policy
What it controls: Whether access is set up automatically after purchase, or requires manual admin approval. Also controls webhook notifications and deprovisioning on cancellation.
When it matters: Immediately after a successful payment, when the entitlement is created.
| Field | Default | Options / Range | Description |
|---|---|---|---|
auto | true | true / false | Auto-provision on payment, or require manual approval |
require_approval | none | none / admin / both | Who must approve when provisioning is manual |
webhook_enabled | false | true / false | Notify an external system after provisioning |
retry_on_failure | true | true / false | Retry provisioning if it fails |
max_retries | 3 | Integer | Max retry attempts before permanent failure |
timeout_minutes | 30 | Integer (minutes) | Minutes before marking provisioning as failed |
notify_admin_on_manual | true | true / false | Send admin notification when manual provisioning needed |
deprovision_on_cancel | false | true / false | Automatically remove resources when entitlement cancelled |
Example scenario: Plugin entitlements (PLG class) are fully automatic -- purchase triggers instant license generation. Service entitlements (SVC class) override to manual provisioning (auto: false, require_approval: admin) because contracts require human validation and Jira workspace setup. Environment entitlements (ENV class) enable deprovision_on_cancel: true to shut down hosting environments when cancelled.
Trial Policy
What it controls: Free trial availability, duration, auto-conversion to paid, and abuse prevention.
When it matters: When a prospective customer wants to try a product before committing.
| Field | Default | Options / Range | Description |
|---|---|---|---|
enabled | false | true / false | Whether trials are available at this level |
duration_days | 14 | Integer (days) | Trial length |
auto_convert | true | true / false | Auto-convert to paid subscription when trial ends |
require_payment_method | false | true / false | Require a credit card to start the trial |
max_trials_per_org | 1 | Integer | Max trials per organization (prevents abuse) |
extend_allowed | false | true / false | Allow an admin to extend a trial manually |
notification_days_before_end | [3, 1] | List of integers | Days before trial end to notify the customer |
Example scenario: Trials are disabled globally but enabled for the Environment class (ENV) to let schools test the Campus EAD hosting platform. The ENV class override sets enabled: true and require_payment_method: true to prevent abuse of cloud provisioning resources.
Refund Policy
What it controls: Refund eligibility window, automatic vs manual approval, thresholds, and what happens to the entitlement and credits after a refund.
When it matters: When a customer requests a refund after purchase.
| Field | Default | Options / Range | Description |
|---|---|---|---|
refund_window_days | 30 | Integer (days) | Days after purchase to request a refund |
auto_refund | false | true / false | Auto-approve refunds within the window (up to max amount) |
auto_refund_max | 100.00 | Decimal or multi-currency object | Maximum amount for auto-refund; above this needs admin |
partial_allowed | true | true / false | Allow partial refunds proportional to usage |
approval_required | admin | none / admin | Who must approve refund requests |
cancel_entitlement | true | true / false | Cancel the entitlement after a full refund |
credits_on_refund | forfeit | forfeit / retain / proportional | What happens to unused credits on refund |
Example scenario: Plugin entitlements (PLG class) enable auto-refund for purchases under R$500 BRL / $100 USD, because plugins are low-risk and generous refund policies reduce support overhead. Service entitlements (SVC class) set refund_window_days: 0 because annual contracts have no refund period, though an admin can still approve exceptions.
Tier Change Policy
What it controls: How upgrades and downgrades work -- immediate vs next billing cycle, cooldown between changes, approval requirements, and credit adjustment.
When it matters: When a customer wants to switch to a higher or lower plan tier.
| Field | Default | Options / Range | Description |
|---|---|---|---|
effect | immediate | immediate / next_cycle | When the tier change takes effect |
downgrade_requires_approval | none | none / admin / client / both | Who must approve a downgrade |
cooldown_days | 0 | Integer (days) | Minimum days between tier changes (0 = no limit) |
credit_behavior | next_cycle | immediate / next_cycle / forfeit | How credits are adjusted on tier change |
Example scenario: Service entitlements (SVC class) override to effect: next_cycle (changes apply at the next billing cycle), downgrade_requires_approval: admin, and cooldown_days: 90 to prevent frequent plan flipping on annual contracts.
Notification Policy
What it controls: Which notification channels are active, which events trigger notifications, reminder timing, and opt-out settings.
When it matters: Throughout the entitlement lifecycle -- expiry warnings, payment alerts, renewal reminders, and more.
| Field | Default | Options / Range | Description |
|---|---|---|---|
channels | [email] | email, sms, whatsapp, portal | Active notification channels |
events | (see below) | List of event identifiers | Events that trigger notifications |
expiry_warning_days | [30, 7, 1] | List of integers | Days before expiry to send warnings |
credit_low_threshold_pct | 20 | Integer (percentage) | Credit balance percentage to trigger low-credit alert |
allow_opt_out | true | true / false | Let collaborators opt out of non-critical notifications |
Default notification events: expiry_warning, credit_low, payment_failed, payment_success, suspension, cancellation, renewal.
Example scenario: Service entitlements (SVC class) use earlier expiry warnings -- [60, 30, 7] instead of [30, 7, 1] -- because contract renewals require more lead time. Environment entitlements (ENV class) add the 1 day warning back to the extended list: [60, 30, 7, 1], because a hosting environment going offline is urgent.
Quick reference: Class-level defaults
This table shows which policies each entitlement class overrides from the global defaults:
| Policy | PLG (Plugin) | ENV (Environment) | SVC (Service) |
|---|---|---|---|
| Renewal | -- | -- | current pricing, block downgrade |
| Payment Recovery | 14d suspend | 15d suspend | -- |
| Cancellation | 30d visible, 14d expire, 90d retain, archive | 30d visible, 15d expire, 180d retain | -- |
| SLA | Standard, no escalation | Standard, 99.9% uptime, extended hours | Priority, extended hours, 70% escalation |
| Credit | -- | -- | Explicit FIFO, 30d grace |
| Provisioning | -- | deprovision on cancel | Manual, admin approval, deprovision |
| Trial | -- | Enabled, 14d, card required | -- |
| Refund | Auto to R$500/$100 | -- | 0d window, proportional credits |
| Tier Change | -- | -- | next_cycle, admin approval, 90d cooldown |
| Notification | -- | 60/30/7/1d warnings | 60/30/7d warnings |
-- means the class inherits the global default with no override.