Add Subscriptions to your Discourse Plugin

You can add a paid subscriptions to your plugin by using the Subscription Server and Client Plugins. A forum administrator (i.e. the end user for your plugin subscription) just needs the Subscription Client plugin installed (in addition to your plugin). The Subscription Client plugin supports multiple subscriptions from multiple providers at the same time.


There are three things you need to do to add subscriptions to your plugin.

1. Add a subscription_url to your plugin metadata

Add a subscription_url to your plugin metadata in the plugin.rb with the url of the server where you’re running the subscription server (and your payment provider)


# subscription_url:

2. Run a subscription server

You need to run a subscription server at your subscription_url with:

  • The Subscription Server plugin installed and set up (see below)
  • A supported payment provider installed and set up (e.g. Discourse Subscriptions)
Subscription Server Plugin setup

To setup the server, set the following site settings:

allow user api keys: true

allow user api key scopes: add discourse-subscription-server:user_subscription

subscription_server_subscriptions: true

subscription_server_supplier_name: This will appear in the subscription client as the “Supplier” of the subscription

subscription_server_subscriptions: A list of supported subscriptions in the format resource_name:provider_name:provider_id:domain_limit. The provider name and id will depend on how the Payment provider is implemented. For Stripe via the Discourse Subscriptions plugin use stripe and the product id of the subscription. You can get this via the stripe admin dashboard.


3. Implement the subscription client subscriptions interface in your plugin.

Finally, you need to use the subscription client subscriptions data in your plugin. You can see an example of this in the Custom Wizard plugin (below). This should be a single class that does three things

  1. Check if the Subscription Client plugin is installed and handle when it’s not
  2. Query the SubscriptionClientSubscription model for relevant subscriptions
  3. Do something with the result, e.g. restrict features.

You should then use that class throughout your plugin to implement whatever subscriber functionality scheme you want.


Send messages to your subscribers

You can send messages to subscribers via the Subscription Client plugin. Currently the only way to create a new message is on the model directly via the rails console on your subscription server. An admin interface for managing subscriber messages is on the todo list for the server plugin.

How to send a message

Invoke SubscriptionServer::Message.create with the following parameters:

  • title: title of your message
  • message: body of your message
  • type: 0 (information) or 1 (warning)
  • resource: the name of the plugin the message is about
./launcher enter app
rails c
SubscriptionServer::Message.create(title: 'This is a warning!', message: "This plugin doesn't work with the latest Discourse", type: 1, resource: 'discourse-custom-wizard')

How to expire a message

The subscription client will poll all messages on your server, so you need to expire messages that are no longer relevant.

./launcher enter app
rails c
SubscriptionServer::Message.list(“type”, 1).each(&:expire)


Can a user programmatically overcome the subscriber restrictions?

Yes. Both your plugin and the subscription client plugin are open source code operating in a highly customisable system on an environment you don’t control. There will never be a way to guarantee the end user cannot “overcome” any restrictions you create.

The question is whether you want someone willing to attempt this as a paying customer. Either they genuinely cannot afford it, in which case you may consider offering them a free subscription, or they are part of a small subset of users who have the technical knowledge and will to consistently maintain a custom override to your subscription restrictions. The latter group should not be a serious part of the business model for your plugin.