Queries - Kana

Queries define GraphQL operations which retrieve data from the server. They return only the data you specify, based on the fields which you provide in a query. If an object is returned, then you must specify the fields of that object which you want to return. The final result of the query must only return scalars.

At the start of every query operation, ensure that you specify query before the field(s).

Query Variables

We use variables throughout our example requests. We do this in order to mirror real-world application practices whereby you would most likely want dynamic values for your arguments. Take a look at this guide if you’re unfamiliar with how variables work in GraphQL.

feature

Retrieve a Feature.

Arguments

Name	Type	Description
`id`	String!	The id of the feature. This maps to the `id` field as set on the Feature object.

Returns

Name	Type	Description
`data`	Feature!	The Feature corresponding to the `id` you passed.
`errors` / `error`	See Errors	Returns any errors which may have occurred with the request.

Examples

Request/Response
cURL
Node.js

Request Body

query canUseFeature($userId: String!, $featureId: String!, $delta: Int) {
  canUseFeature(userId: $userId, featureId: $featureId, delta: $delta) {
    data {
      access
      reason
      consumption {
        budget
        used
        overageEnabled
      }
    }
  }
}

Request Query Variables

{
  "userId": "124",
  "featureId": "api-calls",
  "delta": 1
}

Response Body

{
  "data": {
    "canUseFeature": {
      "access": true,
      "reason": "The user has a subcription to a package with this consumable feature and either has an allowance remaining or overage is enabled.",
      "consumption": {
        "used": 0,
        "budget": 50,
        "overageEnabled": false
      }
    }
  }
}

features

List all Features.

Returns

Name	Type	Description
`data`	[Feature!]!	An array of all features.
`errors` / `error`	See Errors	Returns any errors which may have occurred with the request.

Examples

Request/Response
cURL
Node.js

Request Body

query listFeatures {
  features {
    id
    name
    type
    unitLabel
    unitLabelPlural
    metadata
    packages {
      id
      name
      status
      metadata
      isAddon
      updatedAt
    }
  }
}

Response Body

{
  "data": {
    "features": [
      {
        "id": "api-calls",
        "name": "API Calls",
        "type": "CONSUMABLE",
        "unitLabel": "API Call",
        "unitLabelPlural": "API Calls",
        "metadata": {},
        "packages": [
          {
            "id": "pro-plan",
            "name": "Pro Plan",
            "status": "PUBLISHED",
            "metadata": {},
            "isAddon": false,
            "updatedAt": "2022-01-21T16:08:09.640Z"
          }
        ]
      },
      {
        "id": "messages",
        "name": "Messages",
        "type": "CONSUMABLE",
        "unitLabel": "Message",
        "unitLabelPlural": "Messages",
        "metadata": {},
        "packages": [
          {
            "id": "free-plan",
            "name": "Free Plan",
            "status": "PUBLISHED",
            "metadata": {},
            "isAddon": false,
            "updatedAt": "2022-01-21T16:08:09.640Z"
          }
        ]
      }
    ]
  }
}

canUseFeature

Understand if a User is able to use a particular Feature.

The returned access boolean is true when the user has access (for Binary features), has enough of a feature remaining to be used (for Consumable features), or has overage enabled (for Consumable features).

Arguments

Name	Type	Description
`featureId`	String!	The id of the feature. This maps to the `id` field as set on the Feature object.
`userId`	String!	The id of the user. This maps to the `id` field as set on the User object.
`delta`	Int	The amount of the consumable feature which the user will be using and you want to check access against. Defaults to `1`.

Returns

Name	Type	Description
`data`	CanUseFeatureData!	An object containing details on if the user can use the feature (`access`, `reason`) and on a user’s current Consumption of the feature (`consumption`).
`errors` / `error`	See Errors	Returns any errors which may have occurred with the request.

Examples

Request/Response
cURL
Node.js

Request Body

query canUseFeature($userId: String!, $featureId: String!, $delta: Int) {
  canUseFeature(userId: $userId, featureId: $featureId, delta: $delta) {
    data {
      access
      reason
      consumption {
        budget
        used
        overageEnabled
      }
    }
  }
}

Request Query Variables

{
  "userId": "124",
  "featureId": "api-calls",
  "delta": 1
}

Response Body

{
  "data": {
    "canUseFeature": {
      "access": true,
      "reason": "The user has a subcription to a package with this consumable feature and either has an allowance remaining or overage is enabled.",
      "consumption": {
        "used": 0,
        "budget": 50,
        "overageEnabled": false
      }
    }
  }
}

