Skip to main content
This page walks through the complete lifecycle of a Vowena subscription. By the end, you’ll understand exactly how trustless recurring payments work on Stellar.
This is the “aha moment” page. If you read one page in the docs, make it this one.

​
The Full Flow

1

Merchant Creates a Plan

The merchant calls create_plan() on the Vowena contract, defining the subscription terms.
// On-chain transaction
create_plan({
  merchant: "GMERCHANT...ADDR",
  token: "USDC_CONTRACT_ADDR",
  amount: 99900000n,          // 9.99 USDC
  period: 2_592_000,          // 30 days
  price_ceiling: 149900000n,  // 14.99 USDC max
  trial_periods: 1,           // 1 free month
  max_periods: 0,             // No limit
  grace_period: 259_200,      // 3-day grace
})
The contract stores this plan on-chain and returns a plan_id. This plan is now discoverable by anyone - it’s a public, immutable billing template.
Plans are like product listings on the blockchain. A merchant might create multiple plans for different tiers: Basic, Pro, Enterprise - each with different amounts and periods.
2

Subscriber Discovers the Plan

The subscriber finds the plan through:

Merchant's App

The merchant’s website or dApp displays available plans and provides a “Subscribe” button.

Vowena Dashboard

The Vowena Dashboard lets anyone browse plans, view terms, and subscribe directly.

On-chain Discovery

Plans are stored on-chain. Anyone can query get_plan(plan_id) or get_merchant_plans(merchant) to discover available plans.

Direct Link

Merchants can share a direct subscription link that pre-fills the plan ID.
The subscriber can inspect all plan parameters before subscribing - amount, period, ceiling, trial, max periods, and grace period are all transparent.
3

Subscriber Calls subscribe()

The subscriber initiates the subscription. Their wallet displays the full authorization request:

Contract Authorization

Action: Call subscribe() on Vowena contractParameters:
  • Subscriber address
  • Plan ID
Effect: Creates an on-chain subscription record

Token Approval

Action: Call approve() on USDC contractParameters:
  • Spender: Vowena contract
  • Amount: price_ceiling (per period budget)
  • Expiry: Ledger-based expiration
Effect: Grants Vowena permission to pull USDC
The subscriber should always verify the wallet prompt carefully. The token address, spending amount, and contract address should all match expectations. Legitimate Vowena subscriptions will always show the official Vowena contract as the spender.
4

One Signature Covers Everything

Here’s where Soroban’s authorization framework shines. The subscriber signs once, and that single signature covers both:
  1. The subscribe() contract invocation
  2. The token.approve() allowance grant
This is possible because Soroban supports authorization trees - a single transaction can carry multiple authorization entries that the signer approves together.
Transaction
└── Subscriber's Auth Entry
    ├── vowena.subscribe(subscriber, plan_id)
    └── usdc.approve(subscriber, vowena_contract, ceiling, expiry)
Compare this to Ethereum, where you’d typically need two separate transactions (approve + subscribe). On Soroban, it’s one transaction, one signature, one fee.
After submission, the blockchain now holds:
  • A subscription record in the Vowena contract (status: Active)
  • A token allowance in the USDC contract (Vowena can pull funds)
5

Each Period, a Keeper Calls charge()

When the billing period elapses, a keeper submits a charge() transaction:
charge(caller: "GKEEPER...ADDR", subscription_id: 42)
The keeper can be:
  • The merchant’s own bot
  • The Vowena Dashboard’s built-in keeper
  • A third-party keeper service
  • Even the subscriber themselves
It doesn’t matter who calls it - the contract enforces all rules regardless.
Keepers are economically incentivized. The transaction fee is negligible ($0.00001), and merchants want their revenue collected on time. Third-party keepers may earn service fees for maintaining reliable charging.
6

Contract Validates and Transfers

Inside the charge() execution, the Vowena contract performs a series of on-chain checks:
1

Status Check

Is the subscription Active? If Paused, Cancelled, or Expired - reject.
2

Time Check

Has at least one full period elapsed since last_charged_at? If not - reject. No double-charging.
3

Trial Check

Is the subscription still in its trial period? If yes - increment the period counter but skip the transfer. The subscriber isn’t charged during trials.
4

Balance and Allowance Check

Does the subscriber have enough USDC balance? Is the token allowance sufficient? If either fails - record failed_at and enter the grace period flow.
5

Transfer

All checks pass. The contract calls:
usdc.transfer_from(subscriber, merchant, amount)
USDC moves directly from the subscriber’s wallet to the merchant’s wallet. The Vowena contract never holds funds.
6

Update State

The contract updates last_charged_at, increments periods_charged, and checks if max_periods has been reached (if set).
7

Subscriber Can Cancel Anytime

At any point, the subscriber can call cancel() to end the subscription.
cancel(caller: "GSUBSCRIBER...ADDR", subscription_id: 42)
This is a direct on-chain action. The subscriber does not need:
  • The merchant’s permission
  • Access to the merchant’s app or website
  • The Vowena Dashboard
  • Any specific frontend
Any Stellar wallet, CLI tool, or block explorer that supports Soroban contract calls can execute the cancellation. The subscription status immediately becomes Cancelled, and no further charges can occur.

​
What If the Merchant Disappears?

One of the most important questions in any subscription protocol: what protections does the subscriber have if the merchant’s app goes offline, the company shuts down, or the merchant becomes unresponsive? Vowena provides four layers of protection:

1. Direct On-chain Cancellation

The subscriber can always call cancel() directly on the Vowena contract. This requires no cooperation from the merchant. Any Stellar wallet or Soroban-compatible tool can submit this transaction.The merchant’s app being offline is irrelevant - the smart contract is always available on the Stellar network.

2. Universal Subscription Manager

The Vowena Dashboard includes a Universal Subscription Manager - a UI that lets any subscriber view and manage all their Vowena subscriptions across every merchant, regardless of which app they originally subscribed through.Even if a merchant’s frontend disappears, the subscriber can find and cancel their subscriptions through the dashboard.

3. Auto-Expiry (max_periods)

If a plan was created with max_periods set (e.g., 12 for an annual subscription billed monthly), the subscription automatically expires after that many billing cycles. No action required from anyone.Even for plans with max_periods: 0 (unlimited), the next two protections still apply.

4. Allowance Expiration

Token allowances on Soroban have a ledger-based expiration. The approve() call sets an expiry ledger, after which the allowance automatically becomes invalid.If no one renews the allowance (which requires the subscriber’s signature), the contract loses the ability to pull funds. The subscription effectively becomes unchargeable.
These protections work in layers. Even if the subscriber takes no action at all, the allowance expiration ensures that a forgotten subscription cannot be charged indefinitely. This is fundamentally different from traditional credit card subscriptions, where charges can continue until the card expires or the subscriber contacts their bank.

​
The Trust Model

What You Trust

  • The Stellar network to process transactions
  • The Soroban VM to execute contract logic correctly
  • The USDC token contract (issued by Circle)
  • The Vowena contract code (open source, auditable)

What You Don't Trust

  • The merchant to be honest (contract enforces rules)
  • The keeper to be reliable (anyone can be a keeper)
  • Vowena the company (protocol is permissionless)
  • Any single frontend (multiple access points exist)

​
Next Steps

Quickstart

Build your first subscription in 5 minutes.

Core Concepts

Deep dive into plans, subscriptions, allowances, and more.

Protocol Architecture

Explore the contract internals, storage model, and error handling.

FAQ

Answers to the most common questions.