Discourse Subscriptions Plugin

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

The Discourse Subscriptions plugin allows you to create one-time as well as recurring subscriptions that users can pay for in order to access gated content. This can be a great way to fund the hosting cost of your community.

This image shows the main page of an online discussion forum with the Subscription plugin enabled. There is now a Subscribe button added to the top nav as well as a Support Us banner.
This image shows the main page of an online discussion forum with the Subscription plugin enabled. There is now a Subscribe button added to the top nav as well as a Support Us banner.1920×1290 107 KB

Features

The Discourse Subscriptions plugin supports the following features:

The “Subscribe” button located in the top nav will take you to the Subscribe page /s where it lists the subscriptions you have configured for your site:

This image displays a web page interface for a platform called "Discourse" where users can subscribe to either a one-time purchase or an ongoing campaign to support the site. (Captioned by AI)
This image displays a web page interface for a platform called "Discourse" where users can subscribe to either a one-time purchase or an ongoing campaign to support the site. (Captioned by AI)1920×1203 64.1 KB

Once a user clicks on one of the “Subscribe” button for a specific plan it will open up the payment page for that plan:

This image shows a web page interface for subscribing to a campaign or service, with fields for selecting a payment plan, entering personal and payment information, and a "Subscribe" button. (Captioned by AI)
This image shows a web page interface for subscribing to a campaign or service, with fields for selecting a payment plan, entering personal and payment information, and a "Subscribe" button. (Captioned by AI)1920×1293 88.2 KB

After a user fills out their payment details and their address and click “Subscribe”, they are shown a “Thank you!” message and taken to their billing page:

The image shows a browser window with a subscription management interface, displaying a message confirming that a new subscription has been successfully created. (Captioned by AI)
The image shows a browser window with a subscription management interface, displaying a message confirming that a new subscription has been successfully created. (Captioned by AI)1920×1274 65.6 KB

The user is also automatically added to a group of your choosing so that you can easily see which users have subscribed as well as provide gated content in categories only that group can see.

The image shows a web interface displaying various user groups such as contributors, creators, editors, moderators, publishers, and a group named "supporter" which the user appears to be a member of. (Captioned by AI)
The image shows a web interface displaying various user groups such as contributors, creators, editors, moderators, publishers, and a group named "supporter" which the user appears to be a member of. (Captioned by AI)1920×1296 80.6 KB

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.

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

:warning: 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

  1. Install & enable the plugin
  2. Configure Payment Gateway (Stripe)
  3. Configure Webhooks & Events in Stripe
  4. Add your Stripe keys (public, secret, webhook secret) under Admin > Plugins > Installed > Subscriptions > Settings /admin/site_settings/category/discourse_subscriptions?filter=plugin%3Adiscourse-subscriptions.
  5. Create a group for your subscribers to join via purchase
  6. Create a product and plan under Admin > Plugins > Subscriptions
  7. 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

:bomb: 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
  • checkout.session.completed

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).

:warning: 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 > Plugins > Installed > Subscriptions > Settings /admin/site_settings/category/discourse_subscriptions?filter=plugin%3Adiscourse-subscriptions.

This image shows the configuration settings for the Discourse Subscriptions plugin, which includes options to enable the plugin, display a subscribe button in the navigation, and provide Stripe API keys and a webhook secret for payment processing. (Captioned by AI)
This image shows the configuration settings for the Discourse Subscriptions plugin, which includes options to enable the plugin, display a subscribe button in the navigation, and provide Stripe API keys and a webhook secret for payment processing. (Captioned by AI)2248×1230 171 KB

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 card numbers | 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.

managed failed payments
managed failed payments1034×522 39.3 KB

Update Payment Info

Users can update their card used for individual subscriptions by visiting the billing page and clicking the edit button next to the subscription which will open up this screen:

CleanShot 2024-07-11 at 13.58.15@2x
CleanShot 2024-07-11 at 13.58.15@2x1920×1321 93.5 KB

Stripe Checkout with Stripe Pricing Tables

