# Change, cancel, or resume subscription

**Flow key:** `subscription-change-cancel-resume`

## Outcome

An authorized customer changes the intended subscription with accurate timing, proration, entitlements, invoices, refunds, and reversibility.

## Actors

- Customer or billing admin
- Subscription/billing service
- Payment processor
- Entitlement service

## Preconditions and entry points

- An active synthetic subscription exists.
- Upgrade/downgrade, proration, cancellation, grace, and resume policies are known.

## Required test data

Use synthetic, isolated, resettable data. Never use real credentials, payment instruments, private customer records, or production notifications.

| Data | Canonical valid seed | Critical variations |
|---|---|---|
| Subscription | active `CARBON Pro Monthly` | trialing, past due, canceled-at-period-end, paused |
| Change | upgrade to annual or downgrade to Basic | seat/quantity change, add-on, same plan |
| Timing | immediate upgrade; period-end downgrade | backdated, renewal boundary, trial end |
| Payment | valid test method | decline, credit balance, refund due |
| Actor | billing admin | member, removed admin, support |

## Canonical steps

Treat this as the ordinary successful path inferred from common product behavior. Adapt it to observed labels, business rules, APIs, and implementation evidence; do not invent a requirement.

| Step | User or system action | Expected evidence |
|---:|---|---|
| 1 | Open subscription management. | Current plan, usage, renewal, payment, cancellation, and authority are accurate. |
| 2 | Choose upgrade, downgrade, cancel, pause, or resume. | Effective date, proration, credit/refund, feature loss, and data consequences are explicit. |
| 3 | Review and confirm once. | Server reauthorizes and records one versioned change. |
| 4 | Process any payment/refund. | Billing action uses the authoritative amount and stable idempotency. |
| 5 | Observe subscription and entitlements. | Immediate and scheduled states are distinct and coherent. |
| 6 | Advance through effective date or undo/resume window. | Plan, access, invoice, notification, and audit transition exactly once. |

## Alternate paths

- Immediate upgrade
- Period-end downgrade
- Cancel at period end
- Immediate cancel/refund
- Pause and resume
- Seat/add-on change

## Failure and recovery paths

- Payment fails during upgrade
- Concurrent admin changes
- Entitlement update partially fails
- Cancellation occurs during renewal
- Resume after plan retired

## Completion oracle

- The stated outcome is true in visible UI and authoritative persisted state.
- Exactly one intended business result and no unintended side effect occurred.
- Identity, tenant, authorization, money/data, lifecycle, notifications, integrations, analytics, and audit agree where applicable.
- Refresh, retry, back/forward, and a second authorized read do not reveal a contradictory result.
- Any partial, delayed, canceled, failed, or unknown outcome is labeled truthfully and has a safe recovery path.

## Evidence to capture

- Entry context, actor, tenant, role, feature flags, locale, time zone, and initial identifiers/state.
- Step-level screenshots or DOM state plus request/response, correlation, job, event, and stable business IDs where available.
- Before/after authoritative records, versions, totals, permissions, lifecycle states, and downstream side effects.
- Notifications, audit events, integration deliveries, retries, deduplication, latency, and recovery evidence.
- Untested branches, unsafe-to-run cases, product decisions, and evidence tier.

## Product decisions to resolve

- Exact eligibility, required data, authorization, and validation rules.
- Which steps are synchronous, asynchronous, optional, skippable, reversible, or irreversible.
- Idempotency, concurrency, timeout, retry, cancellation, and compensation semantics.
- Retention, privacy, notification, audit, performance, accessibility, and localization commitments.

## Related CARBON items

- [subscription](../../items/records/subscription.md)
- [currency price totals](../../items/data/currency-price-totals.md)
- [run start stop cancel](../../items/actions/run-start-stop-cancel.md)
- [concurrency and idempotency](../../items/quality/concurrency-and-idempotency.md)

[Back to Commerce and billing flows](index.md)
