Skip to content

9.3 Subscription Service - Application and Lifecycle Endpoints

Sprint: Sprint 09 - Subscription and Onboarding Saga
Feature ID: 9.3
Subtasks: 9.3.1, 9.3.2, 9.3.3, 9.3.4

Objective

Deliver "Subscription Service - Application and Lifecycle Endpoints" within Sprint 09 - Subscription and Onboarding Saga.

Dependencies

Aggregated from the subtasks below (prerequisite task IDs and enablers):

  • 9.2.2
  • 9.3.1
  • 9.2.1

Subtasks

9.3.1 Internal create/activate subscription

  • ID: 9.3.1
  • Title: Implement POST /api/v1/subscriptions (internal) and activation
  • Description: ActivateSubscriptionCommand (called by the saga) allocating an MSISDN, creating an ACTIVE subscription with the tariff snapshot, and publishing subscription.activated.v1. On allocation/creation failure, publish the cataloged subscription.activation-failed.v1 event for compensation. Note: the subscription.activation-failed.v1 .avsc schema is registered with this feature (the producing service owns its schema, ADR-019); CONSUMERS are wired in 9.4.3.
  • Business Purpose: Automatic activation when an order completes (FR-13, AC-01 step 5).
  • Inputs: FR-13, event-catalog subscription.activated.v1, subscription.activation-failed.v1, analysis Section 9.2.
  • Outputs: Activate command, endpoint, events.
  • Acceptance Criteria:
  • Activation allocates an MSISDN, sets status ACTIVE, emits subscription.activated.v1; on failure it emits subscription.activation-failed.v1 and allocates no number.
  • Dependencies: 9.2.2
  • Complexity: L

9.3.2 Suspend, reactivate, terminate endpoints

  • ID: 9.3.2
  • Title: Implement subscription lifecycle endpoints
  • Description: POST /{id}/suspend, /{id}/reactivate, /{id}/terminate commands emitting subscription.suspended.v1 / subscription.terminated.v1 (terminate also releases the MSISDN). Suspend is also triggered by payment failure after a grace period (consume payment.failed.v1).
  • Business Purpose: Manage the subscription lifecycle (FR-14).
  • Inputs: FR-14, event-catalog subscription events.
  • Outputs: Lifecycle commands + endpoints + events + payment-failed consumer.
  • Acceptance Criteria:
  • Suspend/reactivate/terminate transition correctly and emit their events; terminate releases the MSISDN; a post-grace payment.failed.v1 suspends the subscription idempotently.
  • Dependencies: 9.3.1
  • Complexity: M

9.3.3 Get subscription and customer subscriptions

  • ID: 9.3.3
  • Title: Implement subscription read endpoints
  • Description: GET /api/v1/subscriptions/{id} and GET /api/v1/subscriptions?customerId=... returning ApiResult with status, MSISDN, and tariff.
  • Business Purpose: Subscription visibility (FR-15).
  • Inputs: FR-15.
  • Outputs: Queries + endpoints.
  • Acceptance Criteria:
  • Reads return the subscription(s); a customer with multiple subscriptions returns all of them.
  • Dependencies: 9.3.1
  • Complexity: S

9.3.4 MNP state-machine scaffold (post-MVP)

  • ID: 9.3.4
  • Title: Scaffold MNP port number portability state machine (deferred)
  • Description: Define the MNP state-machine interface and states without full implementation, documenting it as post-MVP (FR-16). No active endpoint.
  • Business Purpose: Reserve a clean extension point for number portability (FR-16).
  • Inputs: FR-16 (post-MVP).
  • Outputs: MNP interface/state enum + docs.
  • Acceptance Criteria:
  • The MNP states/interface compile and are documented as deferred; no MVP flow depends on them.
  • Dependencies: 9.2.1
  • Complexity: S

Acceptance Criteria

Each subtask above carries its own objective, testable acceptance criteria. This feature is complete when every subtask's acceptance criteria are met.

Deliverables

  • Activate command, endpoint, events.
  • Lifecycle commands + endpoints + events + payment-failed consumer.
  • Queries + endpoints.
  • MNP interface/state enum + docs.

Definition of Done

  • All subtasks (9.3.1, 9.3.2, 9.3.3, 9.3.4) completed and their acceptance criteria verified.
  • All listed dependencies satisfied.
  • Build and tests green per the global conventions in ../README.md (Section 3).