Getting started

Step 1: Define your product plans, levers, and entitlements

To get started, sign into the Planship Console. If you don't have a Planship account yet, sign up now.

In the console, you'll do the following:

Create a product that corresponds to your software product
Create feature and/or metered levers that map to the pricing dimensions of your product.
Create plans that map to your recurring subscription plans, one-off packages, add-ons, etc.
Apply pricing levers to individual plans by defining entitlements.

Want guidance?

If you're new to Planship, you can follow our Planship Console walkthrough HOWTO guide for a step-by-step guide on creating products, plans, levers, and entitlements.

Plans view of the Planship app showing a list of plans along with the details of the selected plan named 'Personal' — Defining plans and entitlements in the Planship Console

Step 2: Integrate Planship into your product code

With your levers, plans, and entitlements defined in Planship, it's time to integrate your product with the Planship API to do the following:

Authentication and security

The Planship API uses token-based authentication where access tokens are obtained via an OAuth2 Client Credentials flow. The credentials consist of a client ID and secret pair that is exchanged for a token that grants access to the resources within an organization. Client ID and secret pairs are managed on the organization level by organization admins and collaborators. You can find them in the Planship console under your organization.

Info

Since Planship API calls are authenticated by tokens rather than API keys, Planship can be securly integrated into your client-side code (E.g. browser) without compromising application secrets.

Getting started with Planship SDKs

To get started, add a Planship SDK to your project. There are SDKs for JavaScript, Python, and Java, with more languages in the works. Let us know if there's something you'd like to see.

Tip

If the language or platform you use isn't currently supported by any of our SDKs, or you would rather build your own library, you can generate a Planship API client from our OpenAPI spec using a generator like openapi-generator.

JavaScript FetchJavaScript AxiosPythonJavaReact

The Planship fetch client is part of the planship-js SDK codebase hosted at https://github.com/planship/planship-js and published to NPM as @planship/fetch.

Using pnpm:

pnpm install @planship/fetch

Using yarn:

yarn add @planship/fetch

The Planship Axios client is part of the planship-js SDK codebase hosted at https://github.com/planship/planship-js and published to NPM as @planship/fetch.

Using pnpm:

pnpm install @planship/axios

Using yarn:

yarn add @planship/axios

The Planship Python SDK code is hosted at https://github.com/planship/planship-python and published to PyPi at https://pypi.org/project/planship/.

pip install planship

The Planship Java SDK code is hosted at https://github.com/planship/planship-java and available from Maven Central at https://pypi.org/project/planship/.

Maven users

Add this dependency to your project's POM:

<dependency>
  <groupId>io.planship</groupId>
  <artifactId>planship-java</artifactId>
  <version>0.2.0</version>
  <scope>compile</scope>
</dependency>

Gradle users

Add this dependency to your project's build file:

  repositories {
    mavenCentral()     // Needed if the 'planship-java' jar has been published to maven central.
    mavenLocal()       // Needed if the 'planship-java' jar has been published to the local maven repo.
  }

  dependencies {
    implementation "org.planship:planship-java:0.1.0"
  }

The Planship client-side SDK for React uses the React Context API to make consuming Planship data and functionality in React and Next.js apps easier. The React SDK code is hosted at https://github.com/planship/planship-react and published to NPM as @planship/react.

Using pnpm:

pnpm install @planship/react

Using yarn:

yarn add @planship/react

Then, import and initialize it:

JavaScript FetchJavaScript AxiosPythonJavaReact

import { Planship } from '@planship/fetch'

const planship = new Planship(
  'clicker-demo', // your Planship product slug
  {
    clientId: '273N1SQ3GQFZ8JSFKIOK', // Planship API client ID
    clientSecret: 'GDSfzPD2NEM5PEzIl1JoXFRJNZm3uAhX' // Planship API client secret
  }
)

Client-side (browser) code

In client code, the use of application secrets like your Planship API client secret should be avoided at all times. Instead, you should retrieve a Planship access token from the server using your existing application API, and pass the token to the Planship client class constructor via an asynchronous getter function.

const planship = new Planship(
  'clicker-demo', // your Planship product slug
  getAccessToken // function that returns a Promise that resolves with a valid Planship access token
)

To obtain the token on the server side, call the getAccessToken method on the server-side Planship client instance:

const accessToken = await planship.getAccessToken()

import { Planship } from '@planship/axios'

const planship = new Planship(
  'clicker-demo',   // your Planship product slug
  {
    clientId: '273N1SQ3GQFZ8JSFKIOK', // Planship API client ID
    clientSecret: 'GDSfzPD2NEM5PEzIl1JoXFRJNZm3uAhX' // Planship API client secret
  }
)

Client-side (browser) code

In client code, the use of application secrets like your Planship API client secret should be avoided at all times. Instead, you should retrieve a Planship access token from the server using your existing application API, and pass the token to the Planship client class constructor via an asynchronous getter function.

const planship = new Planship(
  'clicker-demo', // your Planship product slug
  getAccessToken // function that returns a Promise that resolves with a valid Planship access token
)

To obtain the token on the server side, call the getAccessToken method on the server-side Planship client instance:

const accessToken = await planship.getAccessToken()

from planship import Planship

planship = Planship(
    "clicker-demo", # your Planship product slug
    "https://api.planship.io", # Planship API endpoint URL
    "273N1SQ3GQFZ8JSFKIOK", # Planship API client ID
    "GDSfzPD2NEM5PEzIl1JoXFRJNZm3uAhX" # Planship API client secret
)

import io.planship;

Planship planship = new Planship(
    "clicker-demo", // your Planship product slug
    "https://api.planship.io", // Planship API endpoint URL
    "273N1SQ3GQFZ8JSFKIOK", //Planship API client ID
    "GDSfzPD2NEM5PEzIl1JoXFRJNZm3uAhX" // Planship API client secret
)

Import and call withPlanshipProvider to create a Planship context provider and wrap your components with it.

import { withPlanshipProvider } from '@planship/react'

function App() {
  const PlanshipProvider = withPlanshipProvider(
    {
      slug: 'clicker-demo', // your Planship product slug
      getAccessToken: getAccessToken, // function that returns a valid Planship token
    }
  )

  return (
    <PlanshipProvider>
      <Page />
    </PlanshipProvider>
  )
}

Then, import and call usePlanship inside your components to access the Planship API client.

import { usePlanship } from '@planship/react'

export default function YourComponent({ children }) {
  const { planship } = usePlanship()

  useEffect(() => {
    // use planship API instance to call the Planship API
  }, [])

  return (
    // Render your component using data retrieved from the Planship API
  )
}