Queries

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

NameTypeDescription

id

The id of the feature. This maps to the id field as set on the Feature object.

Returns

NameTypeDescription

data

The Feature corresponding to the id you passed.

errors / error

Returns any errors which may have occurred with the request.

Examples

Request Body

query retrieveFeature($id: String!) {
  feature(id: $id) {
    id
    name
    type
    unitLabel
    unitLabelPlural
    metadata
    packages {
      id
      name
      status
      isAddon
      updatedAt
      features {
        id
        name
        type
        limit
        unitLabel
        unitLabelPlural
        metadata
      }
      prices {
        id
        provider
        amount
        displayAmount
        currency
        interval
      }
    }
    entitlement(userId: "124") {
      access
      reason
      consumption {
        budget
        used
      }
    }
  }
}

Request Query Variables

{
  "id": "api-calls"
}

Response Body

{
  "data":{
    "feature":{
      "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-05-10T12:39:08.965Z",
          "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"
            }
          ]
        }
      ],
      "entitlement":{
        "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":{
          "budget":1000,
          "used":505,
          "overageEnabled":false
        }
      }
    }
  }
}

features

List allFeatures.

Returns

NameTypeDescription

data

An array of all features.

errors / error

Returns any errors which may have occurred with the request.

Examples

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

NameTypeDescription

featureId

The id of the feature. This maps to the id field as set on the Feature object.

userId

The id of the user. This maps to the id field as set on the User object.

delta

The amount of the consumable feature which the user will be using and you want to check access against. Defaults to 1.

Returns

NameTypeDescription

data

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

Returns any errors which may have occurred with the request.

Examples

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

NameTypeDescription

userId

The id of the user. This maps to the id field as set on the User object.

featureId

The id of the feature. This maps to the id field as set on the Feature object.

Returns

NameTypeDescription

data

An object containing details on the how many of the feature a user has used (usages) and since when (since).

errors / error

Returns any errors which may have occurred with the request.

Examples

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

NameTypeDescription

id

The id of the package. This maps to the id field as set on the Package object.

includeFeatures

SDK Only. Whether you want a features array to be present as part of the response. Defaults to false.

Returns

NameTypeDescription

data

The Package corresponding to the id you passed.

errors / error

Returns any errors which may have occurred with the request.

Examples

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

NameTypeDescription

status

includeFeatures

SDK Only. Whether you want a features array to be present as part of the response. Defaults to false.

Returns

NameTypeDescription

data

An array of all packages.

errors / error

Returns any errors which may have occurred with the request.

Examples

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

NameTypeDescription

id

The id of the user. This maps to the id field as set on the User object.

Returns

NameTypeDescription

user

The User corresponding to the id you passed.

errors / error

Returns any errors which may have occurred with the request.

Examples

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

NameTypeDescription

data

An array of all users.

errors / error

Returns any errors which may have occurred with the request.

Examples

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

NameTypeDescription

id

The id of the subscription. This maps to the id field as set on the PackageSubscription object.

Returns

NameTypeDescription

data

The PackageSubscription of a user to a package. This corresponds to the id you passed.

errors / error

Returns any errors which may have occurred with the request.

Examples

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

NameTypeDescription

userId

The id of the User whose PackageSubscriptions you want to fetch.

Returns

NameTypeDescription

data

A list of subscriptions. These could correspond to a User if a userId is passed.

errors / error

Returns any errors which may have occurred with the request.

Examples

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"
        }
      }
    ]
  }
}

Last updated