customer/account
product offering
product specification
contract/agreement
service instance
resource assignment
billing/charging state
entitlement decision
lifecycle history

Apakah customer punya hak memakai layanan ini sekarang?
Sejak kapan hak itu berlaku?
Apa product/offering/configuration yang aktif?
Apakah billing harus berjalan?
Apakah charging harus mengizinkan usage?
Apakah service teknis harus aktif, suspended, throttled, atau terminated?
Apakah subscription sedang pending activation, pending change, suspended, resumed, pending terminate, atau terminated?
Apakah perubahan berasal dari customer request, dunning, fraud, network issue, migration, atau admin correction?

customer masih bisa memakai service setelah disconnect
billing tetap berjalan ketika service suspended tanpa charge policy jelas
prepaid quota aktif padahal product terminated
customer care melihat active, network melihat inactive
resume gagal karena suspend reason hilang
upgrade plan membuat dua subscription active paralel tanpa policy
termination menghapus history
entitlement cache stale menyebabkan revenue leakage

Diberikan product order yang completed atau lifecycle event dari billing/charging/care,
Anda bisa mendesain Subscription Lifecycle Management yang benar secara domain, aman secara state,
auditable, idempotent, dan dapat menjadi basis entitlement, billing, charging, dan service control.

Apa perubahan yang diminta?

Apa product yang sekarang dimiliki customer dan apa state lifecycle-nya?

Apakah customer boleh menggunakan capability tertentu sekarang?

Subscription: Postpaid Gold Plan milik customer A.
Service: mobile voice/data service di core network.
Resource: MSISDN, IMSI, ICCID/SIM, APN profile, IP allocation.

Subscription: Fiber 300 Mbps product milik billing account B.
Service: internet access service, CFS/RFS.
Resource: ONT, router, OLT port, VLAN, IP block.

Product Inventory = repository semua product instance milik customer.
Subscription = product instance recurring yang memiliki entitlement/lifecycle berkelanjutan.

Setiap subscription adalah product instance.
Tidak semua product instance harus subscription.

one-time installation fee
one-time device purchase
SIM replacement fee
activation fee
one-time roaming pass jika tidak recurring

mobile postpaid plan
prepaid base plan
fiber broadband recurring plan
enterprise MPLS circuit
IoT connectivity plan
cloud voice seat
static IP add-on recurring

State subscription harus dapat menjelaskan entitlement, billing behavior, dan expected service behavior.

class Subscription {
    boolean active;
}

Pending activation dianggap inactive, tapi order masih berjalan.
Suspended dianggap inactive, tapi product belum terminated.
Pending terminate dianggap active atau inactive?
Expired dalam grace period berbeda dengan terminated.
Activation failed berbeda dengan cancelled.
Voluntary suspension berbeda dengan dunning suspension.

public enum SubscriptionState {
    PENDING_ACTIVATION,
    ACTIVE,
    PENDING_SUSPEND,
    SUSPENDED,
    PENDING_RESUME,
    PENDING_CHANGE,
    CHANGE_FAILED,
    PENDING_TERMINATION,
    EXPIRED,
    TERMINATED,
    CANCELLED,
    ACTIVATION_FAILED
}

public enum LifecycleReasonCode {
    CUSTOMER_REQUEST,
    ORDER_COMPLETED,
    NON_PAYMENT,
    FRAUD_SUSPECTED,
    CREDIT_RISK,
    CONTRACT_EXPIRED,
    ADMIN_CORRECTION,
    NETWORK_MIGRATION,
    PRODUCT_MIGRATION,
    TECHNICAL_FAILURE,
    REGULATORY_BLOCK,
    PARTNER_REQUEST
}

Subscription active hanya jika mandatory fulfillment milestone selesai atau policy eksplisit mengizinkan pre-activation.

Active -> PendingSuspend -> Suspended

commercial state sudah menerima suspend request
network/service belum tentu selesai suspend
billing policy mungkin belum berubah sampai suspend effective
customer notification perlu tracking
retry/compensation perlu state antara

public record SuspendSubscriptionCommand(
    SubscriptionId subscriptionId,
    SuspensionRequestId requestId,
    SuspensionType suspensionType,
    LifecycleReasonCode reasonCode,
    Instant requestedAt,
    Instant effectiveAt,
    Actor actor
) {}

