Freemium vs Paid Tier Routing Prompt

This prompt is for platform engineers building routing middleware that must classify an account into a freemium or paid tier before making a downstream decision. Use it when a request hits your system and you need a deterministic, auditable tier assignment that respects upgrade/downgrade timing, trial status, and edge-case account states. The output drives feature gates, support queue selection, rate limit application, and model routing. The ideal user is an AI infrastructure or backend engineer integrating this classification step into a request-handling pipeline where tier information is not already available as a single, trusted source-of-truth field.

Do not use this prompt when tier information is already available as a structured field in your account database. In that case, read the field directly and skip the model call entirely. This prompt is specifically for scenarios where tier must be inferred from messy or compound signals: account metadata, recent billing events, contract snippets, or user-provided context. Using an LLM for a lookup that a database can perform in single-digit milliseconds introduces unnecessary latency, cost, and a potential point of failure. Reserve this prompt for the inference path, not the retrieval path.

Before wiring this prompt into production, define the exact downstream consequences of a misclassification. A false 'paid' classification for a freemium user might expose a gated feature incorrectly, while a false 'freemium' classification for a paying customer can degrade their experience and trigger a support escalation. Implement a validation layer that cross-references the model's output against any available deterministic signals, such as a plan_type field or a recent invoice timestamp. Log every classification decision with the input signals, model output, and final routed action so that audit trails exist for billing disputes or customer-impact investigations. If the confidence score falls below a defined threshold, route the request to a human review queue rather than making an automated gating decision.

This prompt template is designed to be placed in your system instructions or classification node. It accepts account metadata, request context, and tier definitions, then returns a structured routing decision. The prompt handles standard tier classification, but its real value is in managing edge cases: recently upgraded accounts that haven't propagated through billing systems, downgrade grace periods, trial-to-paid transitions, and accounts with conflicting entitlement signals. Before copying, review the square-bracket placeholders and replace them with your application's actual tier definitions, feature gates, and routing rules.

codeCopy
SYSTEM INSTRUCTION:
You are a tier classification and routing engine for a SaaS platform. Your job is to determine whether an account is on a freemium or paid tier and enforce the correct routing rules for feature access, support channels, and rate limits.

INPUT:
- Account metadata: [ACCOUNT_METADATA_JSON]
- Request context: [REQUEST_CONTEXT]
- Current timestamp: [TIMESTAMP]

TIER DEFINITIONS:
[Tier definitions with explicit criteria for each tier, including feature flags, support entitlements, and rate limits]

EDGE CASE RULES:
- Recently upgraded accounts (upgrade within [UPGRADE_PROPAGATION_WINDOW_HOURS] hours): Treat as paid tier even if billing system shows freemium.
- Downgrade grace period (within [GRACE_PERIOD_DAYS] days of downgrade): Continue routing as paid tier until grace period expires.
- Trial accounts with payment method on file: Route as [TRIAL_WITH_PAYMENT_ROUTING_RULE].
- Conflicting signals: When account metadata and request context disagree on tier, prioritize [CONFLICT_RESOLUTION_PRIORITY] and flag for review.
- Missing account data: If account metadata is empty or malformed, return [MISSING_ACCOUNT_FALLBACK_TIER] with confidence "low" and flag for manual review.

OUTPUT SCHEMA:
{
  "account_id": "string",
  "effective_tier": "freemium | paid | [ADDITIONAL_TIERS]",
  "confidence": "high | medium | low",
  "routing_decision": {
    "feature_access": ["[FEATURE_1]", "[FEATURE_2]"],
    "support_channel": "[SUPPORT_CHANNEL]",
    "rate_limit": [RATE_LIMIT_VALUE],
    "queue_priority": "[QUEUE_PRIORITY]"
  },
  "edge_case_flags": ["recent_upgrade | grace_period | trial | conflicting_signals | missing_data | null"],
  "requires_review": true | false,
  "review_reason": "string or null",
  "evidence": ["List of specific fields and values used to determine tier"]
}

