# Vowena

## Docs

- [accept_migration](https://vowena.xyz/docs/api-reference/accept-migration.md): Accepts a pending plan migration for a subscriber. Cancels the old subscription, creates a new one on the target plan, and sets a fresh token allowance.
- [cancel](https://vowena.xyz/docs/api-reference/cancel.md): Cancels a subscription immediately and irreversibly. Can be called by either the subscriber or the plan merchant. Removes the subscription from active billing.
- [charge](https://vowena.xyz/docs/api-reference/charge.md): Charges a due subscription by transferring tokens from subscriber to merchant. Permissionless. Anyone can call this function to trigger billing.
- [create_plan](https://vowena.xyz/docs/api-reference/create-plan.md): Creates a new subscription billing plan on-chain with configurable pricing, billing period, trial length, grace period, and price ceiling protections.
- [extend_ttl](https://vowena.xyz/docs/api-reference/extend-ttl.md): Extends the time-to-live of plan and subscription storage entries on the Soroban ledger, preventing them from being archived and ensuring data availability.
- [get_merchant_plans](https://vowena.xyz/docs/api-reference/get-merchant-plans.md): Returns all plan IDs belonging to a specific merchant address. Read-only query that requires no wallet signature. Use this to discover a merchant's plans.
- [get_plan](https://vowena.xyz/docs/api-reference/get-plan.md): Returns the full Plan struct for a given plan ID, including amount, period, trial settings, grace period, and price ceiling. Read-only, no signature required.
- [get_plan_subscribers](https://vowena.xyz/docs/api-reference/get-plan-subscribers.md): Returns all active subscription IDs on a given plan. Read-only query requiring no wallet signature. Useful for merchants tracking their subscriber base.
- [get_subscriber_subscriptions](https://vowena.xyz/docs/api-reference/get-subscriber-subscriptions.md): Returns all subscription IDs for a given subscriber address across every merchant on Vowena. Read-only query requiring no wallet signature.
- [get_subscription](https://vowena.xyz/docs/api-reference/get-subscription.md): Returns the full Subscription struct including status, billing history, next billing time, and migration state. Read-only, no signature required.
- [initialize](https://vowena.xyz/docs/api-reference/initialize.md): One-time contract initialization that sets the admin address and starts plan and subscription ID counters. Rejects subsequent calls.
- [API Reference](https://vowena.xyz/docs/api-reference/introduction.md): Complete reference for every function in the Vowena Soroban smart contract - parameters, authorization, return types, events, and error codes.
- [reactivate](https://vowena.xyz/docs/api-reference/reactivate.md): Reactivates a paused subscription by re-approving the token allowance and attempting an immediate charge. Returns the subscription to active billing on success.
- [refund](https://vowena.xyz/docs/api-reference/refund.md): Issues a partial or full refund to a subscriber. The merchant authorizes a transfer from their own wallet, recorded on-chain as a verifiable receipt.
- [reject_migration](https://vowena.xyz/docs/api-reference/reject-migration.md): Rejects a pending plan migration request. The subscriber stays on their current plan at the current price. Clears the migration flag from the subscription.
- [request_migration](https://vowena.xyz/docs/api-reference/request-migration.md): Requests migration of all active subscribers from an old plan to a new one. Each subscriber must accept or reject. Both plans must belong to the same merchant.
- [subscribe](https://vowena.xyz/docs/api-reference/subscribe.md): Subscribes to a billing plan by setting a token allowance and creating an on-chain subscription. One signature covers both the contract call and approval.
- [update_plan_amount](https://vowena.xyz/docs/api-reference/update-plan-amount.md): Updates the billing amount of an existing plan. The new amount must stay within the price ceiling that subscribers agreed to, so no re-authorization is needed.
- [Core Concepts](https://vowena.xyz/docs/concepts.md): Understand the building blocks of the Vowena protocol: plans, subscriptions, token allowances, billing cycles, price ceilings, grace periods, and keepers.
- [Keeper Setup](https://vowena.xyz/docs/dashboard/keeper-setup.md): Configure automated billing for your Vowena subscriptions. Use the built-in dashboard keeper or run a standalone keeper bot for full control.
- [Merchant Guide](https://vowena.xyz/docs/dashboard/merchant-guide.md): Step-by-step guide for merchants using the Vowena Dashboard. Create plans, manage subscribers, monitor billing, and configure auto-charging.
- [Dashboard Overview](https://vowena.xyz/docs/dashboard/overview.md): The Vowena Dashboard is a Next.js app for managing on-chain subscriptions. Merchants create plans and subscribers manage billing in one place.
- [Subscriber Guide](https://vowena.xyz/docs/dashboard/subscriber-guide.md): Manage all your Vowena subscriptions from one dashboard. View billing history, handle plan migrations, and cancel any subscription with a single click.
- [FAQ](https://vowena.xyz/docs/faq.md): Frequently asked questions about the Vowena protocol covering billing, subscriptions, keepers, migrations, security, and technical architecture.
- [How It Works](https://vowena.xyz/docs/how-it-works.md): A visual step-by-step walkthrough of the Vowena protocol - from plan creation to recurring charges to cancellation. This is the full picture.
- [Vowena](https://vowena.xyz/docs/index.md): Vowena is the first trustless recurring payment protocol on Stellar. On-chain subscription billing powered by Soroban smart contracts and USDC token allowances.
- [Billing](https://vowena.xyz/docs/protocol/billing.md): The complete charge flow in Vowena: permissionless billing, pre-check mechanics, grace period handling, trial periods, and balance verification.
- [Deployment Guide](https://vowena.xyz/docs/protocol/deployment.md): Step-by-step guide to building, deploying, and initializing the Vowena smart contract on Stellar's Soroban platform - for both mainnet and testnet.
- [Migrations](https://vowena.xyz/docs/protocol/migrations.md): How Vowena handles plan changes with explicit subscriber consent - the migration system that prevents silent price increases and protects consumers.
- [Architecture Overview](https://vowena.xyz/docs/protocol/overview.md): Deep dive into the Vowena single-contract architecture on Soroban, covering storage strategy, data models, TTL management, and the event system.
- [Plans](https://vowena.xyz/docs/protocol/plans.md): How merchants create, configure, and manage subscription plans on Vowena - including pricing, trials, grace periods, and the price ceiling mechanism.
- [Refunds](https://vowena.xyz/docs/protocol/refunds.md): How merchants issue on-chain refunds in Vowena - partial refunds, verifiable receipts, and the refund flow from the merchant's own funds.
- [Security & Consumer Protection](https://vowena.xyz/docs/protocol/security.md): Vowena's security architecture - how subscribers are protected from merchant failure, price manipulation, and custodial risk through on-chain guarantees.
- [Subscriptions](https://vowena.xyz/docs/protocol/subscriptions.md): The subscription lifecycle on Vowena - creation, state machine, status transitions, allowance calculations, and the one-signature authorization model.
- [Quickstart](https://vowena.xyz/docs/quickstart.md): Go from zero to a working on-chain subscription in 5 minutes. Install the Vowena SDK, create a billing plan, subscribe a wallet, charge, and cancel.
- [Amount Conversion](https://vowena.xyz/docs/sdk/amounts.md): Convert between human-readable USDC amounts and on-chain stroops. Understand USDC decimal precision and the helper constants provided by the SDK.
- [VowenaClient Reference](https://vowena.xyz/docs/sdk/client.md): Complete API reference for VowenaClient. Every write method, read method, and submit function with signatures, parameters, and TypeScript examples.
- [Embed](https://vowena.xyz/docs/sdk/embed.md): Add Vowena subscribe buttons and pricing tables to any app in three lines of code. Plan ID in, signed subscription out.
- [Event Polling](https://vowena.xyz/docs/sdk/events.md): Listen to on-chain Vowena contract events using getEvents() for one-off queries or VowenaEventPoller for continuous real-time billing monitoring.
- [Installation & Setup](https://vowena.xyz/docs/sdk/installation.md): Install the Vowena TypeScript SDK from npm, configure your VowenaClient for Stellar mainnet or testnet, and explore all available exports and type definitions.
- [Keeper Bot](https://vowena.xyz/docs/sdk/keeper.md): Run an automated keeper bot that charges due subscriptions on schedule. Understand how keepers work, configure environment variables, and deploy to production.

## Optional

- [Blog](https://vowena.xyz/blogs)
- [GitHub](https://github.com/vowena)
- [npm](https://www.npmjs.com/package/@vowena/sdk)