How Subscriptions Work
Subscriptions let your app charge a Pioneer a fixed amount of Pi on a fixed schedule, for example 5 Pi every month for a premium plan. This page explains the idea, the terms and the flow. You don't need to write any code yet.
Note: Subscription payments are currently available only on Pi Testnet, on the first version of the Subscription contract (v1). v1 will be replaced before Mainnet: the new contract gets a new address, services must be registered again, and subscribers must subscribe again.
Limits on Testnet v1
- The maximum billing period is ~180 days, so yearly plans aren't possible yet.
- An approval lasts just under 180 days, however many periods it covers, so subscribe with a periods value whose renewals fit in it: 5 for a monthly plan, 25 for a weekly one. A Developer Portal month is 2,629,746 seconds (about 30.44 days). Extending starts a new approval, so ask Pioneers to extend before theirs runs out.
The Subscriptions guide has three pages:
- How Subscriptions Work (this page): what a subscription is, the terms you'll see, and what happens from sign-up to cancellation.
- Implementation & Core Methods: set up the SDK and use the two methods every subscription app needs, subscribe and process.
- Additional Methods: create and manage plans, show Pioneers their subscriptions, and let them extend or cancel.
Table of Contents
- Introduction
- Key Concepts
- The Subscription Flow
- Example: One Subscription Over Time
- Collecting Renewals
- Who Calls What
- Next
Introduction
The user approves a subscription once, in the Pi Wallet. After that, your app collects each renewal without asking the user to sign again.
Subscriptions work differently from one-time Payments. There is no Pi.createPayment call and no backend approve/complete handshake. Instead, all the rules live in Pi's Subscription smart contract on the Pi Blockchain:
- The contract keeps the list of plans (services) and who subscribed to them.
- When a Pioneer subscribes, they allow the contract to take a limited amount of Pi from their wallet for future renewals.
- When a renewal is due, the contract moves the price from the subscriber's wallet to yours, but only when your app asks it to.
The Pi SDK exposes the contract as Pi.SmartContract.Subscription. Each method builds a contract call, asks the Pi Wallet to sign it when needed, and returns the result.
Key Concepts
| Term | Meaning |
|---|---|
| Merchant | The wallet that owns a service and receives the payments. Usually your app's wallet. |
| Subscriber | The Pioneer's wallet that pays for the service. |
| Service | A plan you sell: a name, a price, a billing period and an optional free trial. Each service gets a numeric service_id. |
| Subscription | One subscriber's sign-up to one service. Each subscription gets a numeric sub_id. |
| Period | The billing cycle, in seconds. In the Developer Portal a plan is weekly (604800) or monthly (2629746, about 30.44 days). Periods are fixed lengths, not calendar dates. |
| Trial | A free period at the start. A subscriber gets it only on their first subscription to that service. |
| Auto-renew | When on, the merchant can charge the subscriber each period. When off, the subscription ends after the current period. |
| Allowance (periods) | When subscribing, the subscriber pre-approves the contract to take up to price × periods Pi from their wallet. Each renewal uses one period's worth. |
| Processing | Renewals don't happen by themselves. The merchant calls process to collect every payment that is due. |
Units. Amounts are in stroops: 1 Pi = 10,000,000 stroops, so 5 Pi is "50000000". Times are in seconds. Pass amounts, IDs and periods as strings (for example "50000000") or BigInt values so large numbers are never rounded.
The Subscription Flow
Merchant Subscriber Subscription contract
| | |
|-- registerService(price, period) ---------------------------------------->| creates service_id
| | |
| |-- subscribe(service_id, periods) ->| pays 1st period (or starts trial)
| | | approves price × periods
| | |
| ... one period later ... | |
|-- process(service_id) -------------------------------------------------->| charges every due subscription
| | |
| |-- extendSubscription(periods) ---->| approves more periods
| |-- cancel(sub_id) ----------------->| stops renewals, releases allowance
- The merchant registers a service once, in the Developer Portal.
- A Pioneer subscribes. Without a trial, the first period is paid immediately. With a trial, nothing is paid until the trial ends.
- Each time a period ends, the merchant calls process to collect the next payment from every subscriber who is due.
- When the pre-approved periods run out, the subscriber calls extendSubscription to approve more.
- The subscriber can cancel at any time. They keep access until the end of the period they already paid for.
Example: One Subscription Over Time
Say you register a "Premium Plan" in the Developer Portal: 5 Pi monthly (a period of about 30.44 days), with a 7-day free trial. A Pioneer subscribes on day 0 with auto-renew on and pre-approves 5 periods.
| When | What happens | Pioneer pays | Pioneer has access |
|---|---|---|---|
| Day 0 | The Pioneer subscribes. Their first subscription to this plan, so they get the trial. They pre-approve 5 × 5 = 25 Pi. | Nothing | Yes, until day 7 |
| Day 7 | The trial ends. The next time you run process, the contract charges the first period. | 5 Pi | Yes, until about day 37 |
| About day 37, 68, ... | Each period ends, and process charges the next one. Each charge uses up 5 Pi of the 25 Pi approved. | 5 Pi each time | Yes, one more period each time |
| Any day | The Pioneer cancels. Renewals stop and the rest of the approved Pi is released. No refund for the current period. | Nothing more | Yes, until the paid period ends |
Without a trial, the first 5 Pi is paid on day 0, as part of subscribing.
Things that end a subscription early:
- The renewal is collected too late. A renewal can only be collected for one period after it is due. If a renewal is due on about day 37 and nobody runs process until after about day 68, the contract won't charge it and turns auto-renew off. This is why process must run regularly.
- The Pioneer can't pay. Their balance is too low, or the periods they pre-approved are used up. The charge fails and auto-renew is turned off. They can subscribe again.
- The approval runs out. An approval lasts just under 180 days, however many periods it covers (see Limits on Testnet v1 at the top of this page). With a monthly plan and 5 approved periods, the Pioneer needs to extend after 5 renewals, and in any case before the approval's 180 days are up.
Collecting Renewals
Renewals don't happen by themselves. The contract charges a subscriber only when the merchant calls process, and that call has to be signed by the merchant wallet. There are two ways to do it:
| From the Pi Browser | From your server | |
|---|---|---|
| How it's signed | You enter the merchant wallet's passphrase in the Pi Wallet, every time | Your server signs with the merchant wallet's secret seed |
| Runs on a schedule | No | Yes, for example every 24 or 12 hours |
| Best for | Trying it out, or collecting by hand | Real apps with paying subscribers |
Running process in the Pi Browser is the easiest way to start, but someone has to approve every run by hand. To collect renewals automatically, run it on your server with the Node.js or Ruby server SDK. Implementation & Core Methods explains both.
Who Calls What
| Method | Called by | What it does | Page |
|---|---|---|---|
| subscribe | Subscriber | Signs up and approves future renewals | Core |
| process | Merchant | Collects every renewal that is due | Core |
| registerService | Merchant | Creates a plan. Use the Developer Portal for this. | Additional |
| getMerchantServices, getMerchantSubscriptions | Merchant | Lists your plans and their subscribers | Additional |
| getService, isSubscriptionActive | Anyone | Shows a plan, checks access | Additional |
| getSubscriberSubscriptions, getSubscription, getSubscriptionReservation | Subscriber | Shows the Pioneer's subscriptions and what is still approved | Additional |
| extendSubscription, toggleAutoRenew, cancel | Subscriber | Approves more periods, turns renewals on or off, cancels | Additional |
Next
Continue with Implementation & Core Methods to set up the SDK and add subscribe and process to your app.