# Start and renew subscription

**Flow key:** `subscription-start-and-renew`

## Outcome

A customer starts exactly one intended plan with truthful trial, billing, entitlement, renewal, invoice, and cancellation terms.

## Actors

- Customer
- Subscription/billing service
- Payment processor
- Entitlement service
- Notification provider

## Preconditions and entry points

- Test plans, prices, trial rules, payment methods, tax, and entitlement mappings exist.
- Time can be advanced in a test clock if possible.

## 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 |
|---|---|---|
| Plan | `CARBON Pro Monthly` | annual, free trial, free tier, metered, unavailable legacy plan |
| Customer | `carbon.sub+001@example.test` | new, existing, tax exempt, other currency/region |
| Payment | processor success token | decline, 3DS, expiring before renewal |
| Time | start now with known renewal date | trial end, DST/month-end/leap day, grace period |
| Entitlements | known Pro feature set | delayed provisioning, partial entitlement failure |

## 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 plan selection. | Price, interval, trial, limits, renewal, taxes, and cancellation terms are clear. |
| 2 | Choose plan and provide billing/payment data. | Final recurring and due-now amounts are explicit. |
| 3 | Confirm subscription once. | One subscription and billing intent are created idempotently. |
| 4 | Observe activation. | Entitlements, account plan, invoice/receipt, renewal date, and notification agree. |
| 5 | Advance to trial end or renewal. | Correct amount is attempted once under current tax/price/payment policy. |
| 6 | Inspect successful and failed renewal paths. | Entitlements, dunning, grace, invoice, and customer messaging match policy. |

## Alternate paths

- Immediate paid start
- Free trial
- Free plan conversion
- Metered subscription
- Annual or localized plan

## Failure and recovery paths

- Double submit creates duplicates
- Payment succeeds but entitlements fail
- Trial converts unexpectedly
- Renewal webhook repeats
- Price/tax changes before renewal

## 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)
- [payment](../../items/records/payment.md)
- [product service plan price](../../items/records/product-service-plan-price.md)
- [schedule](../../items/automation/schedule.md)

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