# Overview Welcome to Subscription Management on Algorand Welcome to the Subtopia documentation. Subtopia is a decentralized platform that allows you to create and manage flexible on-chain subscriptions for your users. Built on the Algorand blockchain, Subtopia provides an easy-to-use and secure solution for integrating subscription payment processing and management into your app. ### Features Overview #### Utility as a Service Subtopia enables you to create a subscription service in minutes with flexible configuration options. Customize your subscription service to your needs, whether you want time-based or unlimited subscription plans. #### Easy Integration Integrate Subtopia into your website using a JavaScript SDK or HTML. Advanced users can leverage the ABI interface to interact with Subtopia from their own smart contracts for quick subscription membership lookups. #### Decentralized Subtopia operates entirely on the Algorand blockchain, ensuring cheap and fast transactions while securely persisting your data on a public ledger. ### Glossary Throughout this document you will see the following terms, here is the glossary explaining the definitions and abbreviations: * **Subscribers**: Users who subscribe to a dApp * **Creators**: Users who create dApps * **Product**: Subscription Management Infrastructure (also referred to as "Product") * **Registry**: Subscription Management Registry (also referred to as "Registry") * **Locker**: Subscription Management Locker (also referred to as "Locker") * **Discount**: An on-chain object that represents the discount to apply on subscriptions when users are purchasing them via your Product instance * **Subscription Pass:** An on-chain object that represents purchases **Product** subscription ### Platform portals #### Creator Portal A portal accessible within the platform that aims to provide a convenient experience for Developers, Projects or Businesses to deploy their decentralized subscription management infrastructures. Currently is the most extensive operational mode offered by the platform. #### User Portal A portal accesible within the platform that aims to provide a convenient experience for Users of products that use Subtopia for their subscription infrastructure management. To be significantly expanded in future. Currently offers a central entry view to quickly choose and manage existing subscriptions. ### Additional Resources * [Subtopia Website](http://subtopia.io/) * [Subtopia SDK](https://sdk.subtopia.io/) # How it works? High level architecture of the platform's on-chain components The diagram effectively outlines the relationships and interactions between the different on-chain components of Subtopia system, focusing on the Registry Contract as the central entity deploying and managing Product Contracts, Creator Lockers, and User Lockers.

Platform overview

