# `subscription_management`

## Use when / do not use when

Use to inspect or manage an existing subscription. Do not use for an acquisition paywall, cancellation save offer, or app handoff.

## Exact metadata contract

<!-- funnelsgrove:generated:start contract-v3/step/subscription_management -->
### Generated contract facts — do not edit

- Step contract version: `3`
- Contract hash: `d761e91d5ac6ff9e72c6d49c5bcd014270912473a66f99c49d726c65998085cf`
- Type: `subscription_management`
- Family: `commerce`
- Description: A screen for managing or inspecting an existing subscription.
- Action owner: `step`
- Analytics role: _none_
- Terminal: `false`
- Required kind: `manage-subscription`
- Allowed kinds: `manage-subscription`
- Allowed semantic events: _None_
- Forbidden capabilities: `choice-write`, `email-capture`, `checkout`, `subscription-handoff`, `hardcoded-navigation`, `provider-direct-analytics`, `browser-registration-completed`

#### Choice contract

_Not a choice type._

#### Automatic lifecycle events

`first_step_clicked`, `first_step_viewed`, `funnel_started`, `step_completed`, `step_exited`, `step_started`

#### Approved capability owners

- `subscription-management` must be owned by `runtime-subscription-helpers`.

#### Reserved identities

- `manage-subscription`: id=`manage-subscription`, name=`manage-subscription`; type=`subscription_management`; kind=`manage-subscription`; unique=`true`

#### Golden fixture source

```ts
import type { FunnelManifestStep, FunnelStepMeta } from '@funnelsgrove/runtime';

const manifestStep = {
  id: 'manage-subscription',
  name: 'manage-subscription',
  path: '/manage-subscription',
  filePath: 'src/steps/step-manage-subscription.tsx',
  componentKey: 'stepManageSubscription',
  type: 'subscription_management',
  kind: 'manage-subscription',
  title: 'Manage subscription',
} as const satisfies FunnelManifestStep;

const componentMeta = {
  id: 'manage-subscription',
  name: 'manage-subscription',
  type: 'subscription_management',
  kind: 'manage-subscription',
  figmaNodeId: 'golden:subscription-management',
  title: 'Manage subscription',
  description: 'Inspect and manage an existing subscription.',
} as const satisfies FunnelStepMeta;

export const goldenFixture = {
  stepType: 'subscription_management',
  manifestStep,
  componentMeta,
  helper: 'runtime subscription helpers',
} as const;
```
<!-- funnelsgrove:generated:end contract-v3/step/subscription_management -->

## Interaction and persisted answer shape

Load and mutate subscription state through runtime subscription helpers. This screen does not persist funnel choice answers.

## Automatic lifecycle events

The controller owns step lifecycle; subscription APIs own account-state changes.

## Required semantic conversions

None unless a separately defined server-owned subscription event exists.

## Approved shared helpers

Use runtime subscription-management helpers and manifest routing.

## MUST rules

- Preserve the reserved management identity.
- Refresh visible state after a successful management action.

## NEVER rules

- Never expose secrets or call a provider with browser credentials.
- Never relabel this screen as a paywall.

## Golden template or fixture

See the [embedded canonical fixture](#golden-fixture-source) generated from `subscription_management.fixture.ts`.

## Validation command

Run `fgrove validate`.

## Manual QA and completion criteria

Test loading, empty state, action success/failure, refresh, back/exit, and exact reserved metadata.