Configuring Policies

This page explains where and how to configure policies at each level of the hierarchy. Some configuration screens are fully implemented; others are planned. Each section notes the current status.

For background on what each policy does, see Available Policies. For how the hierarchy resolves values, see Policy Hierarchy.

Overview: where policies live

Level	Configuration location	Status
Global	WP Admin > MIDDAG Account > Settings > Policies	Implemented
Entitlement Class	YAML files in docs/commerce/policies/	Implemented
Organization	WP Admin > Organization > Edit > Policies tab	Planned
Product	Product YAML policies: block	Implemented
Individual Entitlement	WP Admin > Entitlement > Edit > Policies tab	Planned

---

Level 1: Global policies

Location: WP Admin > MIDDAG Account > Settings > Policies

Global policies are the baseline. Every field has a default value defined in the policy schema, and the global settings override those defaults for your entire installation.

Source of truth: The file docs/commerce/policies/global.yaml defines all global policy values. Changes to this file are synced to the WordPress database via composer policies:sync (sync tooling is in development).

What to configure here:

• Renewal behavior for all entitlements (auto-renew, grace period, pricing)
• Payment recovery defaults (when to suspend, how long before cancellation)
• Notification channels and timing
• SLA baseline tier and targets
• Refund window and approval rules
• Credit expiration and consumption order

How it works:

1. Navigate to WP Admin > MIDDAG Account > Settings.
2. Select the Policies tab.
3. Each policy is displayed as a collapsible section with all its fields.
4. Edit the values you want to change.
5. Save. All entitlements without a more specific override will use these values.

Tip: The global level should reflect your most common business case. Override at lower levels only where needed.

---

Level 2: Entitlement Class policies

Location: YAML files in docs/commerce/policies/

Class-level policies define rules that apply to all entitlements of a given type. The system ships with classes: PLG (Plugin), ENV (Environment), SVC (Service), ORD (Order), AFL (Affiliate), and EDU (Education).

Files:

File	Applies to
class-plg.yaml	Plugin entitlements
class-env.yaml	Environment entitlements
class-svc.yaml	Service entitlements
class-ord.yaml	Order-based entitlements
class-afl.yaml	Affiliate entitlements
class-edu.yaml	Education entitlements

How it works:

Class YAML files only include the fields that differ from the global defaults. Any field not present in the class file is inherited from the global level.

For example, class-plg.yaml overrides the payment recovery suspension window to 14 days but does not set a renewal policy -- so PLG entitlements inherit the global renewal defaults.

What to configure here:

• SLA tier and support hours per class (e.g., SVC gets Priority, PLG gets Standard)
• Provisioning mode (auto for PLG, manual for SVC)
• Trial availability (enabled for ENV, disabled for others)
• Refund terms per class (generous for PLG, zero for SVC)
• Cancellation timelines per class

Editing class policies:

1. Open the appropriate class-*.yaml file in docs/commerce/policies/.
2. Add or modify only the fields you want to override.
3. Run the sync command to apply changes: composer policies:sync (in development).

Important: Class files must include _class: PLG (or the appropriate class code) in the YAML header for validation.

---

Level 3: Organization policies

Status: [Planned]

Planned location: WP Admin > Organizations > [Organization Name] > Edit > Policies tab

Organization-level policies let you set customer-specific rules. This is where you configure negotiated terms for enterprise customers, stricter rules for customers with payment issues, or extended credit periods for strategic accounts.

How it will work:

1. Navigate to WP Admin > Organizations.
2. Click the organization you want to configure.
3. Open the Policies tab.
4. You will see a list of all 10 policies, each showing the currently effective value (inherited or overridden).
5. To override a field, toggle the override switch and enter the new value.
6. Overridden values are highlighted to distinguish them from inherited values.
7. Save. All entitlements owned by this organization will use these values (unless a product or entitlement override is more specific).

Design goals for the admin screen:

• Show the effective value for each field (where it comes from in the hierarchy).
• Show the inherited value alongside any override, so the admin knows what they are changing from.
• Provide a Reset button per field to remove the override and fall back to the inherited value.
• Log all policy changes in the organization audit trail.

What to configure here:

• Extended credit expiration for enterprise deals
• Longer payment recovery periods for customers with slow procurement
• Custom SLA tier for contracted customers
• Adjusted notification timing

---

Level 4: Product policies

Location: Product YAML file, policies: block

Product-level policies let you set rules for a specific WooCommerce product. All entitlements created from purchases of that product inherit these values.

How it works:

Each product YAML file in the commerce catalog can include a policies: block that overrides specific fields. Only include the fields you want to override.

# Example: product YAML for a premium hosting plan
name: "Campus EAD Business"
sku: "ENV-CAMPUS-BIZ"
policies:
  sla:
    sla_level: priority
    uptime_target: "99.95%"
  trial:
    duration_days: 30

In this example, the product overrides the SLA level to Priority and extends the trial to 30 days. All other fields inherit from the class (ENV) or global levels.

What to configure here:

• Product-specific SLA targets (higher uptime for premium plans)
• Different trial durations per product
• Tier change cooldowns for specific products
• Custom refund windows for specific products

---

Level 5: Individual Entitlement policies

Status: [Planned]

Planned location: WP Admin > Entitlements > [Entitlement Code] > Edit > Policies tab

Individual entitlement overrides are for one-off exceptions. This is the most specific level and should be used sparingly.

How it will work:

1. Navigate to WP Admin > Entitlements (or find the entitlement from the organization view).
2. Click the entitlement code (e.g., SVC-2026050012).
3. Open the Policies tab.
4. You will see all policy fields with their effective values and the level they are inherited from.
5. Override specific fields as needed.
6. Save.

Design goals for the admin screen:

• Clear indication of the source level for each effective value (global, class, org, product, or entitlement).
• Audit log entry for every override, including who made the change and when.
• Warning when overriding values that differ from the organization or product level, to prevent accidental conflicts.

What to configure here:

• Contractual exceptions negotiated for a specific deal
• Migration accommodations for entitlements imported from external systems
• One-time extensions or adjustments from customer escalations

---

Verifying effective policies

To check what policy values are in effect for a specific entitlement:

1. Navigate to the entitlement in WP Admin.
2. Open the Policies tab. (Planned)
3. Each field will show:
   • The effective value currently in use.
   • The source level (Global, Class, Organization, Product, or Entitlement).
   • Whether the value is inherited or overridden at this level.

This view makes it easy to diagnose why an entitlement is behaving a certain way and where the controlling policy is set.

---

Policy change auditing

All policy changes are recorded in the system audit log:

• Who made the change (WordPress user)
• When the change was made (timestamp)
• What changed (field name, old value, new value)
• At which level (global, class, organization, product, or entitlement)

This audit trail is essential for compliance and for debugging unexpected behavior.

Next steps

• Policy Recipes -- practical configuration walkthroughs
• Available Policies -- field reference for all 10 policies
• Policy Hierarchy -- understanding override resolution