Voluntary suspend mungkin future-dated.
Fraud/regulatory suspend biasanya immediate.
Dunning suspend mengikuti collection policy.
Technical suspend tidak selalu customer-visible.

suspend reason boleh dihapus atau sudah resolved
outstanding payment sudah clear jika dunning
fraud block sudah released jika fraud
network/service resume berhasil
charging entitlement restored
billing policy benar
customer notified

Suspended -> PendingResume -> Active

customer bayar tagihan
billing marks account paid
subscription active set true
network service tetap barred
customer masih tidak bisa memakai layanan

upgrade speed 100 -> 300 Mbps
add roaming add-on
remove static IP
change mobile plan
change contract term
change SIM/eSIM profile
change installation address / relocation

public record PendingLifecycleChange(
    LifecycleChangeId id,
    SubscriptionId subscriptionId,
    LifecycleChangeType type,
    ChangeState state,
    Instant requestedAt,
    Instant effectiveAt,
    Map<String, ChangeValue> proposedChanges,
    ProductOrderId sourceOrderId
) {}

REQUESTED
VALIDATED
IN_PROGRESS
APPLIED
FAILED
CANCELLED
ROLLED_BACK

current configuration = what is active now
pending configuration = what will be active after effective date/fulfillment
historical version = what was active before

contract start date
contract end date
minimum commitment period
auto-renewal flag
renewal offer
penalty/early termination fee
price lock period
promotion expiry
notification obligation

Active
InRenewalWindow
RenewalPending
Renewed
Expired
GracePeriod
Terminated

Subscription masih active setelah contract minimum term selesai.
Tapi discount/promotion mungkin expired.
Early termination fee mungkin tidak lagi berlaku.

Active/Suspended -> PendingTermination -> Terminated

future-dated termination
immediate termination
end-of-cycle termination
early termination fee
resource release
service disconnect
billing final charge
refund/adjustment
number quarantine/recycle policy
CPE return
historical record retention

public record TerminateSubscriptionCommand(
    SubscriptionId subscriptionId,
    TerminationRequestId requestId,
    TerminationMode mode,
    LifecycleReasonCode reasonCode,
    Instant requestedAt,
    Instant effectiveAt,
    ProductOrderId sourceOrderId,
    Actor actor
) {}

IMMEDIATE
END_OF_BILL_CYCLE
FUTURE_DATED
END_OF_CONTRACT
ADMIN_CORRECTION
MIGRATION_REPLACED

Terminated subscription tidak boleh kembali active.
Jika perlu reconnect, buat subscription/order baru atau explicit reinstatement policy dengan audit sangat kuat.

reminder
late fee
outgoing call barred
data throttling
partial suspension
full suspension
termination
write-off

subscription state
product offering/specification
customer/account status
balance/quota
payment/dunning state
fraud/regulatory blocks
service/resource state
time/effective date
location/roaming context
policy version

public record EntitlementDecision(
    SubscriptionId subscriptionId,
    String capability,
    boolean allowed,
    EntitlementDecisionReason reason,
    Instant decidedAt,
    String policyVersion,
    Duration ttl
) {}

DATA_ACCESS
VOICE_OUTGOING
VOICE_INCOMING
SMS_OUTGOING
ROAMING
STATIC_IP
FIBER_INTERNET
QOS_PREMIUM
API_SIM_SWAP_CHECK

ALLOWED_ACTIVE_SUBSCRIPTION
DENIED_SUSPENDED_NON_PAYMENT
DENIED_TERMINATED
DENIED_QUOTA_EXHAUSTED
DENIED_FRAUD_BLOCK
DENIED_NOT_YET_EFFECTIVE
DENIED_EXPIRED

SubscriptionActivated
SubscriptionSuspended
SubscriptionResumed
SubscriptionChanged
SubscriptionTerminated
SubscriptionRenewed
PromotionExpired
ContractTermEnded

if suspended then stop billing

public interface SubscriptionBillingPolicy {
    BillingEffect evaluate(Subscription subscription, LifecycleEvent event);
}

