Iron Plans
Search…
JavaScript SDK

Installation

GitHub - ironplans/js: Iron Plans JS/TS Monorepo
GitHub
npm, yarn
1
yarn add @ironplans/sdk
Copied!
1
npm i @ironplans/sdk
Copied!
CDN
ES6 Modules (Asynchronous)
1
<link
2
rel="modulepreload"
3
href="https://unpkg.com/@ironplans/sdk/dist/sdk.esm.js">
4
<script type="module">
5
6
import { Customer } from "https://unpkg.com/@ironplans/sdk/dist/sdk.esm.js"
7
// ...
8
9
</script>
Copied!
Classic Bundle (Synchronous)
1
<script src="https://unpkg.com/@ironplans/sdk/dist/sdk.min.js"></script>
2
<script>
3
var customerToken = ...
4
var customer = new IP.Customer({token: customerToken})
5
customer.onInitialized((c)=>{console.log(`Hi ${c.id}`)})
6
customer.init()
7
</script>
Copied!

Versions

Our open source packages are released automatically with the release tag next if you want to live on the edge, e.g. npm i @ironplans/[email protected]

Github repo

Dive right into the source code of the JS SDK here:

Customers

See the Quick start or Create customer tokens to understand what customer tokens are and how to create them.
1
import { Customer } from "https://unpkg.com/@ironplans/browser/dist/index.mjs"
Copied!

Options

1
export interface CustomerOptions {
2
/**
3
* An OIDC-compliant ID token for a customer. This token will be exchanged for
4
* a customer access token and automatically create the customer if they do
5
* not yet exist.
6
*/
7
idToken?: string
8
9
/** A customer access token. Omit if you're using `idToken`. */
10
token?: string
11
12
/** A Provider public token. */
13
publicToken?: string
14
15
/** ID of the Team the Customer should default to using. */
16
teamId?: string
17
18
/** The API base URL for Iron Plans customers. */
19
apiBaseUrl?: string
20
21
/** The base URL to use for embedded views. */
22
appBaseUrl?: string
23
24
ui?: {
25
/** zIndex to use for embedded views. */
26
zIndex?: number
27
}
28
29
/** The amount of milliseconds to wait before timing out an API request. */
30
timeout?: number
31
}
Copied!

Identify customers

Using the customer token you created earlier, initialize a Customer client-side as early in the page's lifecycle as possible:
1
const config = {
2
// either: 1st-party auth
3
token,
4
// or: 3rd-party auth
5
publicToken,
6
idToken,
7
}
8
9
// Top-level await:
10
const customer = await Customer.init(config)
11
12
// Or, deferred:
13
const customer = new Customer()
14
// ...
15
await customer.init(config)
Copied!

Plans

1
const plansDiv = document.querySelector('#plans-div')
2
3
const theme = {
4
base: {
5
customFont: 'JetBrains Mono',
6
colors: {
7
primary: '#FBD2D7',
8
},
9
fontFamily: 'JetBrains Mono, sans-serif',
10
darkMode: 'off',
11
}
12
}
13
14
customer.getTeam().showWidget('v2/plans', theme, plansDiv)
Copied!
Every customer belongs to a team. The team chooses from the plans you designed.
Plans UI widget w/custom theme
team.showPlans() can either be shown as a modal, or you can pass a DOM Element or query selector and the library will find that element and insert a transparent iframe as a child of the target.
You can also brand the cards by passing in a custom themes Theme object.

Getting a customer's plan

Once the customer confirms payment, their team is subscribed to that plan and will automatically renew at the configured interval. The subscription and the plan information is available on the Team object, team.subscription .

Teams

Display a customer's team

The easiest way to give your customers team management capabilities is to embed the teams UI widget in your app. The UI widget lets your customers see their teams, create teams, update their teams, and invite team members.
1
customer.getTeam().showWidget('team', theme, teamsDiv)
Copied!
Team UI widget w/custom theme
If you don't want to use the UI widget, you can use all the team methods directly to build your own experience. The widgets themselves are built using the same SDK!
1
// get all teams for a customer
2
const teams = await customer.fetchTeams()
3
4
// get info for a specific team
5
const teamInfo = await customer.fetchTeamInfo(teamId: string)
6
7
// create a new team
8
const team = await customer.createTeam(team: TeamDetailRequest)
9
10
// invite a team member to a team
11
team.invite(email: string)
Copied!

Billing

Display all invoices for a team

1
customer.getTeam().showWidget('invoices', theme, invoicesDiv)
Copied!
Invoices UI widget w/custom theme

Display a customer's payment method

1
customer.getTeam().showWidget('payment_methods', theme, paymentMethodContainer)
Copied!
Payment UI widget