1. **Registry Contract (Main Entity)**: This contract is the central component of the system. Users interact with the Registry Contract to deploy Product Contracts. Arrows from the Registry Contract depict the creation of Product Contracts, Creator Lockers, and User Lockers. 2. **Product Contract (Integration)**: Once created, the Product Contract integrates with the user's project, website, or app. This integration is represented by an arrow pointing from the Product Contract to a user's project icon. 3. **Creator Locker (Revenue and Ownership Management)**: A Creator Locker interacts with multiple Product Contracts. It is responsible for storing revenue in an escrow, allowing creators to withdraw their earnings. Additionally, the Creator Locker serves as a lookup mechanism to determine which products a user owns. The diagram shows an instance of a Creator Locker interacting with 'N' number of Product Contracts. 4. **User Locker (Subscription Tracking and Management)**: The User Locker tracks active subscriptions of users and features a quick-edit UI, resembling a subscription view page seen in iOS devices. This component allows users to overview and manage their active subscriptions easily. The diagram uses specific colors and styles to distinguish between different components and their functions: * User's project/website/app is marked with a light blue color. * Revenue Escrow is highlighted in light pink. * Active Subscriptions and Subscription View Page are in light cyan and light red, respectively. # Pricing Overview of platform pricing model | Fee Type | Description | Amount | | -------------------- | ------------------------------------------------------------------------- | --------------- | | **Transaction Fee** | Cost for deploying the ***Subtopia Product*** contract on the blockchain. | **\~0.8 Algo** | | **Platform Fee** | Fixed cost charged by the Subtopia platform for deployment. | **$5** | | **Subscription Fee** | Flat fee charged per subscription purchase by a user. | **$0.02 Cents** | Upon deploying a single ***Product*** contract you will be able to upgrade it on-chain to include all of the latest features and improvements that.
{% hint style="info" %} Note that if you deploy a **Product** with a **Price** of 0 Algo/ASA, platform will not charge your subscribers with a **Subscription Fee** of $0.02 Cents. {% endhint %} # Creating Products A guideline on creating your Products This chapter will guide you through the process of getting started with Subtopia. By following these steps, you will be able to create and manage on-chain subscriptions for your users. ### Prerequisites Before you can use the platform, make sure you meet the following requirements: * Authenticate with one of the preferred wallet providers: Pera Wallet, Defly Wallet or passwordless login via Email. ### Creating a new Product To create a new Product, follow these steps: #### Step 1: Select Subscription Type Choose one of the two subscription types provided by the platform: 1. **Unlimited**: This subscription never expires once purchased by your user. Users can transfer, delete, or vanity claim their pass to hold in their wallet. 2. **Time-based**: Similar to Unlimited, but allows you to set a custom duration (day, week, month, quarter, half a year, a year). Users can delete it, resubscribe, or mint a renewal pass. If you set the price to 0, the platform won't charge you any extra platform fees and you can use it freely. A common scenario for selling 0 priced subscriptions could be, eligibility validation or building systems for gated access to communities, websites or projects. #### Step 2: Provide Subscription Settings Fill in the required information for your subscription settings: 1. **Product name**: Enter a name for your product (e.g., "Not Netflix"). 2. **Subscription name**: Enter a name for your subscription pricing plan (e.g., "Not Premium"). 3. **Unit Name**: Custom name of a smallest unit of the Subscription ASA that is to be minted per each new subscriber. For examples, consider short yet descriptive names like "PASS", 'USDC', "TOKEN" and etc. Each pass minted will follow the pattern `{Unit Name}-#{number of subscription mint}`. Where `number of subscription mint` is a simple counter that is increment on each new subscription. 4. **ASA Image**: To be customizable via platform soon, currently defaults to the "stock subtopia pass image". 5. **Asset:** Pick an asset to use as a currency for accepting payments. Defaults to Algo, if you have opted-in assets on your wallets they will be presented on the input form. Any custom ASA with `total` bigger than zero is supported. 6. **Price**: Enter a price, which should be at least 1 unit in the ASA type you choose or Algo. 7. **Max Limit**: Optionally, set a maximum limit for items to sell. Upon reaching the limit, new users won't be able to subscribe unless someone else cancels their subscription, and the limit counter decreases. There are three counters: total sales, active, and max limit. The default value of 0 for max limit means no limit. 8. **Image**: Optionally you can upload a custom image that is going to be stored on `IPFS` and used as a cover image on your product checkout page. #### Step 3: Confirm Selection Confirm your selection and sign two transactions: 1. First transaction: Fee payment to activate or fund your locker account. A Locker is your escrow that will hold all revenue from sells of your subscriptions, you can withdraw ALGO or ASAs from it at any time you want. 2. Second transaction: Call to Registry to deploy a new Product contract After creating the Product, you will be presented with two cards showing how to embed interactions with your newly created Product using the JavaScript SDK available at [sdk.subtopia.io](https://sdk.subtopia.io/) or via HTML iframe embedding with an API call to [api.`subtopia`.io](https://api.subtopia.io/). > It is important to understand that each deployed Product application is a combination of Product and your individual Pricing plan. If you want multiple pricing plans you will need to deploy additional Contracts but with existing Product name pre-selected. ### Next steps ### Troubleshooting Ensure you have enough funds to perform operations. If you would like to report a bug send an email to or join the discord community server [here](https://discord.gg/JCjHpXHy). # Managing Products A guideline on managing your Products This chapter will guide you through the process of managing your Products on the Subtopia platform. ### Common Tasks * Withdraw revenue from the Locker in Algo or ASAs * Browse information about active Products and respective pricing plans. * Access integration popups for the JavaScript SDK and HTML iframe * Transfer Product ownership to a different account * Access the user portal * Delete a subscription ### Withdrawing Funds from the Locker To withdraw funds from the Locker: 1. Navigate to the top row on the Manage page. 2. Click the "Withdraw" button if there are any claimable Algo available. 3. For ASAs, select the ASA in the dropdown list. The "Withdraw" button will become visible if there are any claimable ASA revenue available. ### Transferring Subscription Ownership To transfer ownership of a subscription: 1. Click the "Manage" button on the row corresponding to the specific Product instance of interest. 2. Enter the wallet address of the recipient. 3. Sign the transfer transactions. Please note that the recipient will need to pay additional fee to cover Locker application creation on behalf of the recepient if he/she does not have one yet. ### Deleting a Subscription To delete a subscription, follow this three-step process: 1. Click the "Manage" button and then click "Disable". This will set your product in withdrawal-only mode. 2. Once all active subscribers are unsubsribed, or their respective subscriptions expired (if time-based), delete button in "Manage" menu will be activated. 3. Click "Delete". Note that this is a destructive operation and will delete all actively subscribed user's passes. The platform does not currently provide auto-refund functionality, so you will need to handle refunds yourself if you provide such guarantees on your platform. > Please note, if you have active discounts on the Product, you also need to delete them first before deleting the entire Product application. ### Troubleshooting If you encounter any issues, submit a report to or join the Subtopia Discord community server at . # Creating Discounts A guideline on creating discounts for your Products This chapter will guide you through the process of getting started with Subtopia. By following these steps, you will be able to create and manage on-chain subscriptions for your users. ### Prerequisites * Make sure to have an active Product instance created on which you are a manager (creator) ### Creating a new Discount To create a new discount follow these steps: #### Step 1: Provide discount details Navigate to `Manage` page and click on `Discounts` under `Manage` button menu on an Product you'd like to configure. Discounts can be either `Fixed` or `Percentage` based. You can also optionally specify the expiration date or set it to 0 to have your discount active until you want to delete it manually. > Please note for time-based discounts, quartery, semi-annual and annual price is calculated by multiplying based monthly price on number of month. Discount is then applied on the base \* number of month. **Step 2: Click `Create new`** Upon clicking, sign the required transactions and your discount will be activated. When user is purchasing a subscription the active discount will be auto applied and displayed to user. After discount is created you can manage it within the same popup as it will be loaded into Manage Table. # Manage and delete Discounts A guideline on managing discounts for your Products ### Prerequisites * Make sure to have an active Product instance created on which you are a manager (creator) * Make sure to have an active discount created for that Product ### Deleting a discount To delete an active discount follow these steps: 1. Open `Discounts` popup on `Manage` page 2. Select discount you want to delete and click `Delete` 3. Sign transactions and the discount will be removed. All new subscribers using the Product will no longer get discount auto-applied. # Checkout Portal Overview of the 'no-code' options The simplest way to relay users to purchase the subscription is to redirect them to the checkout portal page. To copy the URL: 1. Navigate to `Manage` page 2. Click on the `Gear` icon on a row corresponding to the `Product` you wish to integrate 3. Click on `JS SDK` - the opened popup will contain a button that you can click to copy the direct Checkout/Subscription Portal url. \ \ If you also require capability to perform a lookup on user's subscription status and do not have a need to use JS SDK to create completely customized experience for your users, refer to [API section.](/integrations/api) # Javascript SDK Overview of JS SDK integration options Once your Product is deployed the next step is to integrate interactions with your Product into your application so your users can start purchasing subscriptions, while you will be able to verify whether they are eligible subscribers or not.\ \ For detailed integration guide refer to sdk.subtopia.io. # AlgoKit References on official AlgoKit template for Subtopia-enabled React dApps Jumpstart your Algorand dApp development with our AlgoKit template. This template enhances the official AlgoKit React template and integrates seamlessly with , providing a solid base for subscription-enabled dApps. {% code overflow="wrap" fullWidth="false" %} ```bash algokit init --template-url https://github.com/subtopia-algo/algokit-subtopia-template ``` {% endcode %} **Key Features** * **Integrated with Subtopia-js-sdk**: Ensures smooth integration with Subtopia's features. * **High Customizability**: Tailor the template to your project's specific needs. * **Stable Foundation**: Ideal for building Algorand blockchain dApps. **Getting Started** 1. **Access the Template**: Visit our GitHub [here](https://github.com/subtopia-algo/algokit-subtopia-template) to find the template and setup instructions. 2. **Download and Customize**: Adapt the template to fit your project requirements. **Join and Contribute** This template codebase is completely open source. Contributions are welcome to improve the template. **Ready to Code** With this AlgoKit template, you're set to develop innovative dApps in the Algorand ecosystem. Happy coding! 🚀💻 # API Guideline on Subtopia API for membership lookups If you also require capability to perform a lookup on user's subscription status, refer to Swagger on [api.subtopia.io/docs](https://api.subtopia.io/docs) for an endpoints that will return subscription status for provided wallet address. # ABI Guidelines on accessing membership lookup from via ABI Please reach out to and outline your use case for next steps and suggestions on how to access Subtopia for membership lookups on-chain from within your own Algorand Smart Contract. # Wallet-based Login For detailed documentation and guides, refer to the respective links: * [Defly Wallet Documentation and How-To](https://docs.defly.app/) * [Pera Wallet Documentation and How-To](https://docs.perawallet.app/) # Email Login > Please note, the feature has been deprecated! An alternative email based authentication option is to be introduced in 2025. In the meantime if you are an existing Subtopia user who previously authenticated over email, navigate [here](https://reveal.magic.link/algorand/subtopia) to export your associated custodial account. This guide will walk you through the process of logging into your account using your email address. ## Step 1: Navigate to the Login Page First, navigate to the login page of the Subtopia platform. You can do this by clicking on the "Login" button usually located at the top right corner of the website. ## Step 2: Enter Your Email Address Once you're on the login page, you'll see a field asking for your email address. Enter the email address associated with your Subtopia account. ## Step 3: Follow instructions in the popup After entering your email address, proceed with instructions from authentication provider. ## Step 4: Check Your Email Go to your email inbox and look for an email from Subtopia. This email contains a magic link that will log you into your account. ## Step 5: Click on the Magic Link Open the email from Subtopia and click on the magic link. This will automatically log you into your Subtopia account. And that's it! You're now logged into your Subtopia account and ready to start managing your subscriptions. * If you encounter any issues while using the fiat onramp feature, please [contact our support team](mailto:info@subtopia.io). * Join our [Discord community](https://discord.com/invite/gzXtwTVj9a) for further assistance and discussions. # Exporting keys There are several options available when you need to withdraw funds from the wallet address associated with your email: ## Option 1: Transfer Funds The 'Transfer Funds' button on the Authentication Portal allows you to select the amount of Algos or ASAs in your email-based wallet and transfer them to any Algorand wallet of your choice. This could be a wallet in your mobile wallet provider (Pera, Defly, etc.). ## Option 2: Export Keys > **Note:** This option is only recommended for experienced users! Never reveal your mnemonic. After exporting the keys, you can import them into a wallet provider of your choice to manually manage the resources in your email-based wallet. # Contacts How to contact us? **Email**: **Discord**: