Skip to content
flintDocs

Partner app installs

Partner app installs are the partner apps a merchant has connected to its Flint account. Use these routes as the merchant to see which apps can reach its data and to disconnect one. Both routes cover live and test mode, so they need a live API key: test keys get 403 FORBIDDEN with details[0].reason live_mode_required, and partner install tokens get 401 INVALID_CREDENTIAL with details[0].reason wrong_credential_type.

Note:

Building the app instead? The Partner app installs guide covers installing, the events your app receives when a merchant disconnects, and the app owner's install routes under Partner apps.

List installed apps#

GET /v1/partner-app-installs with developer.partner_apps.read lists the selected merchant's installs across all apps, including each install's environment grants. It includes revoked installs unless you filter them out, and never returns other merchants' installs, even for an app you own.

cURL
curl "https://api.withflintpay.com/v1/partner-app-installs?status=active" \
  -H "Authorization: Bearer $FLINT_API_KEY"

Filter with partner_app_id, and with status (pending_exchange, active, revoked). Repeat status or separate values with commas to match more than one. A page_token only works with the filters it was issued for.

Each install has the app's partner_app_id and current partner_app_name, its status, and revoked_by (merchant or partner_app) when known. Each environment grant lists granted_permissions, the app's permissions it holds with their titles, descriptions, and scopes, and granted_scopes, the Flint API scopes the app can use in that mode.

GET /v1/developer/partner/installs returns the same list and also accepts an onboarding session.

Disconnect an app#

POST /v1/partner-app-installs/{partner_app_install_id}/revoke with developer.partner_apps.write disconnects the app. Flint revokes the install, its environment grants, and its refresh tokens, so the app's access tokens stop working and it stops receiving events for this merchant. The app is sent partner_app_install.revoked with revoked_by merchant.

cURL
curl -X POST https://api.withflintpay.com/v1/partner-app-installs/pinst_123/revoke \
  -H "Authorization: Bearer $FLINT_API_KEY"

Revoking a revoked install returns it unchanged. Another merchant's install returns 404 PARTNER_APP_INSTALL_NOT_FOUND. To reconnect, install the app again from the app's install link.

List installed partner apps#

GET/v1/developer/partner/installs

Requires scope developer.partner_apps.read or developer.partner_apps.write

Lists partner app installs on the authenticated merchant, across live and test mode. Requires a live API key.

Query parameters

page_sizeinteger

Page size, default 20, max 100.

page_tokenstring

Cursor returned by the previous list response.

partner_app_idstring

Filter by app ID.

statusarray of enum

Filter by install status. Accepts repeated keys, comma-separated values, or mixtures. Values are trimmed and deduplicated in first-seen order; empty or unknown entries are rejected. Values within this filter are ORed; separate filters are ANDed.

  • pending_exchange
  • active
  • revoked

Response · 200

dataarray of objectRequired
metaobject

Metadata returned with a response: the `api_version`, `trace_id`, whether an idempotent request was replayed, and any warnings.

next_page_tokenstring
request_idstring
curl https://api.withflintpay.com/v1/developer/partner/installs \
  -H "Flint-Version: 2026-09-07" \
  -H "Authorization: Bearer YOUR_API_KEY"
JSON
{
  "data": [
    {
      "created_at": "2026-03-18T20:05:00Z",
      "environment_grants": [
        {
          "created_at": "2026-03-18T20:05:00Z",
          "environment_grant_id": "egrt_01JQPARTNERGRANTTEST123456",
          "granted_permissions": [
            {
              "description": "Read and update Flint orders for installed merchants.",
              "permission_id": "manage_orders",
              "required_scopes": [
                "commerce.orders.read",
                "commerce.orders.write"
              ],
              "title": "Manage orders"
            },
            {
              "description": "Read product, variant, bundle, and SKU lookup catalog records.",
              "optional": true,
              "permission_id": "read_catalog",
              "required_scopes": [
                "commerce.products.read",
                "commerce.bundles.read",
                "commerce.catalog.read"
              ],
              "title": "Read catalog"
            }
          ],
          "granted_scopes": [
            "commerce.orders.read",
            "commerce.orders.write",
            "commerce.products.read",
            "commerce.bundles.read",
            "commerce.catalog.read"
          ],
          "mode": "test",
          "sandbox_id": "test_01KEZF7C00EWKVN1WYFT3YJSS5",
          "status": "active",
          "updated_at": "2026-03-18T20:05:00Z"
        },
        {
          "created_at": "2026-03-18T20:06:00Z",
          "environment_grant_id": "egrt_01KEZF7C00YSFNZQ5GTQT0EEQW",
          "granted_permissions": [
            {
              "description": "Read and update Flint orders for installed merchants.",
              "permission_id": "manage_orders",
              "required_scopes": [
                "commerce.orders.read",
                "commerce.orders.write"
              ],
              "title": "Manage orders"
            },
            {
              "description": "Read product, variant, bundle, and SKU lookup catalog records.",
              "optional": true,
              "permission_id": "read_catalog",
              "required_scopes": [
                "commerce.products.read",
                "commerce.bundles.read",
                "commerce.catalog.read"
              ],
              "title": "Read catalog"
            }
          ],
          "granted_scopes": [
            "commerce.orders.read",
            "commerce.orders.write",
            "commerce.products.read",
            "commerce.bundles.read",
            "commerce.catalog.read"
          ],
          "mode": "live",
          "status": "active",
          "updated_at": "2026-03-18T20:06:00Z"
        }
      ],
      "installed_by_user_id": "usr_01KEZF7C00NQEV558W0ESKV30S",
      "merchant_id": "mer_01KEZF7C00MPP0T9S0KH5BB4CC",
      "partner_app_id": "papp_01KEZF7C00CRN13BTTQVZ1CEWS",
      "partner_app_install_id": "pinst_01KEZF7C00V5TD9V9QS2PK2VEE",
      "partner_app_name": "Acme Commerce Plugin",
      "status": "active",
      "updated_at": "2026-03-18T20:06:00Z"
    }
  ],
  "next_page_token": "example",
  "request_id": "req_01KWM6JY3QVFM8KDF0537N33SC"
}

