Subscription Refund Flow Design: Handling Refunds After Account Anomalies

1. Background: Paid Entitlements and Service Availability Must Stay Aligned

In a subscription model, users pay in advance for a billing cycle and receive access to a service for a defined period. The model assumes that as long as the billing cycle is active, the service should remain usable.

In real-world systems, however, account states can change because of risk-control reviews, suspicious login activity, compliance checks, system freezes, or other operational actions. As a result, an account that has already been paid for may lose access in the middle of the billing cycle.

This creates a common conflict: the user has paid for the billing cycle, but the service is no longer available. From the user’s perspective, they paid for access they cannot use and may deserve compensation. From the platform’s perspective, the suspension may be based on risk-control evidence, and refunds involve money, accounting, compliance, and payment-channel rules.

The goal of refund design is not simply to return money. It is to build an explainable and executable balance among user fairness, platform risk control, payment-channel limitations, and applicable laws or regulations.

Refund decisions should be based on the user agreement, platform rules, channel documentation, and applicable regulations. They should not be based only on a single incident or a single support agent’s judgment. For subscription businesses, these scenarios should be considered during the design of billing and refund systems, not handled reactively after complaints appear.

2. How to Determine Whether the Service Was Actually Unavailable

2.1 Decouple Account State, Billing State, and Refund State

Account state should not be judged only by whether the user has paid. Refund eligibility depends on whether the service was genuinely unavailable, how long it was unavailable, who was responsible, and whether access has since been restored.

It is recommended to model account state, subscription state, and refund state separately.

Common account states can be abstracted as follows:

• ACTIVE: normally available
• SUSPENDED: temporarily frozen, for example pending risk review
• REVIEWING: appeal or review in progress
• TERMINATED: permanently banned or terminated
• EXPIRED: subscription expired
• PAUSED: paused by the user or paused by the service
• REFUND_FAILED: refund channel failure that requires manual handling

Refund state can be modeled separately:

• PENDING: awaiting review
• APPROVED: review approved
• REJECTED: refund rejected
• COMPLETED: refund completed
• REFUND_FAILED: refund failed

A visibility mapping can be used between refund states and account or subscription states:

Refund State	Visible Account or Subscription State	Description
PENDING / APPROVED	REFUNDING	Refund is under review or being processed
COMPLETED	REFUNDED	Funds have been returned and entitlements are closed
REJECTED	Keep original state	Record the rejection reason and allow an appeal
REFUND_FAILED	REFUND_FAILED	Requires retry, manual intervention, or compensation

This separation prevents refund state from interfering with service-availability decisions and prevents the refund process from incorrectly changing the original account state.

2.2 Use Unavailable Interval Records Instead of a Point-in-Time Check

If the system only checks whether the service is available at the current moment, it may miss cases where the service was unavailable for a long period within the billing cycle but has since been restored.

For example, a user may experience a service outage on day 5 of the billing cycle, and access may be restored on day 10. The account is currently available again, but the service was unusable between day 5 and day 10. The system should not reject refund evaluation simply because the account has been restored.

A dedicated service-unavailable interval table can be introduced to record the start time, end time, reason, and billing cycle for each unavailable period:

CREATE TABLE service_unavailable_segment (
    segment_id BIGSERIAL PRIMARY KEY,
    user_id VARCHAR(64) NOT NULL,
    subscription_id VARCHAR(64) NOT NULL,
    billing_cycle VARCHAR(32) NOT NULL,
    cause VARCHAR(64) NOT NULL,
    start_at TIMESTAMPTZ NOT NULL,
    end_at TIMESTAMPTZ NOT NULL,
    UNIQUE(user_id, billing_cycle, cause, start_at)
);

Refund eligibility should be based on cumulative unavailable time within the target billing cycle, not only on the current instantaneous state. This allows the system to handle cases where the service has already been restored but compensation may still be appropriate, and it also supports attribution across billing cycles.

2.3 Example Eligibility Logic

from datetime import datetime, timezone
def now():
    return datetime.now(timezone.utc)
def is_service_available(user):
    # Service availability should not depend on refund state;
    # check account state and billing period only.
    return user.account_status in {"ACTIVE", "PAUSED"} and user.subscription_end > now()