CONSTRAINTS:
- Never grant paid-tier access to accounts that are unambiguously freemium.
- When confidence is "low," always set requires_review to true.
- Do not invent account data. If a field is missing, acknowledge it in evidence.
- For conflicting signals, explain the conflict in review_reason.

After pasting this template, replace each square-bracket placeholder with your application's concrete values. The tier definitions block should be exhaustive: list every feature flag, support channel, and rate limit per tier. The edge case rules are critical for production—most tier misclassifications happen during transitions, not steady state. Test this prompt against a golden dataset that includes recently upgraded accounts, accounts mid-downgrade, trial accounts with and without payment methods, and accounts with missing or malformed metadata. If your application serves enterprise customers with custom contracts, pair this prompt with the Contract Entitlement Gap Detection Prompt to catch requests that fall outside standard tier definitions.

This prompt is designed to sit inside a routing middleware layer—typically an API gateway, support ticketing system, or feature-flag service—that must make a deterministic tier classification before dispatching a request. The harness should call the prompt with a structured account object containing fields like account_id, plan_type, subscription_status, contract_start_date, contract_end_date, recent_upgrade_date, recent_downgrade_date, and any custom entitlement overrides. The output is a JSON object with tier (one of freemium, paid, grace_period, or unknown), confidence (0.0–1.0), routing_decision (the target queue or feature gate), and evidence (the specific fields that drove the classification). Do not pass raw, unparsed account blobs; the prompt works best when the application layer has already normalized the account state into a clean input schema.

Validation must happen in two layers. First, validate the model's output against a strict JSON schema before the routing decision takes effect. If tier is not one of the enumerated values, or if confidence is below a configurable threshold (start at 0.85), reject the classification and fall back to a safe default—typically routing to the freemium queue with a logged low_confidence_override flag. Second, validate against business rules in the application layer: if the model returns paid but the account's plan_type is free and there is no recent_upgrade_date, flag a contradiction and escalate for human review. These post-model business-rule checks catch hallucinations that schema validation alone would miss. Log every classification decision with the full input, output, validation result, and final routing action to an append-only audit table. This trace is essential for debugging misroutes and for demonstrating compliance with commercial agreements during contract disputes.

For retries, implement a single retry with exponential backoff (1s delay) if the model returns malformed JSON or a tier value outside the enum. Do not retry on low confidence or business-rule contradictions—those should escalate immediately. If the model fails twice, route to a human review queue with the full account context and a classification_failed reason code. Model choice matters: use a fast, cost-effective model like GPT-4o-mini or Claude Haiku for the primary classification path, and reserve a more capable model like GPT-4o or Claude Sonnet for the human-review fallback when contradictions are detected. Avoid using the same model for both primary classification and contradiction review, as it may reproduce the same error. Wire the prompt into your application with a timeout of 5 seconds and a circuit breaker that opens after 10 consecutive failures, preventing cascading latency in your routing middleware.

Edge cases around recently upgraded or downgraded accounts are the most common failure mode. The prompt includes instructions for detecting grace periods, but the harness should reinforce this with application-level date arithmetic: if recent_upgrade_date or recent_downgrade_date is within a configurable window (default 7 days), force the grace_period tier regardless of the model's output. This hard rule prevents the model from misinterpreting transitional account states. Similarly, if subscription_status is cancelled or suspended, override the tier to freemium with a status_override reason. These application-level overrides should be logged distinctly from model classifications so you can measure how often the model gets transitional states wrong and improve the prompt or fine-tune accordingly. Before deploying, run a regression suite of at least 50 account scenarios covering standard paid, standard freemium, grace-period upgrades, grace-period downgrades, cancelled accounts, custom entitlements, and missing fields. Measure precision and recall per tier, and set a release gate at >98% accuracy on the golden set before routing real traffic.