List installed partner apps#

GET/v1/partner-app-installs

Requires scope developer.partner_apps.read or developer.partner_apps.write

Lists partner app installs on the authenticated merchant, across live and test mode. Requires a live API key.

Query parameters

page_sizeinteger

Page size, default 20, max 100.

page_tokenstring

Cursor returned by the previous list response.

partner_app_idstring

Filter by app ID.

statusarray of enum

Filter by install status. Accepts repeated keys, comma-separated values, or mixtures. Values are trimmed and deduplicated in first-seen order; empty or unknown entries are rejected. Values within this filter are ORed; separate filters are ANDed.

  • pending_exchange
  • active
  • revoked

Response · 200

Same response as List installed partner apps.

curl https://api.withflintpay.com/v1/partner-app-installs \
  -H "Flint-Version: 2026-09-07" \
  -H "Authorization: Bearer YOUR_API_KEY"
JSON
{
  "data": [
    {
      "created_at": "2026-03-18T20:05:00Z",
      "environment_grants": [
        {
          "created_at": "2026-03-18T20:05:00Z",
          "environment_grant_id": "egrt_01JQPARTNERGRANTTEST123456",
          "granted_permissions": [
            {
              "description": "Read and update Flint orders for installed merchants.",
              "permission_id": "manage_orders",
              "required_scopes": [
                "commerce.orders.read",
                "commerce.orders.write"
              ],
              "title": "Manage orders"
            },
            {
              "description": "Read product, variant, bundle, and SKU lookup catalog records.",
              "optional": true,
              "permission_id": "read_catalog",
              "required_scopes": [
                "commerce.products.read",
                "commerce.bundles.read",
                "commerce.catalog.read"
              ],
              "title": "Read catalog"
            }
          ],
          "granted_scopes": [
            "commerce.orders.read",
            "commerce.orders.write",
            "commerce.products.read",
            "commerce.bundles.read",
            "commerce.catalog.read"
          ],
          "mode": "test",
          "sandbox_id": "test_01KEZF7C00EWKVN1WYFT3YJSS5",
          "status": "active",
          "updated_at": "2026-03-18T20:05:00Z"
        },
        {
          "created_at": "2026-03-18T20:06:00Z",
          "environment_grant_id": "egrt_01KEZF7C00YSFNZQ5GTQT0EEQW",
          "granted_permissions": [
            {
              "description": "Read and update Flint orders for installed merchants.",
              "permission_id": "manage_orders",
              "required_scopes": [
                "commerce.orders.read",
                "commerce.orders.write"
              ],
              "title": "Manage orders"
            },
            {
              "description": "Read product, variant, bundle, and SKU lookup catalog records.",
              "optional": true,
              "permission_id": "read_catalog",
              "required_scopes": [
                "commerce.products.read",
                "commerce.bundles.read",
                "commerce.catalog.read"
              ],
              "title": "Read catalog"
            }
          ],
          "granted_scopes": [
            "commerce.orders.read",
            "commerce.orders.write",
            "commerce.products.read",
            "commerce.bundles.read",
            "commerce.catalog.read"
          ],
          "mode": "live",
          "status": "active",
          "updated_at": "2026-03-18T20:06:00Z"
        }
      ],
      "installed_by_user_id": "usr_01KEZF7C00NQEV558W0ESKV30S",
      "merchant_id": "mer_01KEZF7C00MPP0T9S0KH5BB4CC",
      "partner_app_id": "papp_01KEZF7C00CRN13BTTQVZ1CEWS",
      "partner_app_install_id": "pinst_01KEZF7C00V5TD9V9QS2PK2VEE",
      "partner_app_name": "Acme Commerce Plugin",
      "status": "active",
      "updated_at": "2026-03-18T20:06:00Z"
    }
  ],
  "next_page_token": "example",
  "request_id": "req_01KWM6JY3QVFM8KDF0537N33SC"
}

Remove connected partner app#

POST/v1/partner-app-installs/{partner_app_install_id}/revokeIdempotent

Requires scope developer.partner_apps.write

Disconnects a partner app from the authenticated merchant: revokes the install, its environment grants and its refresh tokens. The app is sent partner_app_install.revoked with revoked_by: merchant. Revoking a revoked install returns it unchanged. To reconnect, install the app again.

Path parameters

partner_app_install_idstringRequired

Flint partner app install ID.

Response · 200

dataobjectRequired

A merchant's authorization of a partner application.

metaobject

Metadata returned with a response: the `api_version`, `trace_id`, whether an idempotent request was replayed, and any warnings.

request_idstring
curl -X POST https://api.withflintpay.com/v1/partner-app-installs/pinst_01KEZF7C00V5TD9V9QS2PK2VEE/revoke \
  -H "Flint-Version: 2026-09-07" \
  -H "Authorization: Bearer YOUR_API_KEY"

Was this helpful?