subscription active?
plan/quota policy?
balance bucket?
validity period?
roaming allowed?
throttle policy?
5G slice/QoS policy?

activation -> create balance/quota/charging profile
suspend -> bar/throttle/deny capabilities
resume -> restore profile
change plan -> migrate buckets/policy
terminate -> close profile and reject new sessions

Usage event datang setelah termination.

accept if usageTime before termination effectiveAt
reject if after termination effectiveAt
route to suspense if ambiguous

Subscription PendingSuspend, service still active until network command completed.
Subscription PendingResume, service still barred until resume completed.
Subscription PendingTermination, resources may still be assigned.

subscription active, service inactive
subscription suspended, network still allows data
subscription terminated, MSISDN still assigned
subscription active, billing not charging

public final class Subscription {
    private final SubscriptionId id;
    private final CustomerId customerId;
    private final BillingAccountId billingAccountId;
    private final ProductId productId;
    private final ProductOfferingId productOfferingId;
    private SubscriptionState state;
    private LifecycleReasonCode lifecycleReason;
    private Instant activationDate;
    private Instant suspensionDate;
    private Instant terminationDate;
    private final List<SubscriptionLifecycleTransition> transitions;
    private final List<PendingLifecycleChange> pendingChanges;
    private long version;

    public void activate(ActivateSubscriptionCommand command) {
        requireState(SubscriptionState.PENDING_ACTIVATION);
        this.activationDate = command.effectiveAt();
        transitionTo(
            SubscriptionState.ACTIVE,
            LifecycleReasonCode.ORDER_COMPLETED,
            command.actor(),
            command.occurredAt(),
            command.effectiveAt()
        );
    }

    public void requestSuspension(SuspendSubscriptionCommand command) {
        requireState(SubscriptionState.ACTIVE);
        this.lifecycleReason = command.reasonCode();
        transitionTo(
            SubscriptionState.PENDING_SUSPEND,
            command.reasonCode(),
            command.actor(),
            command.requestedAt(),
            command.effectiveAt()
        );
    }

    public void completeSuspension(CompleteSuspensionCommand command) {
        requireState(SubscriptionState.PENDING_SUSPEND);
        this.suspensionDate = command.effectiveAt();
        transitionTo(
            SubscriptionState.SUSPENDED,
            lifecycleReason,
            command.actor(),
            command.occurredAt(),
            command.effectiveAt()
        );
    }

    public void requestTermination(TerminateSubscriptionCommand command) {
        requireAnyState(SubscriptionState.ACTIVE, SubscriptionState.SUSPENDED);
        transitionTo(
            SubscriptionState.PENDING_TERMINATION,
            command.reasonCode(),
            command.actor(),
            command.requestedAt(),
            command.effectiveAt()
        );
    }

    public void completeTermination(CompleteTerminationCommand command) {
        requireState(SubscriptionState.PENDING_TERMINATION);
        this.terminationDate = command.effectiveAt();
        transitionTo(
            SubscriptionState.TERMINATED,
            lifecycleReason,
            command.actor(),
            command.occurredAt(),
            command.effectiveAt()
        );
    }

    private void transitionTo(
        SubscriptionState next,
        LifecycleReasonCode reason,
        Actor actor,
        Instant occurredAt,
        Instant effectiveAt
    ) {
        var previous = this.state;
        this.state = next;
        this.lifecycleReason = reason;
        this.transitions.add(
            SubscriptionLifecycleTransition.of(previous, next, reason, actor, occurredAt, effectiveAt)
        );
    }
}

public final class SuspendSubscriptionUseCase {
    private final SubscriptionRepository repository;
    private final SuspensionPolicy policy;
    private final FulfillmentGateway fulfillmentGateway;
    private final Outbox outbox;

    public SuspendSubscriptionResult suspend(SuspendSubscriptionCommand command) {
        var subscription = repository.findById(command.subscriptionId())
            .orElseThrow(() -> new NotFoundException("SUBSCRIPTION_NOT_FOUND"));

        var decision = policy.evaluate(subscription, command);
        if (!decision.allowed()) {
            return SuspendSubscriptionResult.rejected(decision.reason());
        }

        subscription.requestSuspension(command);
        repository.save(subscription, ExpectedVersion.current());

        outbox.append(new SubscriptionSuspensionRequestedEvent(
            subscription.id(),
            command.suspensionType(),
            command.reasonCode(),
            command.effectiveAt(),
            command.requestId()
        ));

        fulfillmentGateway.requestSuspend(subscription.id(), command.requestId());

        return SuspendSubscriptionResult.accepted(subscription.id());
    }
}

