Discourse Subscriptions

:mega: Summary: Discourse Subscriptions allows site owners to sell recurring and one-time purchase subscriptions that grant access to a group on a Discourse instance.

:link: GitHub: https://github.com/discourse/discourse-subscriptions
:arrow_right: Install: Follow the plugin installation guide.


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


  • 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.
  • Plan - A plan contains a price, recurring cycle, and associates with a group to which your subscribers gain access.

:rotating_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.


  1. Install & enable the plugin
  2. Configure Stripe
  3. Configure Webhooks & Events in Stripe
  4. Add your Stripe keys (public, secret, webhook secret) under Admin > Plugin > Settings
  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

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


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

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.


  • 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

:exclamation: 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.


Please make sure your app.yml has the correct repository installed. It should be https://github.com/discourse/discourse-subscriptions


This seems counterintuitive – shouldn’t the plugin automatically remove group access upon subscription renewal failure? Just about every other subscription system does this so I’m a little confused by this.



Yes as long as Stripe is set up to cancel subscriptions after failed charges AND you have webhooks set up correctly, it will work as expected.


I think I see, so maybe this:

should be something like

Also, it’s a little confusing that the OP is owned by @rimian, especially since the plugin is now official and he’s not @team. I think it’d be better if it were owned by you, or perhaps @system as some topics are, or perhaps a @discourse user should own #official things.


I would have if I were sure that I understood. :wink:

OK. Done.

This moves this from a bug/feature problem with the plugin to a user error.

I’m hoping to have a test site using this plugin up in the next week or two. . .


The only way to do this right now is with the rake subscriptions:import task. This was built to handle an edge case after a refactor, though I’m open to additions. #pr-welcome!

Plans should be able to be deactivated in the edit screen.

Yes - it will cancel at the end of the subscription period. This is only valid for recurring items, though. If a one time purchase is refunded, group access will need manual removal.


@ajmuir @pfaffman it’s not 100% ready yet. I have some feedback to implement on the PR and have been focused on other things. Will be merged this week though!

It’s on the list!


Just a question: is there any way to sort plans belonging to the product in the presentation page /s? What is the default mode of sorting?

There isn’t a way to sort them currently. Sorting is based upon however they come back from the Stripe API, which I believe is by creation date (earliest to latest).



I’ve noticed that neither one-time payment nor the customer created have any meta data. Is that correct?

Would it be possible to add discourse_userid and discourse_username to the transaction and customer metadata so I can see them in the Stripe dashboard? That would help a lot.

Recurring payments can be viewed in Discourse admin under Plugins → Subscriptions → Subscriptions but that doesn’t include one-time payments.



Is it possible to enable a single customer to pay for multiple users, like in the traditional B2B payment setups? For example, Discourse for teams pricing is $20 / month for up to 5 members, and then $6.67 / month for each member after that.

Is there a way that I could set up the same kind of pricing structure on my forum that uses the subscriptions plugin?

No, unfortunately. This is now how the plugin was designed – its purpose is to be for users to financially support communities they’re a part of.

1 Like

That makes sense. What I’d have in mind is still a community-focused site; but one where certain businesses could have an interest in having their employees be a part of the community, so could pay for their employees’ subscriptions.

For example (hypothetical), a community devoted to discussing how-tos and education on investing, and a finance company would pay for its employees to join bc it makes them better at investing.

Do you have a sense as to how the Discourse teams pricing structure (and other B2B structures like it–basecamp, jira, asana, etc) actually works? Probably a per-seat structure with Stripe? I’m trying to wrap my head around it to see if there is something I can code directly with stripe, or if there is a bare bones (MVP) version I can still do with the plugin.

What I mean: To do this kind of pricing structure, you’d need some way to:

  1. Have a single entity pay, while also
  2. Linking users to that entity when they sign up, so the entity’s account gets charged (and the user does not need a charge). Maybe some kind of unique token the company gives to its employees? Or maybe anyone with a certain kind of company email address gets linked to the company?

You might need another plugin to fully automate it.

But you could do something to make the subscriber be the owner of a group and either hand-control who could get to the group, or auto-add to group if they were in the same email domain. Maybe you’d have a company_group_manager group that discourse_subscriptions handled and you could just let Discourse handle the money and do the other bits (create their group, add the email domain to the group config) by hand. Later, when you’re SOOOO frustrated having to create all those groups by hand, you would gladly pay $500-1000 (wild guess) to develop the plugin.

1 Like

Thanks. Yes–I was thinking something similar and that is a good idea: using the group system in Discourse, and having the paying subscriber (ie, the company) be the owner of a group, able to invite additional members.

I was thinking like you mention: I could add the company to a master group–and use the plugin to charge a monthly subscription for that. And then, either by hand or maybe using the API, make each member of the master group an owner of its own private group, able to add members (its employees) to the group.

That works well and maybe is enough if there is 1 set fee for all companies, irrespective of size (basecamp does that–$99 per year no matter how many members you have on your team). In most cases, like Discourse for Teams, Slack, etc., there is a fee that increases per user ($6.99 per user on your team).

For that, I’d need some way to increase a company’s charge depending on how many users were in their group. Any ideas?

Best I can think of right now is to, in some way perhaps with the API, check how many users are in a group on an automatic, monthly basis, and then separately bill the company through Stripe (not using the plugin in that case). I expect there’s a way to do that.

In broad strokes, I’d do it with a plugin that watched group updates and checked if the update violated the number of users (determined by the group owner’s group membership?). Something like that.


Am currently working on procourse_memberships import support. Safe to assume you would accept that PR?

Question: Looking at your subscriptions.rake example I see it hitting the Stripe API .list methods like so:

But it appears that only pulls the first “page” of data, requiring pagination to get all, e.g. Stripe Subscriptions.

Am I missing something?


I’d accept a PR — yes.

You’re probably right about the rake task and pagination of results. Plus the rake task is not currently multisite safe, so there are improvements to be had there.

1 Like