def is_refund_eligible(user, unavailable_segments):
    # unavailable_segments are the intervals within the target billing cycle.
    cycle_seconds = user.billing_cycle_seconds
    unavailable_seconds = sum(
        max(0, (seg.end_at - seg.start_at).total_seconds())
        for seg in unavailable_segments
        if seg.billing_cycle == user.billing_cycle
    )
    unavailable_ratio = unavailable_seconds / cycle_seconds if cycle_seconds else 0
    # If the service is currently blocked, or the historical unavailable ratio
    # reaches the threshold, the case should enter refund evaluation.
    current_blocked = user.account_status in {"SUSPENDED", "REVIEWING", "TERMINATED"}
    return current_blocked or unavailable_ratio >= 0.3

Here, subscription_end is used to represent the end of the billing cycle, avoiding mixed use of fields such as subscription_active and subscription_end. Time fields should preferably be timezone-aware, for example by using TIMESTAMPTZ in the database.

3. How to Orchestrate the Refund Flow and Keep State Consistent

3.1 Standard Refund Workflow

A complete refund flow usually includes the following steps:

1. Trigger evaluation: The system detects service unavailability within a billing cycle, or the user proactively requests a refund.
2. Attribution classification: Distinguish between platform failure, risk review, user violation, duplicate charge, accidental purchase, and other causes.
3. Evidence collection: Record freeze time, appeal progress, unavailable intervals, channel order details, and related records.
4. Auto-renewal handling: Cancel or pause auto-renewal before starting the refund so that the user is not charged again.
5. Amount calculation: Calculate the refundable amount based on unavailable time, billing-cycle amount, and agreement rules.
6. Review and decision: Combine automated rules with manual review, and record approval or rejection reasons.
7. Fund return: Call the payment channel’s refund capability and record the channel transaction.
8. State closure: Update refund state, subscription entitlements, accounting records, and notify the user.
9. Reconciliation and audit: Check channel results and handle failures, timeouts, partial successes, and other exceptions.

3.2 Refund Preconditions, Amount Calculation, and Channel Limits

Before starting a refund, the following preconditions should be confirmed:

• Auto-renewal has been canceled or paused. Otherwise, the user may be charged again after the refund.
• The target billing cycle is clear, so that a failure from the previous billing cycle is not incorrectly counted in the current cycle.
• The user agreement, platform rules, and payment-channel limitations allow a refund.
• The refund amount, currency, order number, and channel transaction details are traceable.

Payment channels differ significantly:

• Apple / Google in-app subscription refunds: Refunds are usually handled by the channel, and developers generally cannot directly call a refund interface. Users need to apply through entries such as Apple’s reportaproblem.apple.com or Google Play. The final result is governed by the channel’s rules.
• Regional payment channels, such as WeChat Pay and Alipay where supported: Partial refunds may be subject to limits on the number of requests, time windows, amounts, or API behavior. The latest channel documentation should be followed.
• Other channels: During design, confirm whether the channel supports partial refunds, refunds to the original payment method, refund callbacks, and reconciliation files.

Partial refunds can be calculated based on the ratio of unavailable time within the billing cycle:

Refundable amount = Amount due for the current billing cycle × Unavailable time in the current billing cycle ÷ Total time in the current billing cycle

In practice, the system should also define rounding rules, minimum refund amount, who bears transaction fees, and how to merge multiple unavailable intervals. If the platform is at fault or the outage is severe, the agreement may allow a full refund, service-time extension, or compensating entitlements.

3.3 Idempotency, Unique Keys, and the Refund State Machine

Refunds are especially prone to duplicate processing caused by repeated submissions, network retries, or channel callbacks. Three layers of deduplication are recommended:

• Request key: Generate a unique request_id for each refund request.
• Business idempotency key: Create a unique index based on “user + subscription + billing cycle”.
• Channel transaction key: Record the refund_id returned by the payment channel and enforce a unique constraint.

Example table:

CREATE TABLE refund_request (
    request_id VARCHAR(64) PRIMARY KEY,
    user_id VARCHAR(64) NOT NULL,
    subscription_id VARCHAR(64) NOT NULL,
    billing_cycle VARCHAR(32) NOT NULL,
    idempotency_key VARCHAR(128) NOT NULL,
    amount DECIMAL(12,2) NOT NULL,
    currency CHAR(3) NOT NULL,
    refund_reason VARCHAR(255) NOT NULL,
    operator VARCHAR(64) NOT NULL,
    status VARCHAR(32) NOT NULL,
    channel_refund_id VARCHAR(128),
    created_at TIMESTAMPTZ NOT NULL,
    updated_at TIMESTAMPTZ NOT NULL,
    UNIQUE(idempotency_key),
    UNIQUE(channel_refund_id)
);

The refund state machine should allow only legal transitions. For example:

PENDING → APPROVED → COMPLETED
PENDING → REJECTED

A COMPLETED refund should not revert to PENDING.

A REFUND_FAILED state can enter a manual retry or compensation flow, but it should not skip review and complete the refund directly. The state machine should be enforced by code constraints or database constraints to prevent illegal transitions.

3.4 State Consistency, Reconciliation, and Exception Handling

Message queues usually provide at-least-once delivery. Therefore, consumers must deduplicate events by request_id or idempotency_key.

The refund ledger should be reconciled daily against channel statements. Key fields include state, amount, currency, time, and channel transaction identifiers.

Recommended exception paths include:

• Refund failure: Record the failure code and distinguish retryable from non-retryable failures.
• Partial success: Preserve the difference between the amount successfully refunded by the channel and the locally expected refund amount.
• Timeout with unknown status: Mark the request as processing or pending query, actively query the channel, and avoid writing “refunded” prematurely.
• Local status shows refunded, but the channel has not completed the transfer: Fix the inconsistency through reconciliation and query jobs, and use manual compensation if necessary.

This avoids inconsistencies such as “the local system shows refunded, but the channel has not actually completed the refund” or “the channel has refunded, but the local system still shows processing”.

4. How to Protect Entitlements During Freezes and Attribute Responsibility

4.1 Protecting Users During the Review Gap

After an account is frozen, the appeal and review process may take time. This review gap is where conflicts are most likely: the user’s paid billing cycle is still running, but the service is unavailable.

A reasonable system should provide compensation mechanisms:

• Service-time extension: Pause billing-cycle timing during the review freeze and automatically extend validity after the review ends.
• Early warning: When a subscription is nearing expiration and the account is frozen with an unresolved appeal, proactively notify the user that they can request a refund or extension.
• Clear time expectations: Show the estimated review completion time to the user, manage expectations, and reduce complaints caused by uncertainty.

These “no loss of entitlement” mechanisms can reduce refund disputes at the source. Many refund requests are not only about money; they come from the feeling that the user paid for a period during which the service was unusable.

4.2 Freeze Attribution, Anti-Abuse Controls, and Audit Trails

Different freeze reasons should lead to different refund strategies:

Freeze Reason	Responsible Party	Recommended Action
Platform failure or mistaken suspension	Platform responsibility	Restore service, extend time, refund proportionally or fully
Risk-control review pending	To be confirmed	Protect the review timeline, then handle after the outcome is clear
User violation	User responsibility	Usually reject the refund, explain the basis, and follow the agreement
No clear responsibility	No clear responsible party	Evaluate extension or partial refund based on the agreement or fairness principles

Automated refund evaluation is more suitable for cases involving platform failure, mistaken suspension, or cases with no clear responsible party. Risk-control reviews and user-violation cases usually require stronger manual review.

A risk-control freeze should not automatically be treated as a refund case. The system should first determine whether there is platform responsibility, user responsibility, or no clearly attributable responsibility.

Anti-abuse rules may include:

• Refund rate limits, such as limiting the number of refunds for the same user within the same billing cycle.
• Maximum refund amount per user.
• Linked-account detection to prevent batch or abnormal requests.
• Chargeback records linked with refund records.
• Manual review for high-risk orders.

All state changes should be written to an append-only audit log, recording the operator, time, state before and after the change, and the basis for the decision, so that the process remains traceable.

5. Refund Decision Matrix: Refund, Extend, or Reject?

To provide engineering and support teams with a consistent basis for judgment, a refund decision matrix can be used:

