Tier Downgrade Grace Period Routing Prompt

This prompt is for billing and entitlement engineers building AI-powered routing middleware that must respect downgrade grace periods. When a customer downgrades their subscription, most SaaS platforms provide a grace window during which the customer retains their previous tier's entitlements. Routing requests based on the new, lower tier during this window causes premature feature revocation, broken support experiences, and compliance violations. This prompt classifies an incoming request against the customer's effective tier, which accounts for active grace periods, and returns a deterministic routing decision with an audit trail.

Use this prompt inside a classification step before dispatching to feature gates, support queues, or resource allocators. It expects upstream context that includes the customer's current tier, downgrade event timestamp, grace period duration, and the request's required entitlement level. The prompt does not perform initial tier detection or contract extraction—pair it with the Account Tier Detection Prompt or Contract SLA Mapping Prompt to supply the necessary inputs. The output is a structured routing decision with an effective tier, a boolean indicating whether the request should be honored under grace period rules, and a timestamp for when the grace window expires.

Do not use this prompt for initial tier detection, contract extraction, or for customers who are upgrading rather than downgrading. It is not designed to handle multi-product bundles where different features have independent grace periods—that scenario requires a more granular entitlement matrix. Avoid using this prompt as the sole authorization mechanism for regulated or financially material entitlements; always pair it with a deterministic business rules engine that can be independently audited. Before deploying, test against edge cases including zero-duration grace periods, overlapping downgrade events, and customers who downgrade multiple tiers in a single event.

This prompt template is designed to be integrated into a billing or entitlement middleware service. Its core job is to evaluate a customer support or feature access request against the customer's current account state, specifically checking for an active downgrade grace period. The model must decide whether to honor the previous (higher) tier's entitlements or enforce the new (lower) tier's limits. Copy the template below and replace each [PLACEHOLDER] with data from your account, billing, and contract systems before sending it to the model.

textCopy
You are an automated entitlement routing engine for a SaaS platform. Your task is to classify a customer's request based on their account tier, with special handling for accounts currently in a downgrade grace period.

## Input Data
- Current Request: [USER_REQUEST]
- Account ID: [ACCOUNT_ID]
- Previous Tier: [PREVIOUS_TIER]
- New Tier: [NEW_TIER]
- Downgrade Effective Date: [DOWNGRADE_DATE]
- Grace Period End Date: [GRACE_PERIOD_END_DATE]
- Current Date: [CURRENT_DATE]
- Previous Tier Entitlements: [PREVIOUS_TIER_FEATURES]
- New Tier Entitlements: [NEW_TIER_FEATURES]

## Classification Rules
1.  **Grace Period Active:** If `[CURRENT_DATE]` is on or before `[GRACE_PERIOD_END_DATE]`, the account is in a grace period.
2.  **Routing Logic:**
    *   If the `[USER_REQUEST]` maps to an entitlement in `[PREVIOUS_TIER_FEATURES]` AND the account is in a grace period, route to the `PREVIOUS_TIER_QUEUE`.
    *   If the `[USER_REQUEST]` maps to an entitlement in `[PREVIOUS_TIER_FEATURES]` AND the account is NOT in a grace period, route to the `NEW_TIER_QUEUE` and flag as a potential upsell.
    *   If the `[USER_REQUEST]` maps to an entitlement in `[NEW_TIER_FEATURES]`, always route to the `NEW_TIER_QUEUE`.
    *   If the `[USER_REQUEST]` does not map to any known entitlement, route to the `GENERAL_SUPPORT_QUEUE`.

## Output Schema
Return a single, valid JSON object without markdown fences. Do not include any explanatory text.
{
  "account_id": "[ACCOUNT_ID]",
  "is_grace_period_active": boolean,
  "routing_target": "PREVIOUS_TIER_QUEUE" | "NEW_TIER_QUEUE" | "GENERAL_SUPPORT_QUEUE",
  "classification_reason": "string"
}

