Discourse Subscriptions

blake · February 6, 2020, 4:15am


	Summary	Discourse Subscriptions allows site owners to sell recurring and one-time purchase subscriptions that grant access to a group on a Discourse instance.
	Repository Link	https://github.com/discourse/discourse-subscriptions
	Install Guide	How to install plugins in Discourse

Features

Discourse Subscriptions supports the following features:

Create new products and plans from the admin panel
Cancel and refund subscriptions from the admin panel
Create one time purchase or recurring subscription plans
Add free trials on recurring subscriptions
SCA/3D Secure support
Add/remove users from plan groups as they subscribe/cancel
Cancel subscription from user profile
Cancellation of subscription at end of subscription period

Terms

Subscription - Subscriptions are a recurring payment plan which allow you to control access to content on your community. When a subscription is created or deleted, a user is added or removed from the user group you associate with your subscription plan. A subscription is made up of a product and plans.
Product - A product in Stripe’s terms is what you’re selling. A product can contain one or more plans.
- To add a description to your product, add a metadata field named “description” and use that one instead. You can use Markdown.
Plan - A plan contains a price, recurring cycle, and associates with a group to which your subscribers gain access.

Be very careful to keep your Stripe private keys safe and secure at all times.

If you were to shut down your instance of Discourse, uninstall this plugin or your site were to go offline, Stripe will continue to bill your customers for your service until the subscription is cancelled.

Configuration

Install & enable the plugin
Configure Payment Gateway (Stripe)
Configure Webhooks & Events in Stripe
Add your Stripe keys (public, secret, webhook secret) under Admin > Plugin > Settings
Create a group for your subscribers to join via purchase
Create a product and plan under Admin > Plugins > Subscriptions
Profit!

Set up your Payment Gateway.

Firstly, you’ll need an account with the Stripe payment gateway. To get started, you can set up an account in test mode and see how it all works without making any real transactions or having to set up a bank account. There is no test mode toggle in the plugin; instead, be sure to use your developer keys (they begin with pk_test, sk_test)

Set up Webhooks and Events in your Stripe account

Webhooks are required to make subscription cancellations work fully. Be sure you have them configured correctly.

Once you have an account on Stripe, you’ll need to tell Stripe your website’s address so it can notify you about certain transactions. You can enter this in your Stripe dashboard under Endpoints > URL.

Webhooks address: [your server address]/s/hooks – where [your server address] is the URL of your Discourse install.

You’ll also need to tell Stripe which events it should notify you about via the webhook URL.

Currently, Discourse Subscriptions responds to the following events:

customer.subscription.deleted
customer.subscription.updated

Add the Stripe API and Webhook keys to your plugin settings

Stripe needs to be authorized to communicate with your website. To do this, it publishes a pair of private and public API keys and a signing secret for your web hooks.

To authorize webhooks, add the API keys and webhook secret from Stripe to your settings page (under Developers).

Adding production keys will make live payments. If you plan to test, be sure to switch to View test data mode and get pk_test and sk_test keys under Developers.

In your Stripe account settings, see:

Add these keys under the appropriate settings in Admin > Settings > Plugins.

Set up your User Groups in Discourse

When a user successfully subscribes to your Discourse application, after their credit card transaction has been processed, they are added to a User Group. By assigning users to a User Group, you can manage what your users have access to on your website. User groups are a core functionality of Discourse and this plugin does nothing with them except add and remove users from the group you associated with your Plan.

Create one or more products with plans.

Under Admin > Plugins > Subscriptions, click add a new Product. Once you have a product saved, you can add plans to it. Keep in mind that the pricing and billing intervals of plans cannot be changed once you create them. This is to avoid confusion around subscription management.

If you take a look at your Stripe Dashboard, you’ll see all those products and plans are listed. Discourse Subscriptions does not create them locally. They are created in Stripe.

Testing

Test with these credit card numbers:

4242 4242 4242 4242
4111 1111 1111 1111 (no authentication required)
4000 0027 6000 3184 (authentication required)

For more test card numbers: Test cards | Stripe Documentation

Visit /s and enter a few test transactions.

Going Live

Once you’re ready to go live, change your API and webhook secret keys to production keys. You will need to create new products and plans in live mode.

Do be aware that if if you don’t properly configure Stripe webhooks, and recurring payments fail to process for any reason (expired credit card, etc.), users will still have access to the group . To have Stripe automatically cancel subscriptions, be sure to set your Manage failed payments settings similar to the below image and configure webhooks as described above.

CHANGELOG

2021-06-02T05:00:00Z Support campaigns added
2021-01-13T06:00:00Z Coupon code creation in admin panel
2021-01-07T06:00:00Z Coupon code support (client only, creation required in Stripe)
2020-11-02T06:00:00Z Subfolder install support
2020-10-30T05:00:00Z Refund subscriptions from admin panel
2020-10-29T05:00:00Z Improve anonymous user UX

TODO pr-welcome

Extend rake subscriptions:import to migrate from other tools

If you were running this plugin prior to 2020-05-22T05:00:00Z, you may need to import subscriptions created by the plugin using the rake task rake subscriptions:import. This will pull products from Stripe, let you choose which to import, and subsequently import the related subscriptions to your site.