API reference

The monday apps framework has three interfaces to manage your app’s monetization:

  • monday SDK: Handles subscriptions in a frontend app
  • GraphQL API: Allows your backend to access subscription information and create mock subscriptions for testing
  • Webhooks: Sends subscription information to your backend and custom actions

SDK methods

Frontend apps can use the following methods through the monday SDK.

Open plan selection

This execute method opens the plan selection page or billing tab so users can upgrade or pay for your app.

Users can update their subscription when the tab opens by subscribing, upgrading, downgrading, or canceling. For example, users may want to use a feature not available on their plan. You can show them the billing tab so they can upgrade to the next plan tier.

If the isInPlanSelection parameter is true, the plan selection page will open. You should use this when you want the user to pay for the app first.

If the isInPlanSelection parameter is false, the app's billing section will open instead.

Code sample

monday.execute('openPlanSelection', {isInPlanSelection: true});

Session token

Every time your app loads, we will generate a session token signed with your app’s client secret. You can get this token with the method monday.get(‘sessionToken’). Your frontend should use this as the primary access to the current subscription.

You can find more information about this SDK method here.

Code sample

monday.get('sessionToken')
.then((token) => { 
  // send token to backend
  // On backend, call jwt.verify(token.data, 'MY_CLIENT_SECRET') 
}

App Context

Your app’s context contains helpful information to manage your app’s state, such as the board it’s connected to or the current user. Check out the SDK to see all of the context objects that you can return!

In the context payload, we will include the subscription information for the current account. You can access the context using the monday.get and monday.listen methods.

These methods are convenient, but you should always verify the subscription details in the session token since it is signed.

Sample context object

{
  "boardViewId": 19324,
  "boardId": 3423243,
  "mode": "fullScreen", 
  "theme": "light",
  "subscription" : {
      "plan_id" : "basic_tier_5",
      "is_trial" : false,
      "renewal_date" : "2021-08-27T00:00:00+00:00"
  }
}

GraphQL Methods

app_subscription

This query returns the subscription object for the current app and account based on the token used. This method does not accept any arguments and returns an array.

If an account has a mock subscription and a real one, it will only return the mock subscription.

Fields

The following fields will determine the data returned from your app_subscription query.

FieldDescription
plan_id [String]The subscription’s plan tier (e.g., basic)
is_trial [Boolean]True if the account is still in the trial period
renewal_date [Date]When the subscription renews
billing_period [String]The type of billing period [monthly/yearly]
days_left [Int]The number of days left until the subscription ends

 
Sample query

query {
  app_subscription {
    plan_id
    is_trial
    renewal_date
    billing_period
    days_left
  }
}

apps_monetization_status

A query to check if an account supports monetization.

Fields

The following fields will determine the data returned from your apps_monetization_status query.

FieldDescription
is_supported [Boolean]True if the account supports app monetization

 
Sample query

query {
  apps_monetization_status {
    is_supported
  }
}

set_mock_app_subscription

This mutation will create a mock subscription for an account and app based on the token you're using. It returns an app_subscription object. Mock subscriptions disappear after 24 hours, and each account-app pair can create one mock subscription.

Please note that you may need to refresh your browser after creating a mock subscription so that it shows in your account.

The mutation takes an app_id argument, which you can get from the URL of your app. Follow these steps o find your app_id:

  • Open the Developers section.
  • Click on your app.
  • The URL of the page will follow this format: myaccount.monday.com/apps/manage/{YOUR_APP_ID}/app_versions/12345/sections/appDetails

Arguments

ArgumentDescription
app_id [Int!]Your app’s unique ID (you can get this from the URL)
partial_signing_secret [String!]Last 10 characters of your app’s signing_secret
is_trial [Boolean]Defaults to false
renewal_date [String]Defaults to a year from now, UTC DateTime
plan_id [Int]The developer's internal ID for the plan

 
Sample query

mutation {
  set_mock_app_subscription (
       app_id:12345,
       partial_signing_secret: "abcde12345",
       is_trial: true,
       renewal_date:"2022-08-27Z10:00:00+00:00",
       plan_id: "basic_plan_15_users"
  ) {
    plan_id
  }
}

remove_mock_app_subscription

This query removes the mock subscription for the current account. It will return an app_subscription object or an error if no mock subscription exists.

Arguments

ArgumentDescription
app_id [Int!]The unique ID for your app
partial_signing_secret [String!]The last 10 digits of your signing secret

Webhooks

You can use the endpoint found in the webhooks section of your app's configuration screen to receive a notification when someone installs or uninstalls your app or creates, changes, or cancels a subscription.

18591859

You can find samples of the different event payloads below. Timestamps are in UTC:

{
  "type":"install",
  "data":{
    "app_id":1000000000,
    "user_id":3,
    "user_email":"[email protected]",
    "account_id":1,
    "version_data":{
      "major":1,
      "minor":2,
      "patch":0,
      "type":"minor"
    },
    "timestamp":"2022-06-28T06:48:06.643+00:00",
    "subscription":{
      "plan_id":"plan2",
      "renewal_date":"2022-07-19T00:00:00+00:00",
      "is_trial":false,
      "billing_period":"monthly",
      "days_left":21
    }
  }
}
{
  "type":"uninstall",
  "data":{
    "app_id":1000000000,
    "user_id":3,
    "user_email":"[email protected]",
    "account_id":1,
    "version_data":{
      "major":1,
      "minor":2,
      "patch":0,
      "type":"minor"
    },
    "timestamp":"2022-06-28T06:48:06.643+00:00",
    "subscription":{
      "plan_id":"plan2",
      "renewal_date":"2022-07-19T00:00:00+00:00",
      "is_trial":false,
      "billing_period":"monthly",
      "days_left":21
    }
  }
}
{
  "type":"app_subscription_created",
  "data":{
    "app_id":1000000000,
    "user_id":1,
    "user_email":"[email protected]",
    "account_id":777777,
    "version_data":{
      "major":1,
      "minor":2, 
      "patch":0,
      "type":"minor"
    },
    "timestamp":"2022-06-23T05:52:25.782+00:00",
    "subscription":{
      "plan_id":"plan1",
      "renewal_date":"2022-07-19T00:00:00+00:00",
      "is_trial":false,
      "billing_period":"monthly",
      "days_left":26
    }
  }
}
{
  "type":"app_subscription_cancelled_by_user",
  "data":{
    "app_id":1000000000,
    "user_id":1,
    "user_email":"[email protected]",
    "account_id":777777,
    "version_data":{
      "major":1,
      "minor":2,
      "patch":0,
      "type":"minor"
    },
    "timestamp":"2022-06-23T06:05:44.294+00:00",
    "subscription":{
      "plan_id":"plan1",
      "renewal_date":"2022-07-19T00:00:00+00:00",
      "is_trial":false,
      "billing_period":"monthly",
      "days_left":26
    }
  }
}
{
  "type":"app_subscription_changed",
  "data":{
    "app_id":1000000000,
    "user_id":1,
    "user_email":"[email protected]",
    "account_id":777777,
    "version_data":{
      "major":1,
      "minor":2,
      "patch":0,
      "type":"minor"
    },
    "timestamp":"2022-06-23T05:52:25.782+00:00",
    "subscription":{
      "plan_id":"plan1",
      "renewal_date":"2022-07-19T00:00:00+00:00",
      "is_trial":false,
      "billing_period":"monthly",
      "days_left":26
    }
  }
}

We also expose subscription information in webhooks from monday to your app. In each case, the subscription is encoded in the Authorization header of the request as a JWT. This JWT is signed with your app’s signing secret.

We will include the subscription information in three webhooks:

  • Install webhook
  • Custom action webhook
  • Uninstall webhook

Code sample

app.post("/action", function(req, res) {
    res.status(200).send({})
    const token = req.headers.authorization;
    const decoded = jwt.verify(token, “MY_SIGNING_SECRET”);
    const subscription = decoded.subscription;
})