Skip to main content

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:

  1. How Subscriptions Work (this page): what a subscription is, the terms you'll see, and what happens from sign-up to cancellation.
  2. Implementation & Core Methods: set up the SDK and use the two methods every subscription app needs, subscribe and process.
  3. Additional Methods: create and manage plans, show Pioneers their subscriptions, and let them extend or cancel.

Table of Contents​

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​

TermMeaning
MerchantThe wallet that owns a service and receives the payments. Usually your app's wallet.
SubscriberThe Pioneer's wallet that pays for the service.
ServiceA plan you sell: a name, a price, a billing period and an optional free trial. Each service gets a numeric service_id.
SubscriptionOne subscriber's sign-up to one service. Each subscription gets a numeric sub_id.
PeriodThe 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.
TrialA free period at the start. A subscriber gets it only on their first subscription to that service.
Auto-renewWhen 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.
ProcessingRenewals 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
  1. The merchant registers a service once, in the Developer Portal.
  2. A Pioneer subscribes. Without a trial, the first period is paid immediately. With a trial, nothing is paid until the trial ends.
  3. Each time a period ends, the merchant calls process to collect the next payment from every subscriber who is due.
  4. When the pre-approved periods run out, the subscriber calls extendSubscription to approve more.
  5. 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.

WhenWhat happensPioneer paysPioneer has access
Day 0The Pioneer subscribes. Their first subscription to this plan, so they get the trial. They pre-approve 5 × 5 = 25 Pi.NothingYes, until day 7
Day 7The trial ends. The next time you run process, the contract charges the first period.5 PiYes, 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 timeYes, one more period each time
Any dayThe Pioneer cancels. Renewals stop and the rest of the approved Pi is released. No refund for the current period.Nothing moreYes, 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 BrowserFrom your server
How it's signedYou enter the merchant wallet's passphrase in the Pi Wallet, every timeYour server signs with the merchant wallet's secret seed
Runs on a scheduleNoYes, for example every 24 or 12 hours
Best forTrying it out, or collecting by handReal 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​

MethodCalled byWhat it doesPage
subscribeSubscriberSigns up and approves future renewalsCore
processMerchantCollects every renewal that is dueCore
registerServiceMerchantCreates a plan. Use the Developer Portal for this.Additional
getMerchantServices, getMerchantSubscriptionsMerchantLists your plans and their subscribersAdditional
getService, isSubscriptionActiveAnyoneShows a plan, checks accessAdditional
getSubscriberSubscriptions, getSubscription, getSubscriptionReservationSubscriberShows the Pioneer's subscriptions and what is still approvedAdditional
extendSubscription, toggleAutoRenew, cancelSubscriberApproves more periods, turns renewals on or off, cancelsAdditional

Next​

Continue with Implementation & Core Methods to set up the SDK and add subscribe and process to your app.