Mutations
Mutations define GraphQL operations which change data on the server. They are the primary way to take actions with your data in Kana. The majority of operations below require you to provide the fields you want returned after the mutation occurs - the same principles that apply to Queries apply here too.
At the start of every mutation operation, ensure that you specify mutation
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.
createFeature
Create a Feature.
Arguments
Name | Type | Description |
---|---|---|
input | CreateFeatureInput! | The input needed to create the feature. See Inputs for more. |
Return Fields
Name | Type | Description |
---|---|---|
data | Feature! | The Feature which was created. |
errors / error | See Errors | Returns any errors which may have occurred with the request. |
Examples
Request Body
Request Query Variables
Response JSON
updateFeature
Update a Feature.
Arguments
Name | Type | Description |
---|---|---|
input | UpdateFeatureInput! | The input needed to update the feature. See Inputs for more. |
Return Fields
Name | Type | Description |
---|---|---|
data | Feature! | The Feature which was updated. |
errors / error | See Errors | Returns any errors which may have occurred with the request. |
Examples
Request Body
Request Query Variables
Response JSON
createPackage
Create a Package.
Package Status
Your package will always have a status of DRAFT upon being created. If you want to publish this package then you will have to do so through the Dashboard.
Arguments
Name | Type | Description |
---|---|---|
input | CreatePackageInput! | The input needed to create the package. See Inputs for more. |
Return Fields
Name | Type | Description |
---|---|---|
data | Package! | The Package which was created. |
errors / error | See Errors | Returns any errors which may have occurred with the request. |
Examples
Request Body
Request Query Variables
Response JSON
updatePackage
Update a Package.
Only metadata
can be updated on the Package object through the API. All other updates will need to be done through the Dashboard. Let us know if you want to see further updatable fields and your use-cases!
Arguments
Name | Type | Description |
---|---|---|
input | UpdatePackageInput! | The input needed to update the package. See Inputs for more. |
Return Fields
Name | Type | Description |
---|---|---|
data | Package! | The Package which was updated. |
errors / error | See Errors | Returns any errors which may have occurred with the request. |
Examples
Request Body
Request Query Variables
Response JSON
createUser
Create a User.
Arguments
Name | Type | Description |
---|---|---|
input | CreateUserInput! | The input needed to create the user. See Inputs for more. |
Return Fields
Name | Type | Description |
---|---|---|
data | User! | The User which was created. |
errors / error | See Errors | Returns any errors which may have occurred with the request. |
Examples
Request Body
Request Query Variables
Response JSON
updateUser
Update a User.
How can I update the email or billingId of a user?
You will need to do this through a CSV Import within our Dashboard. We’ll soon make this possible through the API.
Arguments
Name | Type | Description |
---|---|---|
input | UpdateUserInput! | The input needed to update the user. See Inputs for more. |
Return Fields
Name | Type | Description |
---|---|---|
data | User! | The User which was updated. |
errors / error | See Errors | Returns any errors which may have occurred with the request. |
Examples
Request Body
Request Query Variables
Response JSON
subscribe
Subscribe a User to a Package - either one or multiple. Returns a PackageSubscription.
Users can only be subscribed to a Package with a status of PUBLISHED
.
Arguments
Name | Type | Description |
---|---|---|
packageIds | [String!]! | An array of id’s for the packages which the user is to be subscribed to. These are the id fields of aPackage. |
userId | String! | The identifier of the user to subscribe the package(s) to. This maps to the id field as set on the User object. |
Return Fields
Name | Type | Description |
---|---|---|
data | [Subscription]! | An array of subscriptions to the packages which the user in question has just been subscribed to. |
errors / error | See Errors | Returns any errors which may have occurred with the request. |
Examples
Request Body
Request Query Variables
Response JSON
Errors
recordUsage
Records the usage of a Feature by a User, including the amount it was used by.
Revert Usage
If you want to revert usage by a certain amount (ie. subtract rather than add from the usage of a feature), you can do so by providing a negative amount in the delta
argument (ie. -1
).
Arguments
Name | Type | Description |
---|---|---|
input | CreateUsageEventInput! | The input needed to record the usage event. See Inputs for more. |
Return Fields
Name | Type | Description |
---|---|---|
data | RecordedUsage | An object containing information on whether the usage of the feature was recorded or not (recorded boolean and reason ). |
errors / error | See Errors | Returns any errors which may have occurred with the request. |
Examples
Request Body
Request Query Variables
Response JSON
generateSubscriptionLinks
Generate a payment link which a user can navigate to in order to pay and subscribe to a Package.
A billing template (which has a price associated to it) must be created
and linked to the package you want a user to subscribe to. You can do so in
the Dashboard. You will need to provide a
valid templateId
- otherwise aSubscriptionLinkError
error will be
returned.
Upon successful payment, we will automatically receive notification of the user and the packages they have subscribed to in order to create PackageSubscriptions. You do not need to notify Kana (ie. through the subscribe mutation) yourself.
Arguments
Name | Type | Description |
---|---|---|
userId | String | The identifier of the user who will be subscribing. This maps to the id field as set on the User object. Your billing provider will otherwise create this user in Kana for you if you don’t have an identifier available. |
templateId | String! | The identifier of the billing template which is related to the package and price which you want to subscribe the user to. |
successUrl | String! | The URL which you want to redirect users to upon successful payment to subscribe. |
cancelUrl | String! | The URL which you want to redirect users to upon a cancelled payment to subscribe. |
Returns
Name | Type | Description |
---|---|---|
data | SubscriptionLink! | An object containing the generated URL (url ) which a user can navigate to in order to pay and subscribe to a package. |
errors / error | See Errors | Returns any errors which may have occurred with the request. |
Examples
Request Body
Request Query Variables
Response JSON
generateUserToken
Generates a user-specific token for the client-side Client SDK (Frontend). You can find out more in our Authorization (Frontend) guide.
Arguments
Name | Type | Description |
---|---|---|
userId | String! | The id of the User who you want to generate the token for. |
Return Fields
Name | Type | Description |
---|---|---|
data | GeneratedUserToken | An object containing the token which can be used to authenticate a user with the Client SDK. |
errors / error | See Errors | Returns any errors which may have occurred with the request. |
Examples
Request Body
Request Query Variables
Response JSON