showUsage

Retrieve both the current and historical usage of a Feature for a User.

Why can I only see the current usage through the SDKs?

We’re in the process of returning past usage of a feature via our SDKs. Let us know if you’d love to see it and we’ll keep you posted on when it’s launched!

Arguments

Name	Type	Description
`userId`	String!	The id of the user. This maps to the `id` field as set on the User object.
`featureId`	String!	The id of the feature. This maps to the `id` field as set on the Feature object.

Returns

Name	Type	Description
`data`	ShowUsageData!	An object containing details on the how many of the feature a user has used (`usages`) and since when (`since`).
`errors` / `error`	See Errors	Returns any errors which may have occurred with the request.

Examples

Request/Response
cURL
Node.js

Request Body

query showUsage($userId: String!, $featureId: String!) {
  showUsage(userId: $userId, featureId: $featureId) {
    current {
      periodStart
      periodEnd
      consumption {
        used
        budget
        overageEnabled
      }
    }
    past {
      periodStart
      periodEnd
      consumption {
        used
        budget
        overageEnabled
      }
    }
  }
}

Request Query Variables

{
  "userId": "124",
  "featureId": "api-calls"
}

Response Body

{
  "data": {
    "showUsage": {
      "current": {
        "periodStart": "2022-08-10T15:07:01.803Z",
        "periodEnd": "2022-09-10T15:07:01.803Z",
        "consumption": {
          "used": 0,
          "budget": 50,
          "overageEnabled": false
        }
      },
      "past": [
        {
          "periodStart": "2022-07-10T15:07:01.803Z",
          "periodEnd": "2022-08-10T15:07:01.803Z",
          "consumption": {
            "used": 48,
            "budget": 50,
            "overageEnabled": false
          }
        }
      ]
    }
  }
}

package

Retrieve a Package.

Arguments

Name	Type	Description
`id`	String!	The id of the package. This maps to the `id` field as set on the Package object.
`includeFeatures`	Boolean	SDK Only. Whether you want a `features` array to be present as part of the response. Defaults to `false`.

Returns

Name	Type	Description
`data`	Package!	The Package corresponding to the `id` you passed.
`errors` / `error`	See Errors	Returns any errors which may have occurred with the request.

Examples

Request/Response
cURL
Node.js

Request Body

query retrievePackage($id: String!) {
  package(id: $id) {
    id
    name
    status
    metadata
    features {
      id
      name
      limit
      type
      unitLabel
      unitLabelPlural
      metadata
    }
    prices {
      id
      provider
      amount
      displayAmount
      currency
      interval
    }
    isAddon
    updatedAt
  }
}

Request Query Variables

{
  "id": "pro-plan"
}

Response Body

{
  "data": {
    "package": {
      "id": "pro-plan",
      "name": "Pro Plan",
      "status": "PUBLISHED",
      "metadata": {},
      "features": [
        {
          "id": "api-calls",
          "name": "API Calls",
          "limit": "1000",
          "type": "CONSUMABLE",
          "unitLabel": "API Call",
          "unitLabelPlural": "API Calls",
          "metadata": {}
        }
      ],
      "prices": [
        {
          "id": "price_1L7NHvIiEnRX8aivoxbSWREF",
          "provider": "STRIPE",
          "amount": 5000,
          "displayAmount": "50.00",
          "currency": "gbp",
          "interval": "month"
        }
      ],
      "isAddon": false,
      "updatedAt": "2021-11-25T16:57:42.778Z"
    }
  }
}

packages

List all Packages.

Arguments

Name	Type	Description
`status`	String	The status of the package. Maps to one of the PackageStatus enum options. Defaults to `PUBLISHED`.
`includeFeatures`	Boolean	SDK Only. Whether you want a `features` array to be present as part of the response. Defaults to `false`.

Returns

Name	Type	Description
`data`	[Package!]!	An array of all packages.
`errors` / `error`	See Errors	Returns any errors which may have occurred with the request.

Examples

Request/Response
cURL
Node.js

Request Body

query listPackages($status: String!) {
  package(status: $status) {
    data {
      id
      name
      status
      metadata
      features {
        id
        name
        limit
        type
        unitLabel
        unitLabelPlural
        metadata
      }
      prices {
        id
        provider
        amount
        displayAmount
        currency
        interval
      }
      isAddon
      updatedAt
    }
  }
}

Request Query Variables

