Instrumental Commerce

Instrumental Commerce from Instrumental Components is a complete Rails Stripe integration, designed for SaaS applications.

It includes all of the essential pieces to power a modern SaaS application's billing needs, including:

• A deep Stripe integration
• Subscriptions or one-time payments
• Plans and pricing page
• An optimized checkout flow
• Coupons and discounts
• Payment methods
• Customer billing portal
• Dunning (failed payments) handling
• Cancellation flow
• Admin dashboard
• and more!

When you purchase your license for Instrumental Components, you went through the checkout flow powered by Instrumental Commerce!

Pre-requisites

Before you can use Instrumental Commerce, you'll need to make sure you have:

• A Stripe account
• Installed the Authentication component
• Installed the Teams component
• Installed the Admin component

Installation overview

Installation of the Commerce component has a few steps. At a high level, these steps are:

1. Install the Commerce component
2. Get your Stripe API keys & install them in your Rails application
3. Run Stripe integration locally & receive test webhooks
4. Set up your production (and/or staging) environments' Stripe integrations
5. Create your product(s) and plan(s) in both Stripe and in your Rails application...

Let's get into it!

STEP 1: Install the Commerce component

rails g instrumental:commerce

rails db:migrate

Open the file config/initializers/stripe.rb and uncomment its contents. (Note: After uncommenting this, your app won't work until you complete the following steps to configure your Stripe keys and webhook secret)

STEP 2: Stripe API keys

In your Stripe account > Developers > API keys, you'll need to obtain your secret key and publishable key.

Save those to your Rails credentials in this format.

stripe:
      publishable_key:
      secret_key:
      webhook_secret:

STEP 3: Run Stripe integration locally

Since you'll typically be developing your app locally before deploying to production, we'll start by setting up your local environment to listen for Stripe webhooks coming from your Stripe account's "test mode".

First, make sure you have the Stripe CLI installed.

Run the following command follow the prompt to log into your Stripe account:

stripe login

Then run the following to start a local server to listen for Stripe webhooks coming from your Stripe account's "test mode":

stripe listen --forward-to localhost:3000/stripe/webhook

That will give you a webhook signing secret, which you'll need to save to the webhook_secret key in your Rails credentials for your local development environment.

Now you're up and running to build and test your Stripe integration locally! You can skip over to setting up your products & prices. Or, keep reading to set up your production (and/or staging) environments' Stripe integrations.

STEP 4: Set up your production (and/or staging) environments' Stripe integrations

Your production environment should be the one that uses your Stripe account in "live mode". If you have a staging environment, then that should use your Stripe account in "test mode".

Let's assume you're setting up your production (live mode) environment:

Get your Stripe API keys from Stripe (in live mode) > Developers > API keys. Save those to the Rails credentials for your application's production environment.

In Stripe (live mode), create a webhook with the following settings:

• Point the webhook to yourdomain.com/stripe/webhook
• Send all events

Get the webhook secret from that webhook in Stripe and save that to the webhook_secret key in your Rails credentials for your production environment.

If you have a staging environment, then do the same as above, except create the webhook in "test mode" in Stripe and save your Stripe test mode API keys and webhook secret to the Rails credentials for your staging environment.

Go deeper

Ready to dive into setting up your products, prices, plans, coupons, and more? It's all documented in these sections: