Iron Plans
Implement in-app subscriptions in 45 minutes
Get in-app subscriptions up and running with Iron Plans ASAP.

Prerequisites (5 minutes)

Switch to Test Mode before following the rest of the guide to allow the use of Stripe test cards as a payment method.

1. Create Plans

You can create up to 4 paid public plans for your customers to select from.
  • You can also create an unlimited number of private plans -- e.g. for custom offers, or pre-existing contracts.
  • Public plans can be unlisted to become private without interrupting your customers' service, and private plans can become public.
  • Every plan may have a monthly price, and/or a yearly price.
Plans are a collection of Features that you want to display to your customers. They also are the building blocks for more sophisticated pricing models.

2. Create Public & Private Tokens

Create tokens in the Iron Plans Dash.
A public token is a limited-scope token that authorizes all client-side SDK access to Iron Plans. A private token authorizes full access to your resources via API. They should only be used in a controlled environment, like a backend service.

End-to-end walkthrough (40 minutes)

This guide will show you how to get a set of subscription plans up and running in your app.
Example subscription plan set with a free tier, paid tier, and enterprise tier.

New User Flow

Step 1
A new user signs up for your service either from a sign-up button, public pricing page, or the Iron Plans public pricing page widget.
If you are using the Iron Plans public pricing page widget you can set the redirect url using the redirectUrl property.
Step 2
The new user goes through your sign up flow where you create an account and authenticate them.
Step 3
After authenticating your new user, create an Iron Plans Customer and get a Customer Token for the user by calling our server-side API. A Customer Token is an expiring JWT signed by Iron Plans that identifies and authorizes a Customer to manage their Teams, Plan, and Billing.
This call also automatically creates a subscription for new customers if a defaultPlan is set in your provider settings or if you explicitly pass a planId.
json={"customer_source_id": user_id, "customer_email": email, "plan_id": planId},
headers={"Authorization": "Bearer PROVIDER_PRIVATE_TOKEN"}
Step 4
Depending on your Iron Plans configuration and how a user signed up, 3 things can happen.
Case 1: New user signed up and no planId was passed in the customer token call.
This typically happens when a user signs up using a simple sign-up button that isn't tied to any specific plan. In this case we subscribe the new user to your defaultPlan which you set in your provider settings page. If no defaultPlan is set, your user will not be subscribed to any plan and you will need to handle how you want that to work in your app.
Case 2: New user signed up and planId was passed in the customer token call.
If a planId is passed in the customer token call, Iron Plans will attempt to create a subscription for that user to that plan. As long as the plan referenced by planId does not require a payment upfront (i.e. there is a free trial & no credit card is required to start free trials) the subscription will be created. If payment is required upfront, see case 3.
Case 3: New user signed up, planId was passed in the customer token call, but Plan requires upfront payment
This case isn't very common for SaaS offerings. Most companies implement cases 1 & 2.
This case means Iron Plans can not automatically create a subscription for your new user because the plan requires payment details. In this case you should route customers to the Plans Widget where the user can subscribe to the plan they had interest in. This plan will be highlighted for them automatically (see below).
If using the Iron Plans public pricing page widget you can also access planId via the localstorage variable ironPlansPlanId, which can be handy for multiple redirects e.g. in 3rd party auth flow.
Step 5
That's it. Go grab a beer, you earned it!

Existing User Flow

Existing users on a free plan are easy to migrate to Iron Plans. Simply follow the steps above for new user sign-ups, but apply it to your log-in flow. An Iron Plans Customer will be created for your existing users the next time they log-in and they will be assigned to your defaultPlan.
For users that are on existing paid plans, you will need to migrate them using our server-side API, or if the volume is small enough, do it in the Iron Plans Dashboard. Migration instructions can be found here or contact us for more info at [email protected]