Marketplace API Reference

App subscription

App monetization utilizes subscriptions as a billing contract between a user and an app. Each subscription contains unique data about the user’s billing frequency, plan type, and renewal period.

Queries

You can use the app_subscription query to retrieve app subscription data via the API.

  • Returns an array containing the current app and account subscription details based on the token used
  • If an account has a mock subscription and a real one, it will only return the mock subscription
  • Can only be queried directly at the root; can’t be nested within another query

This query is called on the app-level. It can only be called within the context of an app, not from the API Playground.

It only returns details based on the token used. If you want to query all of your app’s subscriptions, use the app_subscriptions object instead.

$  query {
>    app_subscription {
>      billing_period
>      days_left
>      is_trial
>      max_units
>      renewal_date
>    }
>  }
$import { ApiClient } from "@mondaydotcomorg/api";
>const mondayApiClient = new ApiClient({ token: myToken });
>
>const query = "query { app_subscription { billing_period days_left is_trial max_units renewal_date } }";
>const response = await mondayApiClient.request(query);
${ 
>  "data": {
>    "app_subscription":[
>      {
>        "billing_period": "yearly",
>        "days_left": 278,
>        "is_trial": false,
>        "max_units": 15,
>        "renewal_date": "2023-08-27T00:00:00+00:00",
>      }
>    ]
>  },
>  "account_id": 12345
>}

Fields

You can use the following fields to specify what information your app_subscription query will return.

FieldsDescription
billing_period StringThe billing period frequency: monthly or yearly.
days_left IntThe number of days left until the subscription ends.
is_trial BooleanWhether the subscription is in a trial.
max_units IntThe maximum number of seats allowed for seat-based plans. Returns null for feature-based plans.
plan_id String!The subscription plan ID from the app’s side.
pricing_version IntThe subscription’s pricing version.
renewal_date Date!The date when the subscription renews.

Mutations

Set mock app subscription

The set_mock_app_subscription mutation creates a mock subscription for an account and app based on the token you’re using. You can specify which fields to return in the mutation response.

Mock subscriptions disappear after 24 hours, and each account-app pair can create one mock subscription. You may need to refresh your browser after creating a mock subscription so that it shows in your account.

$  mutation {
>    set_mock_app_subscription(
>      app_id: 12345,
>  		partial_signing_secret: "abcde12345",
>      is_trial: true,
>      plan_id: "basic_plan_15_users",
>      max_units: 15
>    ) {
>      plan_id
>    }
>  }
$import { ApiClient } from "@mondaydotcomorg/api";
>const mondayApiClient = new ApiClient({ token: myToken });
>
>const query = `
>  mutation {
>    set_mock_app_subscription (
>      app_id: 12345,
>      partial_signing_secret: "abcde12345",
>      is_trial: true,
>      plan_id: "basic_plan_15_users",
>      max_units: 15
>    ) {
>      plan_id
>    }
>  }`;
>const response = await mondayApiClient.request(query);

Arguments

You can use the following arguments to define the mock app subscription.

ArgumentDescription
app_id ID!The app’s unique identifier. You can access this ID from the URL of your app in the following format: myaccount.monday.com/apps/manage/{YOUR_APP_ID}/app_versions/12345/sections/appDetails.
billing_period StringThe billing period frequency: monthly or yearly.
is_trial BooleanWhether the subscription is in a trial. Defaults to false.
max_units IntFor seat-based apps, the maximum number of seats allowed on the mock plan.
partial_signing_secret String!The last 10 characters of your app’s signing secret.
plan_id StringThe plan’s unique identifier for the mock subscription.
pricing_version IntThe subscription’s pricing version.
renewal_date DateThe date when the subscription renews. Defaults to one year in the future and follows UTC DateTime. *The mutation will fail if you do not use a future date.

Remove mock app subscription

The remove_mock_app_subscription mutation removes the mock subscription for the current account. You can specify which fields to return in the mutation response.

$  mutation {
>    remove_mock_app_subscription(
>      app_id: 12345
>      partial_signing_secret: "abcde12345"
>    ) {
>      billing_period
>      days_left
>      is_trial
>    }
>  }
$import { ApiClient } from "@mondaydotcomorg/api";
>const mondayApiClient = new ApiClient({ token: myToken });
>
>const query = `mutation {
>  remove_mock_app_subscription (app_id: 12345, partial_signing_secret: "abcde12345") {
>    billing_period
>    days_left
>    is_trial
> }
>}`;
>const response = await mondayApiClient.request(query);

Arguments

You can use the following arguments to specify which mock app subscription to remove.

ArgumentDescription
app_id ID!The app’s unique identifier.
partial_signing_secret String!The last 10 characters of your app’s signing secret.