Recurring payments enforced at the blockchain consensus layer. No payment processor, no webhook infrastructure, no failed-charge handling.
Subscriptions in Shamwari are stored as first-class account entities in blockchain state which do not rely on smart contract state. The protocol manages subscription automatically at each configured block height via the AFTER_BLOCK_APPLY handler. Only user transaction triggers renewal.
Traditional subscription billing is a webhook problem. When the payment processor fires a webhook, the application must: authenticate the webhook, update its database, handle retries, manage idempotency, and reconcile failures. None of this exists in Shamwari.
Subscription billing is registered as an AFTER_BLOCK_APPLY listener which is one of Shamwari's six automatic post-block operations. The listener processes all subscriptions reaching their expirationHeight in that block as a batch, in a single database transaction.
Every active subscription is a typed entity in the blockchain state, with all authority needed for renewal processing held by the subscriber account.
| Field | Type | Description |
|---|---|---|
| subscriptionId | long | Unique subscription identifier. Derived from transaction hash. Immutable. |
| serviceId | long | References the SubscriptionServiceEntity. Links to service name, provider, and configuration. |
| subscriberAccountId | long | Account ID of the subscriber. Only this account can cancel the subscription. |
| providerAccountId | long | Account ID of the service provider. Credited on each renewal. |
| billingAmount | long | Payment amount per billing period in smallest digital unit (QNT). Immutable after creation. |
| billingPeriod | int | Billing period in blocks. The protocol adds this to expirationHeight after each successful renewal. |
| expirationHeight | int | Block height at which the next billing attempt occurs. Updated by AFTER_BLOCK_APPLY on renewal. |
| assetType | enum | COIN / CURRENCY / TOTEM determines which balance to debit on renewal. |
| assetId | long | Asset ID for CURRENCY and TOTEM types. 0 for COIN type. |
| status | enum | ACTIVE / LAPSED / CANCELLED. Transitions are protocol-enforced. |
| latestBlock | int | Block height of last renewal. Used for history queries and analytics. |
Like all Shamwari entities, SubscriptionEntity is stored in a versioned table keyed by (subscriptionId, height). Every state change from creation, renewal, lapse to cancellation is preserved at the block height it occurred.
The service configuration entity is created once by the provider and referenced by all subscriber entities. Changes to the service (price, period) require a new SERVICE_UPDATE transaction and only apply to new subscriptions and existing subscriptions honour the terms at creation.
Subscription billing frequency is expressed in blocks and not calendar time. This is deterministic, timezone-independent, and unambiguous. A billingPeriod of 7,200 blocks is always exactly 7,200 blocks. There is no concept of "end of month", "daylight saving adjustment", or "leap year edge case" in Shamwari billing.
Service providers can calculate expected revenue for any future block range from the live subscription state. The total expected revenue for blocks N through M = sum of billingAmount for all subscriptions with expirationHeight in [N, M] and status = ACTIVE.
If a service accepts multiple payment types (separate service registrations per asset type), revenue is denominated in the relevant asset. Cross-currency revenue aggregation is an off-chain analytics concern wher each asset's revenue is tracked independently on-chain.
Service providers configure subscription parameters once at service creation. The protocol enforces all restrictions at the gate with account type checks at consensus, asset validity at attachment validation, and balance checks at renewal.
Services can restrict subscriptions to specific AccountType values: BUSINESS, DEVELOPER, PERSONAL, SAVINGS, AUTONOMOUS, or any combination. The SUBSCRIBE transaction is rejected at gate 4 (Account Type Gate) for non-permitted account types before any payment is attempted and before the SubscriptionEntity is created.
Services can accept payment in chain coin (WEALTH/FXT), any ShamwariPay currency (ZWG, ZAR, CAPITAL), or any APPROVED Totem digital asset. The billingAmount is denominated in the smallest unit of the accepted asset. Mixed-asset services require separate service registrations.
If subscriber funds are unavailable at renewal, the subscription lapses immediately at that block. No retry logic, no dunning management, no grace period, no failed payment email. The service provider can query lapsed subscribers and offer reinstatement via a new SUBSCRIBE transaction.
Providers can submit SERVICE_UPDATE transactions to pause new subscriptions (isActive = false). Existing active subscriptions continue billing normally. This enables controlled rollout pauses, maintenance windows, and capacity management without disrupting existing subscribers.
If a subscriber's account receives BLOCKED_CHAIN_USER permission (sanctions or AML action), their subscription renewals are rejected at gate 3 (Permission Policy Check), before the balance debit. The subscription transitions to LAPSED at the next renewal attempt.
Providers can configure a trialPeriodBlocks field in the service entity. Trial subscribers get a subscription entity with expirationHeight = currentHeight + trialPeriodBlocks and billingAmount = 0 for the first period. First paid billing period triggers at trial expiry.
Every subscription use case below runs entirely on the protocol billing engine with no payment processor, no webhook infrastructure, no external dependency.
AccountType.AI accounts can subscribe to services within their AutonomousAccountControl rule set. Subscription payments count toward rolling spend window calculations — the protocol prevents AI agents from silently accumulating recurring obligations that exceed their governance-approved limits.
An enterprise deploys an AI treasury agent configured with the following AutonomousAccountControl rule set for subscriptions:
Sub-5-minute billing periods enable genuine usage-based metering for AI service consumption without off-chain metering infrastructure.
If the SUBSCRIPTION tax rate is configured on the chain (0–3500 basis points), tax is automatically withheld from every subscription renewal payment and credited to the Tax Collector account in the same atomic operation — with zero off-chain reporting.
A ZWG subscription service with billingAmount = 1,000 QNT (100 ZWG at 1 decimal) and SUBSCRIPTION tax rate = 500 bps (5%):
Value-Added Tax on digital services is a compliance challenge for traditional SaaS providers in emerging markets. Shamwari's protocol-native withholding eliminates the challenge entirely as the protocol calculates and withholds at the point of payment automatically.
The complete comparison between Shamwari's consensus-native billing and traditional SaaS subscription infrastructure.
Create subscription services that bill automatically for SaaS, data feeds, media, microinsurance premiums, or any recurring revenue model.