Dalam production, panggilan fulfillmentGateway sebaiknya melalui event/outbox/command queue,
bukan synchronous call yang membuat transaksi DB tergantung network downstream.

activationRequestId
suspensionRequestId
resumeRequestId
terminationRequestId
productOrderId + orderItemId + lifecycleAction
billingCollectionActionId
fraudCaseActionId

same request id + same command -> return same result
same request id + different payload -> reject conflict
completion callback duplicate -> no-op if already in target state with same evidence
late callback after compensation -> quarantine/manual review

public void completeSuspension(CompleteSuspensionCommand command) {
    if (state == SubscriptionState.SUSPENDED && transitions.containsEvidence(command.evidenceRef())) {
        return;
    }
    requireState(SubscriptionState.PENDING_SUSPEND);
    // apply transition
}

Customer request termination pada 2026-06-10.
Termination effective end-of-cycle pada 2026-06-30.
Network disconnect selesai 2026-07-01 01:00 karena maintenance window.
Billing final charge dihitung sampai 2026-06-30.

SubscriptionCreated
SubscriptionActivationRequested
SubscriptionActivated
SubscriptionActivationFailed
SubscriptionSuspensionRequested
SubscriptionSuspended
SubscriptionResumeRequested
SubscriptionResumed
SubscriptionChangeRequested
SubscriptionChanged
SubscriptionRenewed
SubscriptionTerminationRequested
SubscriptionTerminated
SubscriptionExpired
SubscriptionEntitlementChanged

eventId
eventType
eventVersion
subscriptionId
productId
customerId
billingAccountId
state before/after
reasonCode
effectiveAt
occurredAt
aggregateVersion
correlationId
causationId

Current status: Suspended
Reason: Non-payment
Requested by: Collection system
Requested at: 2026-06-15 10:00
Effective at: 2026-06-16 00:00
Resume condition: Payment settlement
Last network action: Barring completed
Billing behavior: Charges continue according to policy X
Customer visible message: Service suspended due to unpaid bill

CorrectActivationDate
CorrectLifecycleReason
ReconcileServiceState
ForceTerminateWithEvidence
RestoreEntitlementAfterIncident
MarkSuspensionCompletionFromEvidence

reason code
actor
approval jika high-risk
before/after snapshot
evidence reference
audit trail
customer impact flag
billing impact flag

active subscription without active service
active subscription without billing profile
terminated subscription with active network access
suspended subscription with charging still allowing usage
billing account closed but subscriptions active
service inventory active but product inventory missing
resource assigned to terminated subscription

AUTO_FIX_SAFE
MANUAL_REVIEW
BUSINESS_DECISION_REQUIRED
TECHNICAL_REPAIR_REQUIRED
IGNORE_WITH_REASON

public record ReconciliationFinding(
    String findingType,
    SubscriptionId subscriptionId,
    Severity severity,
    String expectedState,
    String actualState,
    RecommendedAction recommendedAction,
    Instant detectedAt
) {}

legacy prepaid to new charging platform
3G/4G plan to 5G plan
copper to fiber
old product catalog to new catalog
MVNO migration
billing platform migration

old subscription remains historical
new subscription/product version created or existing subscription versioned
entitlement continuity maintained
billing continuity checked
resource mapping verified
customer visible state stable
rollback/compensation plan exists

SubscriptionMigrationStarted
SubscriptionMigrationCompleted
SubscriptionMigrationFailed
SubscriptionReplaced

original activation date
contract term
promotion history
billing history
service/resource links
audit trail

parent subscription: Family Bundle
child subscriptions:
  main line
  secondary line 1
  secondary line 2
  shared data pool
  device installment

parent active does not always mean all children active
child suspended may or may not suspend parent
termination parent may terminate children
child transfer ownership may split bundle
shared quota requires group entitlement