{
  "status": "PUBLISHED"
}

Response Body

{
  "data":{
    "packages":[
      {
        "id":"free-plan",
        "name":"Free Plan",
        "status":"PUBLISHED",
        "features":[
          {
            "id":"api-calls",
            "name":"API Calls",
            "limit":"1000",
            "type":"CONSUMABLE"
            "unitLabel": "API Call",
            "unitLabelPlural": "API Calls",
            "metadata": {},
          }
        ],
        "prices":[
          {
            "id": "price_1L7NHvIiEnRX8aivoxbSWREF",
            "provider": "STRIPE",
            "amount": 5000,
            "displayAmount": "50.00",
            "currency": "gbp",
            "interval": "month"
          }
        ],
        "isAddon":false,
        "updatedAt":"2021-11-25T16:57:42.778Z"
      },
      {
        "id":"premium-plan",
        "name":"Premium Plan",
        "status":"PUBLISHED",
        "features":[
          {
            "id":"api-calls",
            "name":"API Calls",
            "limit":"10000",
            "type":"CONSUMABLE"
            "unitLabel": "API Call",
            "unitLabelPlural": "API Calls",
            "metadata": {},
          }
        ],
        "prices":[
          {
            "id": "price_id_36w8sjd",
            "provider": "STRIPE",
            "amount": 10000,
            "displayAmount": "100.00",
            "currency": "gbp",
            "interval": "month"
          }
        ],
        "isAddon":false,
        "updatedAt":"2021-11-26T12:50:12.298Z"
      }
    ]
  }
}

user

Retrieve a User.

Arguments

Name	Type	Description
`id`	String!	The id of the user. This maps to the `id` field as set on the User object.

Returns

Name	Type	Description
`user`	User!	The User corresponding to the `id` you passed.
`errors` / `error`	See Errors	Returns any errors which may have occurred with the request.

Examples

Request/Response
cURL
Node.js

Request Body

query retrieveUser($id: String!) {
  user(id: $id) {
    id
    billingId
    name
    email
    metadata
  }
}

Request Query Variables

{
  "id": "124"
}

Response JSON

{
  "data": {
    "user": {
      "id": "124",
      "billingId": "cus_Lp1bSKob4laHDD",
      "name": "Test User",
      "email": "test@usekana.com",
      "metadata": {}
    }
  }
}

users

List all Users.

Returns

Name	Type	Description
`data`	[User!]!	An array of all users.
`errors` / `error`	See Errors	Returns any errors which may have occurred with the request.

Examples

Request/Response
cURL
Node.js

Request Body

query listUsers($id: String!) {
  users(id: $id) {
    id
    billingId
    name
    email
    metadata
  }
}

Response JSON

{
  "data": {
    "users": [
      {
        "id": "124",
        "billingId": "cus_Lp1bSKob4laHDD",
        "name": "Test User",
        "email": "test@usekana.com",
        "metadata": {}
      }
    ]
  }
}

subscription

Retrieve a PackageSubscription.

Arguments

Name	Type	Description
`id`	String!	The id of the subscription. This maps to the `id` field as set on the PackageSubscription object.

Returns

Name	Type	Description
`data`	PackageSubscription!	The PackageSubscription of a user to a package. This corresponds to the `id` you passed.
`errors` / `error`	See Errors	Returns any errors which may have occurred with the request.

Examples

Request/Response
cURL
Node.js

Request Body

query retrieveSubscription($id: String!) {
  subscription(id: $id) {
    id
    userId
    status
    package {
      id
      name
      status
      metadata
      features {
        id
        name
        limit
        type
        unitLabel
        unitLabelPlural
        metadata
      }
      prices {
        id
        provider
        amount
        displayAmount
        currency
        interval
      }
      isAddon
      updatedAt
    }
  }
}

Request Query Variables

{
  "id": "2"
}

Response JSON

{
  "data": {
    "subscription": {
      "id": "2",
      "userId": "124",
      "status": "ACTIVE",
      "package": {
        "id": "free-trial",
        "name": "Free Trial",
        "status": "PUBLISHED",
        "metadata": {},
        "features": [
          {
            "name": "API Calls",
            "limit": "1000",
            "type": "CONSUMABLE",
            "unitLabel": "API Call",
            "unitLabelPlural": "API Calls",
            "metadata": {}
          }
        ],
        "prices": [
          {
            "id": "price_1L7NHvIiEnRX8aivoxbSWREF",
            "provider": "STRIPE",
            "amount": 5000,
            "displayAmount": "50.00",
            "currency": "gbp",
            "interval": "month"
          }
        ],
        "isAddon": false,
        "updatedAt": "2021-11-25T16:57:42.778Z"
      }
    }
  }
}

