Setting up Paddle subscriptions

Here’s how to understand and configure Paddle Billing subscriptions in Business Class.

Design

Subscriptions are implemented with Pay and primarily made to work with Paddle.

Paddle bundles all subscriptions under a single email address which is why every subscription is started and maintained with the user that started it. Inside Business Class the subscription is named after the team and managable by all teams owners.

Paddle Billing

To set up Paddle, read the Paddle developer docs and Pay’s documentation. Since everything is prepared to work out-of-the-box, you’ll only need the following Paddle configuration as part of your credentials file:

paddle:
  vendor_id: xxxx
  product_id: ppp
  api_key: yyyy
  secret_key: zzz
  environment: sandbox

Alternatively to Rails credentials, you can also set them up using environment variables:

ENV["PADDLE_VENDOR_ID"] = ""
ENV["PADDLE_PRODUCT_ID"] = ""
ENV["PADDLE_API_KEY"] = ""
ENV["PADDLE_SECRET_KEY"] = ""
ENV["PADDLE_ENVIRONMENT"] = "sandbox"

For development, you need to create a sandbox environment separated from a production account. If you don’t set Paddle environment you can still test the application using the fake subscriptions.

To update your credentials:

$ RAILS_MASTER_KEY=... bin/rails credentials:edit --environment=development

The test environment doesn’t need any credentials set, only development (with a sandbox) and production need that.

Webhooks

Once done, set up the webhook path to /pay/webhooks/paddle.

https://example.org/pay/webhooks/paddle

If you want to test webhooks locally, you can use a tool like ngrok which will give you a public address:

$ ngrok http 3000
...
Forwarding  https://406b-80-250-28-104.eu.ngrok.io -> http://localhost:3000

Then use this address and add it to the Paddle Sandbox under Developer Tools -> Notifications:

https://406b-80-250-28-104.eu.ngrok.io/pay/webhooks/paddle

Make sure it’s a primary address.

Don’t forget to remove the following condition in teams#success:

# Webhook won't arrive so let's pretend things are well
create_fake_subscription if Rails.env.development?

For a production environment you also have to approve your domain names.

Plans

After you create your plans in Paddle, it will be possible to subscribe to them as part of the create new team/space/organization flow.

Plans starts with trials which have status trialing and the attribute trial_ends_at set.
After trial is over, customer is charged and the status moves to active.
Active subscriptions can be paused and resumed both from the application or Paddle.
Active, paused, and trialing subscriptions can be cancelled. The ends_at attribute is set for subscriptions that will cancel on next billing period.

Cancelled subscriptions cannot be resumed.

Free plans

You can offer your customers a free plan.

A super user can subscribe to a free plan as well as move existing customer to a free plan from the administration area.

To enable it globally, set the ENABLE_FREE_PLAN environment variable.

Sync

Pay webhooks should ensure that subscriptions are always synced. Nevertheless, you can always run the following Rake task to synchronize subscriptions’s state:

$ rails paddle:sync