> Portal Navigation: > > - Append `.md` to any URL under `https://dev.wix.com/docs/` to get its markdown version. > - Pages are either content pages (article or reference text) or menu pages (a list of links to child pages). > - To get a menu page, truncate any URL to a parent path and append `.md` (e.g. `https://dev.wix.com/docs/sdk.md`, `https://dev.wix.com/docs/sdk/core-modules.md`). > - Top-level index of all portals: https://dev.wix.com/docs/llms.txt > - Full concatenated docs: https://dev.wix.com/docs/llms-full.txt # GetAppInstance # Package: appInstance # Namespace: AppInstanceService # Method link: https://dev.wix.com/docs/api-reference/app-management/app-instance/get-app-instance.md ## Permission Scopes: Manage Your App: SCOPE.DC.MANAGE-YOUR-APP ## Introduction Retrieves data about the instance of your app that's installed on a Wix site and data about the site itself. For example, to check whether the Wix user has installed a free or paid version of your app, or to check which apps made by Wix are installed on the site. You must authenticate this method [as a Wix app](https://dev.wix.com/docs/build-apps/develop-your-app/access/authentication/authenticate-using-oauth.md#step-2--make-an-authenticated-api-request). To retrieve `site.ownerInfo` in the response, you must have the __READ SITE OWNER EMAIL__ permission scope in addition to __MANAGE YOUR APP__. --- ## REST API ### Schema ``` Method: getAppInstance Description: Retrieves data about the instance of your app that's installed on a Wix site and data about the site itself. For example, to check whether the Wix user has installed a free or paid version of your app, or to check which apps made by Wix are installed on the site. You must authenticate this method [as a Wix app](https://dev.wix.com/docs/build-apps/develop-your-app/access/authentication/authenticate-using-oauth.md#step-2--make-an-authenticated-api-request). To retrieve `site.ownerInfo` in the response, you must have the __READ SITE OWNER EMAIL__ permission scope in addition to __MANAGE YOUR APP__. URL: https://www.wixapis.com/v1/instance Method: GET Return type: GetAppInstanceResponse - name: instance | type: AppInstance | description: Retrieved app instance. - name: instanceId | type: string | description: App instance GUID. Useful to keep track of the data that's associated with the specific instance of your app installed on a Wix site. - name: appName | type: string | description: App name, as you entered it in the App Dashboard. - name: appVersion | type: string | description: Version of your app that's installed on the Wix site. - name: isFree | type: boolean | description: Whether the Wix user has installed a free or paid version of your app on their site. - name: billing | type: BillingInfo | description: Billing information for the app instance. Available only in case `{"isFree": false}`. - name: packageName | type: string | description: Name of the package that the site owner has paid for. - name: billingCycle | type: PaymentCycle | description: Interval of the billing cycle. `ONE_TIME` indicates that the Wix user has made a single upfront payment without any automatic subscription renewal. This is primarily for usage credits (for example, 5 SMS) but may occasionally apply to a one-time setup for the app. - enum: NO_CYCLE, MONTHLY, YEARLY, ONE_TIME, TWO_YEARS, THREE_YEARS, FOUR_YEARS, FIVE_YEARS - name: timeStamp | type: string | description: Date and time the Wix user purchased the app's paid plan or began their free trial. In `YYYY-MM-DDThh:mm:ss.sssZ` format. - name: expirationDate | type: string | description: Date and time the app's current billing cycle ends in `YYYY-MM-DDThh:mm:ss.sssZ` format. Available only for yearly and multi-yearly plans. - name: autoRenewing | type: boolean | description: Whether the app's subscription automatically renews at the end of the current billing cycle. - name: invoiceId | type: string | description: GUID of the invoice for the current billing cycle. - name: source | type: string | description: Information about any discounts applied to the app instance's current billing cycle. If the site owners applied a developer coupon or Wix Voucher when installing the paid version of your app, this field holds the coupon's name or `“Wix discount coupon”`. Site owners may receive a Wix Voucher when upgrading their Wix subscription. If there is no discount for the current billing cycle, the field is an empty string. - name: freeTrialInfo | type: FreeTrialInfo | description: Information about the free trial applied, if relevant. - name: status | type: FreeTrialStatus | description: Current free trial status. - enum: - IN_PROGRESS: The free trial is currently in progress. - ENDED: The free trial has ended. - NOT_AVAILABLE: No free trial was applied, as none was available. - name: endDate | type: string | description: When the free trial has ended. Populated only once the free trial is over. - name: permissions | type: array | description: List of [permissions](https://dev.wix.com/docs/build-apps/developer-tools/developers-center/example-app-walkthrough/build-an-app.md#4-add-permissions) that the Wix user has granted your app. You set the list of permissions that your app requires from the Wix user in your app's Permissions page. - name: availablePlans | type: array | description: Plans available to this app instance. - name: packageName | type: string | description: Package name of the available plan. - name: source | type: string | description: Source of the available plan. Can be a bundle or 3rd-party app. - name: originInstanceId | type: string | description: GUID of the Wix site from which the instance of your app has been cloned. All visual settings of the Wix site and app data are duplicated during the cloning process. Wix also notifies you in case there is any additional external functionality for the original site. - name: copiedFromTemplate | type: boolean | description: Whether this app instance was created when another Wix site was cloned. - name: freeTrialAvailable | type: boolean | description: Whether this app instance includes a free trial that hasn't started yet. - name: site | type: SiteInfo | description: Information about the site. - name: siteDisplayName | type: string | description: Display name of the site. - name: locale | type: string | description: 2-letter language code of the site's locale in [ISO 639-1 alpha-2](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) format. - name: paymentCurrency | type: string | description: 3-letter currency code for the site's billing in [ISO-4217 alphabetic](https://en.wikipedia.org/wiki/ISO_4217#Active_codes) format. - name: multilingual | type: Multilingual | description: Information about the site's supported languages. - name: isMultiLingual | type: boolean | description: Whether the site supports more than a single language. - name: supportedLanguages | type: array | description: List of supported languages. Returned only when `{"isMultiLingual": true}`. - name: languageCode | type: string | description: Two-letter language code in [ISO 639-1 alpha-2](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) format. - name: locale | type: Locale | description: Locale. - name: languageCode | type: string | description: Two-letter language code in [ISO 639-1 alpha-2](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) format. - name: country | type: string | description: Two-letter country code in [ISO-3166 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements) format. - name: isPrimary | type: boolean | description: Whether the supported language is the primary language for the site. - name: countryCode | type: string | description: Language icon. - name: resolutionMethod | type: ResolutionMethod | description: How the language will be resolved. For internal use. - enum: QUERY_PARAM, SUBDOMAIN, SUBDIRECTORY - name: isVisitorPrimary | type: boolean | description: Whether the supported language is the primary language for site visitors. - name: url | type: string | description: URL of the site. Available only when the site has been published. - name: description | type: string | description: Description of the site. - name: installedWixApps | type: array | description: Apps made by Wix that are installed on the site. - name: ownerInfo | type: OwnerInfo | description: Information about the site's Wix user. Available only when calling _Get App Instance_ with the __Read Site Owner Email__ permission scope. - name: email | type: string | description: Wix user's email address. Identical to the their login email. - name: emailStatus | type: string | description: Supported values: `VERIFIED_OPT_IN`, `VERIFIED_OPT_OUT`, `NOT_VERIFIED_OPT_IN`, `NOT_VERIFIED_OPT_OUT`. Whether the Wix user has verified their email and whether they have chosen to receive email notifications from Wix. - name: siteId | type: string | description: Site GUID. - name: siteUserType | type: string | description: Type of Wix user who owns the site. Available only when calling _Get App Instance_ with the __Read Site User Type__ permission scope. Supported values: `"Channel DIY"`, `"Channel DIFM"`, `"Enterprise"`. ``` ### Examples ### GetAppInstance ```curl ~~~cURL curl -X GET \ https://www.wixapis.com/apps/v1/instance \ -H 'Authorization: ' ~~~ ``` --- ## JavaScript SDK ### Schema ``` Method: wixClientAdmin.appInstance.AppInstanceService.getAppInstance() Description: Retrieves data about the instance of your app that's installed on a Wix site and data about the site itself. For example, to check whether the Wix user has installed a free or paid version of your app, or to check which apps made by Wix are installed on the site. You must authenticate this method [as a Wix app](https://dev.wix.com/docs/build-apps/develop-your-app/access/authentication/authenticate-using-oauth.md#step-2--make-an-authenticated-api-request). To retrieve `site.ownerInfo` in the response, you must have the __READ SITE OWNER EMAIL__ permission scope in addition to __MANAGE YOUR APP__. Return type: PROMISE - name: instance | type: AppInstance | description: Retrieved app instance. - name: instanceId | type: string | description: App instance GUID. Useful to keep track of the data that's associated with the specific instance of your app installed on a Wix site. - name: appName | type: string | description: App name, as you entered it in the App Dashboard. - name: appVersion | type: string | description: Version of your app that's installed on the Wix site. - name: isFree | type: boolean | description: Whether the Wix user has installed a free or paid version of your app on their site. - name: billing | type: BillingInfo | description: Billing information for the app instance. Available only in case `{"isFree": false}`. - name: packageName | type: string | description: Name of the package that the site owner has paid for. - name: billingCycle | type: PaymentCycle | description: Interval of the billing cycle. `ONE_TIME` indicates that the Wix user has made a single upfront payment without any automatic subscription renewal. This is primarily for usage credits (for example, 5 SMS) but may occasionally apply to a one-time setup for the app. - enum: NO_CYCLE, MONTHLY, YEARLY, ONE_TIME, TWO_YEARS, THREE_YEARS, FOUR_YEARS, FIVE_YEARS - name: timeStamp | type: string | description: Date and time the Wix user purchased the app's paid plan or began their free trial. In `YYYY-MM-DDThh:mm:ss.sssZ` format. - name: expirationDate | type: string | description: Date and time the app's current billing cycle ends in `YYYY-MM-DDThh:mm:ss.sssZ` format. Available only for yearly and multi-yearly plans. - name: autoRenewing | type: boolean | description: Whether the app's subscription automatically renews at the end of the current billing cycle. - name: invoiceId | type: string | description: GUID of the invoice for the current billing cycle. - name: source | type: string | description: Information about any discounts applied to the app instance's current billing cycle. If the site owners applied a developer coupon or Wix Voucher when installing the paid version of your app, this field holds the coupon's name or `“Wix discount coupon”`. Site owners may receive a Wix Voucher when upgrading their Wix subscription. If there is no discount for the current billing cycle, the field is an empty string. - name: freeTrialInfo | type: FreeTrialInfo | description: Information about the free trial applied, if relevant. - name: status | type: FreeTrialStatus | description: Current free trial status. - enum: - IN_PROGRESS: The free trial is currently in progress. - ENDED: The free trial has ended. - NOT_AVAILABLE: No free trial was applied, as none was available. - name: endDate | type: Date | description: When the free trial has ended. Populated only once the free trial is over. - name: permissions | type: array | description: List of [permissions](https://dev.wix.com/docs/build-apps/developer-tools/developers-center/example-app-walkthrough/build-an-app.md#4-add-permissions) that the Wix user has granted your app. You set the list of permissions that your app requires from the Wix user in your app's Permissions page. - name: availablePlans | type: array | description: Plans available to this app instance. - name: packageName | type: string | description: Package name of the available plan. - name: source | type: string | description: Source of the available plan. Can be a bundle or 3rd-party app. - name: originInstanceId | type: string | description: GUID of the Wix site from which the instance of your app has been cloned. All visual settings of the Wix site and app data are duplicated during the cloning process. Wix also notifies you in case there is any additional external functionality for the original site. - name: copiedFromTemplate | type: boolean | description: Whether this app instance was created when another Wix site was cloned. - name: freeTrialAvailable | type: boolean | description: Whether this app instance includes a free trial that hasn't started yet. - name: site | type: SiteInfo | description: Information about the site. - name: siteDisplayName | type: string | description: Display name of the site. - name: locale | type: string | description: 2-letter language code of the site's locale in [ISO 639-1 alpha-2](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) format. - name: paymentCurrency | type: string | description: 3-letter currency code for the site's billing in [ISO-4217 alphabetic](https://en.wikipedia.org/wiki/ISO_4217#Active_codes) format. - name: multilingual | type: Multilingual | description: Information about the site's supported languages. - name: isMultiLingual | type: boolean | description: Whether the site supports more than a single language. - name: supportedLanguages | type: array | description: List of supported languages. Returned only when `{"isMultiLingual": true}`. - name: languageCode | type: string | description: Two-letter language code in [ISO 639-1 alpha-2](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) format. - name: locale | type: Locale | description: Locale. - name: languageCode | type: string | description: Two-letter language code in [ISO 639-1 alpha-2](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) format. - name: country | type: string | description: Two-letter country code in [ISO-3166 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements) format. - name: isPrimary | type: boolean | description: Whether the supported language is the primary language for the site. - name: countryCode | type: string | description: Language icon. - name: resolutionMethod | type: ResolutionMethod | description: How the language will be resolved. For internal use. - enum: QUERY_PARAM, SUBDOMAIN, SUBDIRECTORY - name: isVisitorPrimary | type: boolean | description: Whether the supported language is the primary language for site visitors. - name: url | type: string | description: URL of the site. Available only when the site has been published. - name: description | type: string | description: Description of the site. - name: installedWixApps | type: array | description: Apps made by Wix that are installed on the site. - name: ownerInfo | type: OwnerInfo | description: Information about the site's Wix user. Available only when calling _Get App Instance_ with the __Read Site Owner Email__ permission scope. - name: email | type: string | description: Wix user's email address. Identical to the their login email. - name: emailStatus | type: string | description: Supported values: `VERIFIED_OPT_IN`, `VERIFIED_OPT_OUT`, `NOT_VERIFIED_OPT_IN`, `NOT_VERIFIED_OPT_OUT`. Whether the Wix user has verified their email and whether they have chosen to receive email notifications from Wix. - name: siteId | type: string | description: Site GUID. - name: siteUserType | type: string | description: Type of Wix user who owns the site. Available only when calling _Get App Instance_ with the __Read Site User Type__ permission scope. Supported values: `"Channel DIY"`, `"Channel DIFM"`, `"Enterprise"`. ``` ### Examples ### getAppInstance ```javascript import { appInstances } from '@wix/app-management'; async function getAppInstance() { const response = await appInstances.getAppInstance(); }; ``` ### getAppInstance (with elevated permissions) ```javascript import { appInstances } from '@wix/app-management'; import { auth } from '@wix/essentials'; async function myGetAppInstanceMethod() { const elevatedGetAppInstance = auth.elevate(appInstances.getAppInstance); const response = await elevatedGetAppInstance(); } ``` ### getAppInstance (self-hosted) Self-hosted SDK calls require you to [create a client](https://dev.wix.com/docs/sdk/articles/work-with-the-sdk/about-the-wix-client.md). ```javascript import { createClient } from '@wix/sdk'; import { appInstances } from '@wix/app-management'; // Import the auth strategy for the relevant access type // Import the relevant host module if needed const myWixClient = createClient ({ modules: { appInstances }, // Include the auth strategy and host as relevant }); async function getAppInstance() { const response = await myWixClient.appInstances.getAppInstance(); }; ``` ---