subscriptions

List all PackageSubscriptions, or all PackageSubscriptions associated to a User.

Arguments

Name	Type	Description
`userId`	String	The id of the User whose PackageSubscriptions you want to fetch.

Returns

Name	Type	Description
`data`	[PackageSubscription!]	A list of subscriptions. These could correspond to a User if a `userId` is passed.
`errors` / `error`	See Errors	Returns any errors which may have occurred with the request.

Examples

Request/Response
cURL
Node.js

Request Body

query listSubscriptions($userId: String!) {
  subscriptions(userId: $userId) {
    id
    userId
    status
    package {
      id
      name
      status
      metadata
      features {
        id
        name
        limit
        type
        unitLabel
        unitLabelPlural
        metadata
      }
      prices {
        id
        provider
        amount
        displayAmount
        currency
        interval
      }
      isAddon
      updatedAt
    }
  }
}

Request Query Variables

{
  "userId": "124"
}

Response JSON

{
  "data": {
    "subscriptions": [
      {
        "id": "2",
        "userId": "124",
        "status": "ACTIVE",
        "package": {
          "id": "free-trial",
          "name": "Free Trial",
          "status": "PUBLISHED",
          "metadata": {},
          "features": [
            {
              "id": "api-calls",
              "name": "API Calls",
              "limit": "1000",
              "type": "CONSUMABLE",
              "unitLabel": "API Call",
              "unitLabelPlural": "API Calls",
              "metadata": {}
            }
          ],
          "prices": [
            {
              "id": "price_1L7NHvIiEnRX8aivoxbSWREF",
              "provider": "STRIPE",
              "amount": 5000,
              "displayAmount": "50.00",
              "currency": "gbp",
              "interval": "month"
            }
          ],
          "isAddon": false,
          "updatedAt": "2021-11-25T16:57:42.778Z"
        }
      },
      {
        "id": "3",
        "userId": "124",
        "status": "CANCELLED",
        "package": {
          "id": "extra-500-api-calls",
          "name": "Extra 500 API Calls",
          "status": "PUBLISHED",
          "metadata": {},
          "features": [
            {
              "id": "api-calls",
              "name": "API Calls",
              "limit": "500",
              "type": "CONSUMABLE",
              "unitLabel": "API Call",
              "unitLabelPlural": "API Calls",
              "metadata": {}
            }
          ],
          "prices": [
            {
              "id": "price_6378hdsjhshgsu4w8AJNSGL",
              "provider": "STRIPE",
              "amount": 3500,
              "displayAmount": "35.00",
              "currency": "gbp",
              "interval": null
            }
          ],
          "isAddon": true,
          "updatedAt": "2022-02-23T11:19:48.604Z"
        }
      }
    ]
  }
}

​feature

​Arguments

​Returns

​Examples

Request/Response

cURL

Node.js

Request Body

Request Query Variables

Response Body

​features

​Returns

​Examples

Request/Response

cURL

Node.js

Request Body

​canUseFeature

​Arguments

​Returns

​Examples

Request/Response

cURL

Node.js

Request Body

Request Query Variables

​showUsage

​Arguments

​Returns

​Examples

Request/Response

cURL

Node.js

Request Body

Request Query Variables

​package

​Arguments

​Returns

​Examples

Request/Response

cURL

Node.js

Request Body

Request Query Variables

​packages

​Arguments

​Returns

​Examples

Request/Response

cURL

Node.js

Request Body

Request Query Variables

​user

​Arguments

​Returns

​Examples

Request/Response

cURL

Node.js

Request Body

Request Query Variables

​users

​Returns

​Examples

Request/Response

cURL

Node.js

Request Body

​subscription

​Arguments

​Returns

​Examples

Request/Response

cURL

Node.js

Request Body

Request Query Variables

​subscriptions

​Arguments

feature

Arguments

Returns

Examples

features

Returns

Examples

canUseFeature

Arguments

Returns

Examples

showUsage

Arguments

Returns

Examples

package

Arguments

Returns

Examples

packages

Arguments

Returns

Examples

user

Arguments

Returns

Examples

users

Returns

Examples

subscription

Arguments

Returns

Examples

subscriptions

Arguments

Returns

Examples