To adapt this template, ensure the [PREVIOUS_TIER_FEATURES] and [NEW_TIER_FEATURES] placeholders are populated with structured lists of feature flags or support categories, not just tier names. The model needs to perform a semantic match between the user's natural language request and these feature lists. For high-stakes environments, the classification_reason string is critical for auditability; it should concisely state which rule was matched. Before deploying, run this prompt through a test suite that simulates requests on the exact boundary of the [GRACE_PERIOD_END_DATE] to catch off-by-one errors in date logic.

A common failure mode is the model misinterpreting the [CURRENT_DATE] format or performing the date comparison incorrectly. To mitigate this, always inject dates in an unambiguous ISO 8601 format (YYYY-MM-DD) and explicitly instruct the model to perform a chronological comparison. Another risk is the model hallucinating a feature match. You can reduce this by adding a [CONSTRAINTS] placeholder: "If the user's request does not clearly match a specific feature in either entitlement list, set the routing target to GENERAL_SUPPORT_QUEUE." After generating the output, validate the JSON schema and verify the routing_target against a hardcoded business rules engine as a secondary check before the routing decision takes effect.

The Tier Downgrade Grace Period Routing Prompt is not a standalone decision engine—it is a classification step inside a larger routing middleware that must enforce commercial rules deterministically. The prompt's job is to consume account metadata, downgrade timestamps, grace-period policy definitions, and the incoming request context, then return a structured routing decision that downstream systems can act on without ambiguity. The application layer owns the final enforcement: if the prompt returns route_as_tier: "premium" with grace_period_active: true, the middleware must honor that decision and not prematurely revoke access. The prompt should never be the sole source of truth for account state—always cross-reference the output against a source-of-truth billing or entitlement service before executing feature gates or queue assignments.

Wire the prompt into a pre-routing classification step that fires after account resolution but before queue dispatch. The harness should: (1) fetch the account's current tier, downgrade effective date, and grace-period policy from your billing or CRM API; (2) assemble the prompt with [ACCOUNT_CONTEXT] containing tier, downgrade timestamp, grace-period duration, and any custom contract overrides; (3) include [REQUEST_CONTEXT] with the incoming request type, channel, and requested feature or support level; (4) call the model with temperature=0 and a strict JSON output schema to prevent creative tier assignments; (5) validate the response against a schema that requires effective_tier, grace_period_active, grace_period_remaining_days, route_as_tier, and rationale fields; (6) if validation fails, retry once with the validation error injected into [PREVIOUS_ERROR] before escalating to a human reviewer or falling back to a conservative default (treat as downgraded tier to avoid over-entitlement). Log every decision with the full prompt, response, validation result, and final routing action for auditability.

Model choice matters here. Use a model with strong instruction-following and low hallucination rates on structured extraction tasks—GPT-4o, Claude 3.5 Sonnet, or equivalent. Avoid smaller models that may confuse grace-period logic or hallucinate tier assignments. Set response_format to JSON mode if available, and include a [OUTPUT_SCHEMA] placeholder in the prompt that mirrors your application's expected schema exactly. Retry logic should be bounded: one retry on schema validation failure, then escalate. Do not loop more than twice—grace-period decisions are time-sensitive, and a stuck retry loop during a customer interaction is worse than a conservative fallback. Human review triggers should fire when: the account has a custom contract that conflicts with standard grace-period policy, the downgrade timestamp is missing or ambiguous, or the model's confidence signal (if you request one) falls below a threshold. In high-stakes environments where premature feature revocation could cause revenue loss or contractual breach, route all grace-period-active decisions to a review queue for spot-checking during the first week of deployment.

Testing before production requires a golden dataset of account states: active grace period (within window), expired grace period (past window), no downgrade in progress, missing downgrade timestamp, custom contract with extended grace period, and edge cases like same-day downgrade-and-request. For each case, assert the expected route_as_tier and grace_period_active values. Add regression tests that catch false-positive grace-period extensions and false-negative premature downgrades. Observability should capture: prompt version, model version, account ID, downgrade timestamp, grace-period policy duration, model output, validation result, retry count, final routing decision, and latency. This trace data is essential for debugging misroutes and demonstrating compliance with contractual obligations during customer disputes. Do not deploy this prompt without first running it against your eval dataset and confirming that no test case produces a silent misclassification.