CONTAINS
DEPENDS_ON
SHARES_BALANCE_WITH
BILLED_UNDER
REPLACES
ADDON_OF

customer self-care suspend voluntary
agent suspend for customer request
collection system suspend non-payment
fraud team block
regulatory officer block
admin correction
partner/MVNO command

Actor must be authorized for action + reasonCode + subscription scope.

reasonCode=REGULATORY_BLOCK

pending activation can become active
active can request suspension
suspended can request resume
terminated cannot resume
cancelled pending activation cannot activate
pending termination can become terminated
active can request change
change failed can rollback to active

non-payment suspension allowed only from active
fraud suspension can be immediate
voluntary suspension future-dated allowed if product policy supports it
termination end-of-cycle sets correct effective date
resume non-payment rejected if unpaid balance remains

SubscriptionSuspended event updates entitlement projection
SubscriptionActivated event starts billing policy
duplicate activation callback is idempotent
late usage after termination routed by usage time
service reconciliation detects active subscription inactive service

Scenario: Non-payment suspension and resume
  Given a subscription is active
  And the billing account is delinquent
  When collection requests suspension
  Then the subscription becomes pending suspend
  And a service suspension command is emitted
  When suspension completes
  Then the subscription becomes suspended
  And entitlement denies data access due to non-payment
  When payment is settled
  And resume completes
  Then the subscription becomes active
  And entitlement allows data access

service/network state drifts
entitlement has no lifecycle source
customer care cannot explain status

subscription/product inventory owns commercial lifecycle; billing consumes lifecycle events.

cannot distinguish pending/suspended/expired/terminated/cancelled/failed

explicit state machine + reason code + effective dates.

subscription says active, network says barred, care view inconsistent

billing/collection sends lifecycle command; subscription coordinates entitlement/service change.

lost audit, lost dispute evidence, lost billing history, lost resource trace

terminated is final lifecycle state; preserve history.

customer sees future plan as active before fulfillment
billing starts wrong plan
rollback impossible

current config + pending config + effective date + lifecycle change record.

activation
non-payment suspension
fraud block
resume after payment
plan upgrade
termination end-of-cycle

DATA_ACCESS
ROAMING
VOICE_OUTGOING

subscription state
quota balance
dunning status
fraud block
roaming policy

continue full billing
pause recurring charge
charge reduced pause fee

terminated subscription but network resource still active

void requestResume(ResumeSubscriptionCommand command)

hanya boleh dari SUSPENDED
non-payment resume perlu paymentCleared evidence
fraud resume perlu fraudRelease evidence
terminated tidak boleh resume

[ ] explicit lifecycle state machine exists
[ ] reason code mandatory for high-impact changes
[ ] lifecycle transitions audited
[ ] effective dating modeled
[ ] pending changes modeled
[ ] activation does not happen before required fulfillment milestone
[ ] suspension/resume are not simple active boolean update
[ ] dunning lifecycle uses subscription command, not direct network call only
[ ] entitlement decision derives from state/policy and has TTL
[ ] billing consumes lifecycle events idempotently
[ ] charging profile updates are idempotent
[ ] terminated subscriptions are retained historically
[ ] admin correction is command-based and audited
[ ] reconciliation detects drift with service/resource/billing/charging
[ ] authorization checks action + reason + actor scope
[ ] duplicate callbacks are safe
[ ] customer care projection is clear and non-technical

Product Order = requested change.
Subscription/Product Inventory = owned product and lifecycle state.
Entitlement = runtime decision whether capability is allowed.
Service Inventory = technical service instance.
Resource Inventory = assigned technical resource.
Billing/Charging = financial/usage interpretation of lifecycle.

state machine eksplisit
reason code
effective dates
pending changes
billing/charging alignment
entitlement decision layer
service/resource reconciliation
audit trail
idempotent command handling
customer-care projection

Suspend karena apa?
Effective kapan?
Billing tetap jalan atau berhenti?
Charging harus deny, throttle, atau allow partial?
Network command sudah selesai atau masih pending?
Customer boleh lihat reason ini atau tidak?
Resume condition-nya apa?
Bagaimana jika callback datang dua kali?
Bagaimana jika subscription sudah terminated?
Bagaimana audit membuktikan perubahan ini sah?