Skip to content

Get customer entitlements

Once a customer is registered with Planship and subscribed to one or more Planship plans, you can check their entitlements.

const entitlements = await planship.getEntitlements(
  customer.id // customer ID
)

const entitlements: JSONValue = await planship.getEntitlements(
  customer.id // customer ID
)

entitlements = planship.get_entitlements(
    customer.id # customer ID
)

Object entitlements = planship.getEntitlements(
    customer.getId() // customer ID
)

Using Stripe?

If you use the Planship Stripe app, the customer ID is your Stripe customer ID prefixed with stripe (E.g. stripe:cus_Qv7TP2s0BZ6XAV for Stripe customer cus_Qv7TP2s0BZ6XAV).

Entitlements are returned as a dictionary containing all feature and metered entitlements for the customer according to their current subscriptions. Entitlement values for individual levers are keyed by lever slugs.

{
  'premium-button': true,
  'subscription-button-clicks': 75,
  'max-projects': 5,
  'project-types': [ 'Single', 'Random' ],
  'analytics-panel': false,
}

{
  'premium-button': true,
  'subscription-button-clicks': 75,
  'max-projects': 5,
  'project-types': [ 'Single', 'Random' ],
  'analytics-panel': false,
}

{
    "premium-button": True,
    "subscription-button-clicks": 75,
    "max-projects": 5,
    "project-types": [ "Single", "Random" ],
    "analytics-panel": False,
}

{
    subscription-button-clicks=75.0,
    max-projects=5.0,
    project-types=[Single, Random],
    premium-button=true,
    button-clicks-per-project-per-day={null=10.0},
    analytics-panel=false
}

Note

Metered lever entitlement values represent the amount of metered usage available to a customer. For instance, if a customer has a limit of 100 SMS messages per subscription period, and they've already used 25 messages in the current period, the entitlements value for the lever (subscription-sms-messages) will be 75. If you'd like to get the current usage for a customer, see getLeverUsage.

Receiving entitlements via a WebSocket connection

When using a Planship JavaScript SDK (@planship/fetch or @planship/axios) or Planship React SDK (@planship/react), you can also receive entitlements via a WebSocket connection every time they change. Simply pass your callback function to the getEntitlements call, and Planship will notify your client when it detects any change in entitlements for the customer.

function onEntitlementsChange(entitlements) {
  // process an updated entitlements object here
}

const entitlements = await planship.getEntitlements(
  customer.id, // customer ID
  onEntitlementsChange, // entitlements changed callback
)

function onEntitlementsChange(entitlements: JSONValue): void {
  // process an updated entitlements object here
}

const entitlements: JSONValue = await planship.getEntitlements(
  customer.id, // customer ID
  onEntitlementsChange, // entitlements changed callback
)

When using the Planship React SDK PlanshipCustomer provider, the callback is configured automatically to make consuming Planship entitlements in React and Next.js even simpler.

import { usePlanshipCustomer } from '@planship/react'

export default function YourComponent({ children }) {
  const { entitlements } = usePlanshipCustomer()

  return (
    // Render some content using Planship customer entitlements
  )
}

Entitlements across multiple subscriptions

If a customer belongs to multiple subscriptions, Planship will combine and calculate entitlements across all of the customer's subscriptions.

Entitlement values are calculated using an approach where the most permissive (or generous) plan entitlements take priority.