Scenario	Unavailable-Time Ratio	Recommended Action	Required Evidence
Platform failure or mistaken suspension	Low	Service-time extension or small compensation	Incident record, service logs
Platform failure or mistaken suspension	High	Proportional refund or extension	Unavailable intervals, billing statement
Risk-control review pending with no result	Review exceeds expected time	Pause billing, extend, or evaluate refund	Review record, freeze time
User violation	Depends on the agreement	Usually reject, explain the basis	Violation evidence, agreement terms
Duplicate charge	Based on accounting records	Refund the duplicate amount	Payment transaction record, billing statement

The decision matrix should be used as internal guidance, not as a fixed promise to users. The final refund decision is still subject to the user agreement, channel rules, and applicable regulations.

6. How to Submit Evidence Clearly and Safely

When a refund requires manual intervention, a clear evidence description can significantly improve processing efficiency. When users submit an appeal or support creates a ticket, the description should include three elements: what happened, when it happened, and what impact it caused.

A template can be used:

Issue: My account was suspended during an active paid subscription,
so I cannot access the service I already paid for.
Timeline: Suspension started on [date]; I submitted a review request,
which is still pending with an estimated resolution after my current
billing period ends.
Impact: The paid service was unavailable for the entire active period.
Request: A refund for the unusable billing cycle, or an extension of
equivalent service duration.

Before submission, users should be reminded to provide only the necessary information. Sensitive information such as phone numbers, identification numbers, and order numbers should be masked. For example, an order number can use partial masking:

ORD-2025****1234

Review records should have defined retention periods and access permissions to avoid excessive collection of sensitive data.

7. Building the Refund System with General Platform Capabilities

• Idempotent messaging: Events such as refund review, channel callbacks, and reconciliation compensation can be processed asynchronously through a message queue. Consumers must deduplicate by request_id or idempotency_key to avoid duplicate refunds.
• Evidence archiving: Freeze evidence, review records, and channel refund receipts can be stored in object storage with access permissions, retention periods, and audit policies to avoid long-term exposure of sensitive information.
• Refund metrics monitoring: Set alerts for metrics such as “unavailable time within a billing cycle”, “refund request volume”, “approval rate”, “refund failure rate”, and “reconciliation discrepancy” so that abnormal changes can be detected promptly.

8. Pre-Launch Self-Check

• Does the system distinguish account state, subscription state, and refund state?
• Does it record unavailable intervals and support cumulative evaluation by billing cycle?
• Does it cancel or pause auto-renewal before issuing a refund?
• Does it implement request keys, business idempotency keys, and channel transaction keys for three-layer deduplication?
• Does it cover channels such as Apple or Google where refunds cannot be issued directly by the developer?
• Does it include a state machine, reconciliation, failure retry, and audit logging?
• Does it minimize evidence collection and mask sensitive information?
• Does it show users the expected review time, refund calculation method, and expected arrival time?

9. FAQ

1. Can a user get a refund if the account is frozen after payment?

Not necessarily. The decision depends on the freeze reason, responsibility attribution, unavailable duration, and agreement rules. Platform failure or mistaken suspension is more likely to qualify for a refund or extension. User violations are usually handled according to the agreement.

2. Is the refund calculated as a full amount or a proportional amount?

In general, it can be calculated based on the proportion of unavailable time within the billing cycle. If the platform is seriously at fault, the service is unavailable for a long period, or the agreement specifies otherwise, a full refund, service-time extension, or compensation may be appropriate.

3. How long does a refund take, and what happens if it fails?

The arrival time depends on review speed and the payment channel. The system should show the estimated time window. If the refund fails, the system should record the channel response and support retry, manual handling, or conversion to an extension or compensation.

4. What cases are likely to be rejected?

Common cases include requests beyond the channel refund window, duplicate refunds, user violations without platform responsibility, insufficient evidence, or inconsistent request information. When rejecting a request, provide an explainable reason and a clear path for appeal.

10. Conclusion

Refunding an abnormal subscription account is not a one-time fund operation. It is a system-level problem involving account state, billing cycle, service availability, responsibility attribution, payment channels, accounting, and user expectations.

By making state models clear, recording unavailable intervals, enforcing idempotency, attributing responsibility properly, performing reconciliation and auditing, and managing user expectations, a refund flow can evolve from reactive incident handling into a predictable, trustworthy, and sustainable service capability.