Subscribe Users to Plans

When a user signs up to one of your plans, you’re going to want to subscribe them to the plans in Kana in order to register what plans and features they have access to.

​

Grab details on the subscription

You will need to ensure you have details on both:

• The user who has subscribed to the plan in question

• The plan which the user is being subscribed to

Namely, you will need to have an identifier which maps to the id in Kana for both Objects.

If neither the user nor plan exist yet in Kana, then you should create these first and then fetch/store the id of both:

Create Users

Create Packages

We will work on the assumption that you have pulled the following user and have all the following details to hand:

current_user = {
  "id": 123456,
  "kana_id": "123456",
  "name": "Zach Read",
  "email": "zach@usekana.com"
}

plan = {
  "name": "Extra 500 API Calls",
  "identifier": "extra-500-api-calls"
}

​

Fetch the id of the plan

You may have noticed that there’s no id for the plan in the details we have provided. We’re therefore going to need to fetch the id of the plan the user is subscribing to from Kana.

​

Send a plans query

We’ll need to first fetch all your plans from within Kana via theplans query operation. We’ll define the query string for the request to pull back the name and id of each plan, and then send the request to Kana:

plans_query = "query fetchPlans {
  plans {
    name
    id
  }
}"

plans_response = client.execute(query: plans_query)

​

Filter for the correct plan

We now have a returned list of all the plans within the workspace, which will look a bit like so:

{
  "data": {
    "plans": [
      {
        "name": "Extra 500 API Calls",
        "id": "21"
      },
      {
        "name": "Base Plan",
        "id": "20"
      }
    ]
  }
}

However, we only want to subscribe the user to the plan which they have subscribed to. We have the name of the plan to hand (as per the earlier defined plans hash) so we can filter by this when when iterating over the returned plans.

We also need to ensure that the id of the plan is captured in an array as an integer. This is what the subscribe mutation requires.

The following should do the trick:

plan_ids = plans_response['data']['plans'].filter_map do |p|
  p['id'].to_i if p['name'] == plan[:name]
end

​

Send the request to subscribe the user

Both the id of the user and the id of the plan are now accessible. We’re ready to send the request to subscribe the user to the plan.

We do this through the subscribe mutation. This requires two arguments:

1. userId - the id of the User

2. planIds - an array of integers mapping to the plan id’s

We have the identifier for the user we defined earlier, and the id of the plan now in an array as fetched from the previous step.

We’ll define these as variables to send alongside the query:

sub_variables = {
  "userId": current_user[:kana_id],
  "planIds": plan_ids
}

Next, we have to define the query string for the mutation operation which will also specify the details from the subscription object which we want to return.

In our case, we’ll return:

• The name of the plan (which helps in confirming it’s correct)

• If the plan is an add-on through the isAddon boolean

• The features associated to the plans - with their name, type and limit

This helps us in both confirming that the plan associated to the user is the correct one, and gives us details on the different features which a user has access and allowances of now they are subscribed to the plan.

sub_query = "mutation subscribeUserToPlan($planIds: [Int!]!, $userId: String!) {
  subscribe(planIds: $planIds, userId: $userId) {
    plan {
      id
      name
      isAddon
      features {
        name
        type
        limit
      }
    }
  }
}"

We can now send the request to Kana in order to subscribe the user to the plan:

sub_response \= client.execute(query: sub_query, variables: sub_variables)

Feel free to use the response you get back to store any returned fields of use to your records, log the call, or raise any errors if the call is not successful.

​

Next Steps

You’re going to want to tell us when a user has used a particular feature so that we can calculate how much of the feature they have consumed and what they have left.

Record Feature Usage

Likewise, when that user hits their limit of a particular feature, or if they haven’t subscribed to a plan with that given feature at all, you’re going to need to identify their entitlement to that feature in order to block off access and/or inform them of what they have left.

Identify a User’s Feature Entitlement