---
id: STATE-PFM-INT-011
title: Subscription standing
object: DOM-PFM-INT-004
product_area: platform
module: integrations
revision: 1
status: draft
design_intent: proposed
implementation_evidence: observed
source_sha:
  services-platform: ad3f6a6582843008ed0f5a17b131878d15829af1
states:
  - name: absent
    meaning: 'The installation, optional account and event interest have no subscription.'
  - name: active
    meaning: Eligible changes can produce projected delivery records.
  - name: paused
    meaning: An administrator or acceptance withdrawal stopped new fan-out.
  - name: paused_by_failures
    meaning: Repeated dead deliveries stopped new fan-out automatically.
transitions:
  - from: absent
    to: active
    trigger: Create an event interest
    guard: 'Installation, declared and accepted event, filter and uniqueness checks pass'
    side_effects:
      - Commit both audit entries without filter contents.
    who: Integration administrator
    provenance: test
    source: >-
      services-platform:modules/integrations/tests/integration/services/subscriptions/subscriptions.integration.spec.js#refuses
      a subscription to a type the installation has not accepted, naming the type, and writes nothing
  - from: active
    to: paused
    trigger: Pause event fan-out
    guard: An authorized versioned edit pauses it or installation acceptance withdraws its event
    side_effects:
      - Commit pause history in both trails.
    who: Integration administrator or acceptance change
    provenance: test
    source: >-
      services-platform:modules/integrations/tests/integration/services/subscriptions/subscription-consent.integration.spec.js#pauses
      the active subscription of the type left out
  - from: paused
    to: active
    trigger: Resume event fan-out
    guard: The installation is enabled and still accepts this event type
    side_effects:
      - Audit resumed authority as widening.
    who: Integration administrator
    provenance: observed
    source: 'services-platform:modules/integrations/services/persistence/integration-subscriptions.ts'
  - from: active
    to: paused_by_failures
    trigger: Reach repeated-dead threshold
    guard: An active subscription reaches fifty consecutive dead deliveries
    side_effects:
      - Request its administrator notice once.
    who: Delivery worker
    provenance: test
    source: >-
      services-platform:modules/integrations/tests/integration/services/subscriptions/subscriptions.integration.spec.js#pauses
      a subscription after fifty dead deliveries in a row and tells its administrators once
  - from: paused_by_failures
    to: active
    trigger: Resume after dead deliveries
    guard: Ordinary resume validation succeeds
    side_effects:
      - Clear the consecutive dead count.
    who: Integration administrator
    provenance: test
    source: >-
      services-platform:modules/integrations/tests/integration/services/subscriptions/subscriptions.integration.spec.js#pauses
      a subscription after fifty dead deliveries in a row and tells its administrators once
  - from: active
    to: absent
    trigger: Remove the interest
    guard: An administrator removes it or its installation is uninstalled
    side_effects:
      - Delete the subscription while retaining delivery records.
    who: Integration administrator
    provenance: test
    source: >-
      services-platform:modules/integrations/tests/integration/services/connections/disconnect-discard-uninstall.integration.spec.js#removes
      every subscription of the installation with the uninstallation, and no other installation’s
  - from: paused
    to: absent
    trigger: Remove a paused interest
    guard: The same administrative or uninstallation removal applies
    side_effects:
      - Delete the subscription while retaining delivery records.
    who: Integration administrator
    provenance: observed
    source: >-
      services-platform:modules/integrations/services/persistence/integration-subscriptions.ts:removeSubscriptionsOfInstallation
  - from: paused_by_failures
    to: absent
    trigger: Remove a failure-paused interest
    guard: The same administrative or uninstallation removal applies
    side_effects:
      - Delete the subscription while retaining delivery records.
    who: Integration administrator
    provenance: observed
    source: >-
      services-platform:modules/integrations/services/persistence/integration-subscriptions.ts:removeSubscriptionsOfInstallation
invalid:
  - from: absent
    to: paused
    why: New subscriptions start active after their configuration validates.
  - from: paused
    to: paused_by_failures
    why: Automatic failure pausing is conditional on active subscription status.
concurrency: >-
  Versioned edits protect administrative subscription changes. Acceptance withdrawal pauses subscriptions
  inside installation edits. Installation suspension leaves subscription status unchanged while preventing new
  fan-out, and resumption does not backfill skipped changes.
invariants:
  - INV-DOM-PFM-INT-004-06
  - INV-DOM-PFM-INT-004-08
  - INV-DOM-PFM-INT-004-09
evidence:
  - >-
    services-platform at ad3f6a65: modules/integrations/db/integration-subscriptions.table.ts;
    services/events/event-operations.ts; services/subscriptions/delivery-worker.ts;
    services/installations/installation-lifecycle.ts;
    services-platform:docs/milestones/INTG-M3-webhooks-events-deliveries.md (status Proposed)
---

# Subscription standing

## The Lifecycle

```mermaid
stateDiagram-v2
  state "absent" as s0
  state "active" as s1
  state "paused" as s2
  state "paused_by_failures" as s3
  s0 --> s1: Create an event interest
  s1 --> s2: Pause event fan-out
  s2 --> s1: Resume event fan-out
  s1 --> s3: Reach repeated-dead threshold
  s3 --> s1: Resume after dead deliveries
  s1 --> s0: Remove the interest
  s2 --> s0: Remove a paused interest
  s3 --> s0: Remove a failure-paused interest
```

## Transitions Explained

A valid subscription begins taking eligible changes. Administrators, access withdrawal or repeated dead deliveries can pause new fan-out. Resume requires current eligibility and does not reconstruct skipped changes; removal deletes configuration while retaining delivery history.

## What Cannot Happen

New subscriptions start active after their configuration validates. Automatic failure pausing is conditional on active subscription status.

## Concurrency and Timing

Versioned edits protect administrative subscription changes. Acceptance withdrawal pauses subscriptions inside installation edits. Installation suspension leaves subscription status unchanged while preventing new fan-out, and resumption does not backfill skipped changes.