You can also opt to replace the Subscription Plugin product and checkout pages and instead use Stripe Checkout with Stripe Pricing Tables.

CleanShot 2024-07-11 at 13.33.53@2x
CleanShot 2024-07-11 at 13.33.53@2x1920×1382 68.7 KB

CleanShot 2024-07-11 at 13.34.44@2x
CleanShot 2024-07-11 at 13.34.44@2x1920×1387 92.4 KB

To use Stripe Checkout with the Subscription plugin setup a Pricing Table inside of Stripe and add the pricing-table-id from the Pricing Table embed code to the discourse_subscriptions_pricing_table_id site setting as well as enabling the feature.

image
image1576×460 27 KB

When setting up the Pricing Table inside of Stripe it is recommended to link the user to your site after checkout is complete otherwise they will stay on a Stripe confirmation page without a link back to your site.

A screenshot of a payment settings page showing options for supporting a service and setting up a confirmation page. (Captioned by AI)
A screenshot of a payment settings page showing options for supporting a service and setting up a confirmation page. (Captioned by AI)1234×1394 103 KB

Redirecting to https://<your-site>/my/billing/subscriptions is a good choice for subscriptions. For one-off payments you could link directly to https://<your-site>/my/billing/payments.

Automatic Tax Collecting

To enable Automatic Tax Collecting check the Site Setting box for discourse_subscriptions_enable_automatic_tax.

If you enable it, but you have not configured your Stripe instance properly to collect tax users may see this popup after completing the checkout process:

image
image1380×314 19.1 KB

There is this guide for more info, but there shouldn’t be much to do since the plugin is now passing in the appropriate automatic_tax[enabled]=true parameter (step 5).

Be sure you configure your registrations (step 4) as well:

CleanShot 2024-07-10 at 13.29.55@2x
CleanShot 2024-07-10 at 13.29.55@2x2540×1166 232 KB

Here is an example Discourse Subscription Plugin transaction in Stripe showing that tax was automatically collected:

image
image1554×758 60.3 KB

Settings

Name Description
discourse subscriptions enabled Enable the Discourse Subscriptions plugin.
discourse subscriptions extra nav subscribe Show the subscribe button in the primary navigation
discourse subscriptions public key Stripe Publishable Key
discourse subscriptions secret key Stripe Secret Key
discourse subscriptions webhook secret Stripe Webhook Secret
discourse subscriptions currency Default Currency Code. This can be overridden when creating a subscription plan.
discourse subscriptions campaign enabled Enables a campaign banner to promote supporting this community financially.
discourse subscriptions campaign goal The numerical goal for your support campaign (subscribers or amount raised).
discourse subscriptions campaign type Selects the type of campaign to run (subscribers or monthly amount raised).
discourse subscriptions campaign banner location Selects the location of the campaign banner (top or sidebar).
discourse subscriptions campaign banner bg image Upload a custom image to use as the background on the campaign banner.
discourse subscriptions campaign banner shadow color Selects the color of the campaign banner drop shadow.
discourse subscriptions campaign show contributors Show avatars of the most recent purchases of subscription products.
discourse subscriptions campaign product The Stripe product id to send supporters when they click the button on the campaign. If this setting is blank, supporters will be directed to the main products page.
discourse subscriptions campaign grant Grants the user a free month of subscriptions
discourse subscriptions pricing table id The Stripe pricing table id from the embed code
discourse subscriptions pricing table enabled Enables using the Stripe pricing table and replaces the existing subscribe page
discourse_subscriptions_enable_automatic_tax Toggles if sales tax is going to be collected. Requires some setup in Stripe.
discourse_subscriptions_enable_verbose_logging Enables more verbose logging to aid in debugging. Please do not leave permanently enabled in production.

:discourse2: Hosted by us? This plugin is available on our Standard, Business, and Enterprise hosting plans Subscriptions | Discourse - Civilized Discussion

Last edited by @sam 2025-05-07T01:37:02Z

Last checked by @MarkDoerr 2024-07-11T20:25:35Z

Check documentPerform check on document:
135 Likes