Skip to content

Subscribe customers to plans

Once a customer is successfully registered with Planship, you can subscribe them to a Planship plan by creating a new subscription for them using their ID and the slug of the desired plan.

Using Stripe?

If you use the Planship Stripe app, all of your customers and their subscriptions are automatically mirrored in Planship. You can go straight to the Getting Customer Entitlements and Reporting Usage integration guides.

Interested in the Planship Stripe app? Head to our Stripe integration HOW-TO guide to learn more.

const subscription = await planship.createSubscription(
  customer.id, // customer ID
  'medium', // plan slug
)

const subscription: SubscriptionWithPlan = await planship.createSubscription(
  customer.id, // customer ID
  'medium', // plan slug
)

subscription = planship.create_subscription(
    customer.id, # customer ID
    "medium", # plan slug
)

SubscriptionWithPlan subscription = planship.createSubscription(
    customer.getId(), // customer ID
    "medium" // plan slug
)

The returned subscription object contains a subscription id, which is required when managing and modifying subscriptions. However, unlike customer IDs, subscription IDs don't need to be persisted in your product database as you can retrieve them programatically for a customer.

Info

The customer ID can be the Planship-generated customer ID or your own ID provided to Planship as an alternative ID.

Listing customer subscriptions

To find a subscription ID, simply list all subscriptions for a given customer.

const subscriptions = await planship.listSubscriptions(
  customer.id // customer ID
)

const subscription: Array<CustomerSubscriptionWithPlan> = await planship.listSubscriptions(
  customer.id // customer ID
)

subscriptions = planship.list_subscriptions(
    customer.id # customer ID
)

List<CustomerSubscriptionWithPlan> subscriptions = planship.listSubscriptions(
    customer.getId() // customer ID
)

The return value is a list of subscription objects that contain a subscription ID, plan, renew-plan slug, the customer's role in the subscription, and more.

Change subscription plan and renew plan (upgrades and downgrades)

When a customer upgrades their plan, you may want to apply this change immediately. This can be done by changing the subscription plan.

const subscription = await planship.changeSubscriptionPlan(
  customer.id, // customer ID
  subscription.id, // existing subscription ID
  'large', // new plan slug
)

const subscription: CustomerSubscriptionWithPlan = await planship.changeSubscriptionPlan(
  customer.id, // customer ID
  subscription.id, // existing subscription ID
  'large', // new plan slug
)

subscription = planship.change_subscription_plan(
    customer.id, # customer ID
    subscription.id, # subscription ID
    "large", # new plan slug
)

CustomerSubscriptionWithPlan subscription = planship.changeSubscriptionPlan(
    customer.getId(), // customer ID string
    subscription.getId(), // subscription ID
    "large", // new plan slug
)

The same operation can be used when customers downgrade their subscriptions with an immediate effect (usually accompanied by a refund). However, downgrades are often processed at the end of a subscription period. This way, customers continue to have access to all of the product resources (like features and/or usage limits) they already paid for. To accomplish this, change the subscription's renew plan instead.

const subscription = await planship.changeSubscriptionRenewPlan(
  customer.id, // customer ID
  subscription.id, // existing subscription ID
  'large', // new renew plan slug
)

const subscription: CustomerSubscriptionWithPlan = await planship.changeSubscriptionRenewPlan(
  customer.id, // customer ID
  subscription.id, // existing subscription ID
  'large', // new renew plan slug
)

subscription = planship.change_subscription_renew_plan(
    customer.id, # customer ID
    subscription.id, # subscription ID
    "large", # new renew plan slug
)

CustomerSubscriptionWithPlan subscription = planship.changeSubscriptionRenewPlan(
    customer.getId(), // customer ID string
    subscription.getId(), // subscription ID
    "large", // new renew plan slug
)

Instead of downgrading a subscription to a different plan, you may want to cancel it completely. To do so, set the subsciptions's auto renew property to false.

const subscription = await planship.setSubscriptionAutoRenew(
  customer.id, // customer ID
  subscription.id, // existing subscription ID
  false, // set subscription auto-renew to false
)

const subscription: CustomerSubscriptionWithPlan = await planship.setSubscriptionAutoRenew(
  customer.id, // customer ID
  subscription.id, // existing subscription ID
  false, // set subscription auto-renew to false
)

subscription = planship.set_subscription_auto_renew(
    customer.id, # customer ID
    subscription.id, # subscription ID
    False, # set subscription auto-renew to false
)

CustomerSubscriptionWithPlan subscription = planship.setSubscriptionAutoRenew(
    customer.getId(), // customer ID string
    subscription.getId(), // subscription ID
    false, // set subscription auto-renew to false
)

The same call can be used to set a subscription's auto renew property to true.

Team subscriptions

Add a customer to a team subscription

If your plans support team subscriptions, instead of creating a new subscription for a customer, you may want to add them to an exisiting subscription.

const newSubscriptionCustomer = await planship.addSubscriptionCustomer(
  customer.id, // customer ID
  subscription.id, // existing subscription ID
  newCustomer.id, // new subscription customer ID
)

const newSubscriptionCustomer: SubscriptionCustomer = await planship.addSubscriptionCustomer(
  customer.id, // customer ID
  subscription.id, // existing subscription ID
  newCustomer.id, // new subscription customer ID
)

new_subscription_customer = planship.add_subscription_customer(
    customer.id, # customer ID
    subscription.id, # existing subscription ID
    new_customer.id, # new subscription customer ID
)

SubscriptionCustomer newSubscriptionCustomer = planship.addSubscriptionCustomer(
    customer.getId(), // customer ID
    subscription.getId(), // existing subscription ID
    newCustomer.getId(), // new subscription customer ID
)

Please note that this operation requires two customer IDs:

  • ID of an existing subscription customer to execute the operation, has to be an administrator of the subscription with a given ID
  • ID of a customer to be added to the subscription with a given ID

Remove a customer from a team subscription

Customers can be also removed from subscriptions they belong to.

const removedSubscriptionCustomer = await planship.removeSubscriptionCustomer(
  customer.id, // customer ID
  subscription.id, // existing subscription ID
  customerToRemove.id, // ID of a customer being removed
)

const removedSubscriptionCustomer: SubscriptionCustomerInDbBase = await planship.removeSubscriptionCustomer(
  customer.id, // customer ID
  subscription.id, // existing subscription ID
  customerToRemove.id, // ID of a customer being removed
)

removed_subscription_customer = planship.remove_subscription_customer(
    customer.id, # customer ID
    subscription.id, # existing subscription ID
    new_customer.id, # ID of a customer being removed
)

SubscriptionCustomerInDbBase removedSubscriptionCustomer =  planship.removeSubscriptionCustomer(
    customer.getId(), // customer ID
    subscription.getId(), // existing subscription ID
    customerToRemove.getId(), // ID of a customer being removed
)

Just as when adding a customer to a subscription, two customer IDs are required.

Info

Customers can remove themselves from a subscription as long as they are not the only administrator or subscriber of the subscription.