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. It only works for live apps currently in the marketplace and cannot be tested.
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
The app_subscription
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.
Field | Description |
---|---|
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 billing period frequency (monthly or yearly). |
days_left Int | The number of days left until the subscription ends. |
Sample query
query {
app_subscription {
plan_id
is_trial
billing_period
days_left
}
}
Apps monetization status
The apps_monetization
status` query checks if an account supports monetization.
Fields
The following fields will determine the data returned from your apps_monetization_status
query.
Field | Description |
---|---|
is_supported Boolean | True if the account supports app monetization. |
Sample query
query {
apps_monetization_status {
is_supported
}
}
Set mock app subscription
The set_mock_app_subscription
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
Argument | Description |
---|---|
app_id Int! | The app’s unique identifier. |
partial_signing_secret String! | The last 10 characters of your app’s signing_secret. |
is_trial Boolean | Defaults to false. |
renewal_date String | The date the subscription renews. Defaults to one year in the future and follows UTC DateTime. If you use this argument, the mutation will fail if it is not a future date. |
plan_id Int | The developer's internal ID for the plan. |
billing_period String | The billing period frequency (monthly or yearly). |
pricing_version Int | The subscription's pricing version. |
Sample query
mutation {
set_mock_app_subscription (
app_id:12345,
partial_signing_secret: "abcde12345",
is_trial: true,
plan_id: "basic_plan_15_users"
) {
plan_id
}
}
Remove mock app subscription
The remove_mock_app_subscription
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
Argument | Description |
---|---|
app_id Int! | The app's unique identifier. |
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, renews, or cancels a subscription.

-
Install: The
install
webhook containing subscription data will be sent to the user once they install an app. The data may be for a trial subscription if a user installed an app for the first time that offers a trial plan. It can also be for a paid subscription if the user reinstalls an app that they previously paid for but then uninstalled. -
Uninstall: The
uninstall
webhook containing subscription data will be sent to the app as soon as a user uninstalls an app. -
Subscription created: The
app_subscription_created
webhook containing subscription data will be sent to the developer when a user purchases a plan. -
Subscription changed: The
app_subscription_changed
webhook containing subscription data will be sent to the developer once a user upgrades or downgrades their subscription. -
Subscription renewed: The
app_subscription_renewed
webhook containing the renewed subscription information will be sent to the developer when a user's subscription renews on the renewal date. -
Subscription canceled by user: The
app_subscription_cancelled_by_user
webhook containing subscription data will be sent to the developer when a user cancels their subscription. Please note that the subscription will remain active until the paid period ends. Once the renewal date passes, their subscription will not renew and the developer will receive theapp_subscription_cancelled
webhook. -
Subscription canceled: The
app_subscription_cancelled
webhook containing subscription data will be sent to the developer when the subscription actually ends due to a cancellation. When a user churns from monday.com, the webhook will contain areason
field indicatingmonday_subscription_cancel_on_renewal
. -
Undo subscription cancellation: The
app_subscription_cancellation_revoked_by_user
webhook containing subscription data will be sent to the developer when a user undoes their subscription cancellation before the renewal date. This event signifies that the subscription will automatically renew on the renewal date. -
Trial subscription started: The
app_trial_subscription_started
webhook containing subscription data will be sent to the developer when a user starts a new app trial. -
Trial subscription ended: The
app_trial_subscription_ended
webhook containing subscription data will be sent to the developer when a user ends an app trial.
{
type: "install",
data: {
app_id: 1000000000,
user_id: 2,
user_email: "[email protected]",
user_name: "User 1",
user_cluster: "other",
account_tier: "free",
account_max_users: 10000,
account_id: 777777,
account_name: "Demo Account",
account_slug: "test",
version_data: { major: 4, minor: 5, patch: 0, type: "minor" },
timestamp: "2023-06-26T00:00:00.000+00:00",
subscription: {
plan_id: "5",
renewal_date: "2023-07-10T00:00:00+00:00",
is_trial: false,
billing_period: "monthly",
days_left: 14,
pricing_version: null
},
user_country: "IL"
}
{
type: "uninstall",
data: {
app_id: 1000000000,
user_id: 2,
user_email: "[email protected]",
user_name: "User 1",
user_cluster: "other",
account_tier: "free",
account_max_users: 10000,
account_id: 777777,
account_name: "Demo Account",
account_slug: "test",
version_data: { major: 4, minor: 5, patch: 0, type: "minor" },
timestamp: "2023-06-26T00:00:00.000+00:00",
subscription: {
plan_id: "5",
renewal_date: "2023-07-10T00:00:00+00:00",
is_trial: false,
billing_period: "monthly",
days_left: 14,
pricing_version: null
},
user_country: "IL"
}
{
"type":"app_subscription_created",
"data":{
"app_id":1000000000,
"user_id":1,
"user_email":"[email protected]",
"user_name": "User 1",
"user_cluster": 'other',
"account_tier": 'free',
"account_name": "Demo Account",
"account_slug": "test",
"account_max_users": 10000,
"account_id":777777,
"version_data":{
"major":1,
"minor":2,
"patch":0,
"type":"minor"
},
"timestamp":"2022-06-23T00:00:00.000+00:00",
"subscription":{
"plan_id":"plan1",
"renewal_date":"2022-07-19T00:00:00+00:00",
"is_trial":false,
"billing_period":"monthly",
"days_left":26,
"pricing_version":5
}
}
}
{
"type":"app_subscription_changed",
"data":{
"app_id":1000000000,
"user_id":1,
"user_email":"[email protected]",
"user_name": "User 1",
"user_cluster": 'other',
"account_tier": 'free',
"account_name": "Demo Account",
"account_slug": "test",
"account_max_users": 10000,
"account_id":777777,
"version_data":{
"major":1,
"minor":2,
"patch":0,
"type":"minor"
},
"timestamp":"2022-06-23T00:00:00.000+00:00",
"subscription":{
"plan_id":"plan1",
"renewal_date":"2022-07-19T00:00:00+00:00",
"is_trial":false,
"billing_period":"monthly",
"days_left":26,
"pricing_version":5
}
}
}
{
"type":"app_subscription_renewed",
"data":{
"app_id":1000000000,
"user_id":1,
"user_email":"[email protected]",
"user_name": "User 1",
"user_cluster": 'other',
"account_tier": 'free',
"account_name": "Demo Account",
"account_slug": "test",
"account_max_users": 10000,
"account_id":777777,
"version_data":{
"major":1,
"minor":2,
"patch":0,
"type":"minor"
},
"timestamp":"2022-06-23T00:00:00.000+00:00",
"subscription":{
"plan_id":"plan1",
"renewal_date":"2022-07-19T00:00:00+00:00",
"is_trial":false,
"billing_period":"monthly",
"days_left":26,
"pricing_version":5
}
}
}
{
"type":"app_subscription_cancelled_by_user",
"data":{
"app_id":1000000000,
"user_id":1,
"user_email":"[email protected]",
"user_name": "User 1",
"user_cluster": 'other',
"account_tier": 'free',
"account_name": "Demo Account",
"account_slug": "test",
"account_max_users": 10000,
"account_id":777777,
"version_data":{
"major":1,
"minor":2,
"patch":0,
"type":"minor"
},
"timestamp":"2022-06-23T00:00:00.000+00:00",
"subscription":{
"plan_id":"plan1",
"renewal_date":"2022-07-19T00:00:00+00:00",
"is_trial":false,
"billing_period":"monthly",
"days_left":26,
"pricing_version":5
}
}
}
{
"type":"app_subscription_cancelled",
"data":{
"app_id":1000000000,
"user_id":1,
"user_email":"[email protected]",
"user_name": "User 1",
"user_cluster": 'other',
"account_tier": 'free',
"account_name": "Demo Account",
"account_slug": "test",
"account_max_users": 10000,
"account_id":777777,
"version_data":{
"major":1,
"minor":2,
"patch":0,
"type":"minor"
},
"timestamp":"2022-06-23T00:00:00.000+00:00",
"subscription":{
"plan_id":"plan1",
"renewal_date":"2022-07-19T00:00:00+00:00",
"is_trial":false,
"billing_period":"monthly",
"days_left":26,
"pricing_version":5
},
"reason":"monday_subscription_cancel_on_renewal"
}
}
{
"type":"app_subscription_cancellation_revoked_by_user",
"data":{
"app_id":1000000000,
"user_id":1,
"user_email":"[email protected]",
"user_name": "User 1",
"user_cluster": 'other',
"account_tier": 'free',
"account_name": "Demo Account",
"account_slug": "test",
"account_max_users": 10000,
"account_id":777777,
"version_data":{
"major":1,
"minor":2,
"patch":0,
"type":"minor"
},
"timestamp":"2022-06-23T00:00:00.000+00:00",
"subscription":{
"plan_id":"plan1",
"renewal_date":"2022-07-19T00:00:00+00:00",
"is_trial":false,
"billing_period":"monthly",
"days_left":26,
"pricing_version":5
}
}
}
{
"type":"app_trial_subscription_started",
"data":{
"app_id":1000000000,
"user_id":1,
"user_email":"[email protected]",
"user_name": "User 1",
"user_cluster": 'other',
"account_tier": 'free',
"account_name": "Demo Account",
"account_slug": "test",
"account_max_users": 10000,
"account_id":777777,
"version_data":{
"major":1,
"minor":2,
"patch":0,
"type":"minor"
},
"timestamp":"2022-06-23T00:00:00.000+00:00",
"subscription":{
"plan_id":"plan1",
"renewal_date":"2022-07-19T00:00:00+00:00",
"is_trial":true,
"billing_period":"monthly",
"days_left":26,
"pricing_version":5
}
}
}
{
"type":"app_trial_subscription_ended",
"data":{
"app_id":1000000000,
"user_id":1,
"user_email":"[email protected]",
"user_name": "User 1",
"user_cluster": 'other',
"account_tier": 'free',
"account_name": "Demo Account",
"account_slug": "test",
"account_max_users": 10000,
"account_id":777777,
"version_data":{
"major":1,
"minor":2,
"patch":0,
"type":"minor"
},
"timestamp":"2022-06-23T00:00:00.000+00:00",
"subscription":{
"plan_id":"plan1",
"renewal_date":"2022-07-19T00:00:00+00:00",
"is_trial":false,
"billing_period":"monthly",
"days_left":26,
"pricing_version":5
}
}
}
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 client secret.
If your app is listed in the marketplace and monetized through us, 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_CLIENT_SECRET”);
const subscription = decoded.subscription;
})
Updated 5 days ago