Skip to content
flintDocs

Partner apps

Partner apps are installable integrations that Flint merchants connect to your product. The surface has three parts: register and manage the app, send merchants through the hosted OAuth install flow, and exchange the returned authorization code for install access tokens scoped to that merchant.

An app declares a permission manifest (named permission groups that map to Flint API scopes), and merchants review and approve those permissions during install. Each install records per-environment grants you can inspect and revoke individually or all at once. The app's client_secret is returned only at creation and rotation, and a partner app can register its own webhook endpoint to receive install lifecycle events.

Note:

The Partner app installs guide covers the end-to-end flow from registration through token exchange. For a merchant's own webhook endpoints on regular resources, see the webhooks reference instead.

Merchant install access#

Call GET /v1/developer/partner/installs with developer.partner_apps.read to list the apps installed by your selected merchant, including each install's environment grants. The list includes revoked installs. It does not include other merchants' installs, even if you own the app.

cURL
curl https://api.withflintpay.com/v1/developer/partner/installs \
  -H "Authorization: Bearer $FLINT_API_KEY"

Use the returned partner_app_id and partner_app_install_id with GET /v1/developer/partner/apps/{partner_app_id}/installs/{partner_app_install_id} to inspect one install. The installing merchant and the app owner can both read it.

The installing merchant or app owner can call POST /v1/developer/partner/apps/{partner_app_id}/installs/{partner_app_install_id}/revoke to revoke the install and all its environment grants, or POST /v1/developer/partner/apps/{partner_app_id}/installs/{partner_app_install_id}/environment-grants/{environment_grant_id}/revoke to revoke one environment. These writes require a live external API key with developer.partner_apps.write. Revocation invalidates the affected access and refresh tokens and stops installed-merchant events authorized by those grants. It leaves the app owner's settings unchanged.

List partner apps#

GET/v1/developer/partner/apps

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

Returns partner apps owned by the authenticated merchant.

Query parameters

page_sizeinteger

Page size, default 20, max 100.

page_tokenstring

Cursor returned by the previous list response.

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/apps \
  -H "Flint-Version: 2026-09-07" \
  -H "Authorization: Bearer YOUR_API_KEY"
JSON
{
  "data": [
    {
      "allowed_scopes": [
        "commerce.bundles.read",
        "commerce.bundles.write",
        "commerce.catalog.read",
        "commerce.orders.read",
        "commerce.orders.write",
        "commerce.products.read",
        "customers.read",
        "customers.write"
      ],
      "api_version": "2026-09-07",
      "app_type": "plugin",
      "client_id": "fpc_1234567890abcdef1234567890abcd",
      "created_at": "2026-03-18T20:00:00Z",
      "default_requested_permissions": [
        "manage_orders"
      ],
      "name": "Acme Commerce Plugin",
      "partner_app_id": "papp_01KEZF7C00D8DXK5AXR7NPRJ0J",
      "permission_manifest": [
        {
          "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 and update customer records for installed merchants.",
          "optional": true,
          "permission_id": "manage_customers",
          "required_scopes": [
            "customers.read",
            "customers.write"
          ],
          "title": "Manage customers"
        },
        {
          "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"
        },
        {
          "description": "Create and update bundle catalog records for installed merchants.",
          "optional": true,
          "permission_id": "manage_bundles",
          "required_scopes": [
            "commerce.bundles.write"
          ],
          "title": "Manage bundles"
        }
      ],
      "redirect_uris": [
        "https://plugins.acme.com/flint/oauth/callback",
        "http://localhost:3000/flint/oauth/callback"
      ],
      "status": "active",
      "updated_at": "2026-03-18T20:00:00Z",
      "visibility": "private"
    }
  ],
  "next_page_token": "example",
  "request_id": "req_01KWM6Q3QX3V637MC657MCTF86"
}

Create partner app#

POST/v1/developer/partner/appsIdempotent

Requires scope developer.partner_apps.write

Creates a partner app owned by the authenticated merchant. Use a developer setup session during setup or a normal external API key afterward.

Request body

api_versionstring
app_typeenum
  • server
  • plugin
default_requested_permissionsarray of string
namestringRequired
permission_manifestarray of objectRequired
redirect_urisarray of stringRequired
visibilitystring

Response · 201

dataobjectRequired

A partner app returned with its client secret, as in the response to creating a partner app.

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/developer/partner/apps \
  -H "Flint-Version: 2026-09-07" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{
    "app_type": "plugin",
    "default_requested_permissions": [
      "manage_orders"
    ],
    "name": "Acme Commerce Plugin",
    "permission_manifest": [
      {
        "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 and update customer records for installed merchants.",
        "optional": true,
        "permission_id": "manage_customers",
        "required_scopes": [
          "customers.read",
          "customers.write"
        ],
        "title": "Manage customers"
      },
      {
        "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"
      },
      {
        "description": "Create and update bundle catalog records for installed merchants.",
        "optional": true,
        "permission_id": "manage_bundles",
        "required_scopes": [
          "commerce.bundles.write"
        ],
        "title": "Manage bundles"
      }
    ],
    "redirect_uris": [
      "https://plugins.acme.com/flint/oauth/callback",
      "http://localhost:3000/flint/oauth/callback"
    ],
    "visibility": "private"
  }'

Get partner app#

GET/v1/developer/partner/apps/{partner_app_id}

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

Returns a single partner app owned by the authenticated merchant.

Path parameters

partner_app_idstringRequired

Flint partner app ID.

Response · 200

dataobjectRequired

An application that merchants can authorize to access their accounts.

metaobject

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

request_idstring
curl https://api.withflintpay.com/v1/developer/partner/apps/papp_01KEZF7C00D8DXK5AXR7NPRJ0J \
  -H "Flint-Version: 2026-09-07" \
  -H "Authorization: Bearer YOUR_API_KEY"
JSON
{
  "data": {
    "allowed_scopes": [
      "commerce.bundles.read",
      "commerce.bundles.write",
      "commerce.catalog.read",
      "commerce.orders.read",
      "commerce.orders.write",
      "commerce.products.read",
      "customers.read",
      "customers.write"
    ],
    "api_version": "2026-09-07",
    "app_type": "plugin",
    "client_id": "fpc_1234567890abcdef1234567890abcd",
    "created_at": "2026-03-18T20:00:00Z",
    "default_requested_permissions": [
      "manage_orders"
    ],
    "name": "Acme Commerce Plugin",
    "partner_app_id": "papp_01KEZF7C00D8DXK5AXR7NPRJ0J",
    "permission_manifest": [
      {
        "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 and update customer records for installed merchants.",
        "optional": true,
        "permission_id": "manage_customers",
        "required_scopes": [
          "customers.read",
          "customers.write"
        ],
        "title": "Manage customers"
      },
      {
        "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"
      },
      {
        "description": "Create and update bundle catalog records for installed merchants.",
        "optional": true,
        "permission_id": "manage_bundles",
        "required_scopes": [
          "commerce.bundles.write"
        ],
        "title": "Manage bundles"
      }
    ],
    "redirect_uris": [
      "https://plugins.acme.com/flint/oauth/callback",
      "http://localhost:3000/flint/oauth/callback"
    ],
    "status": "active",
    "updated_at": "2026-03-18T20:00:00Z",
    "visibility": "private"
  },
  "request_id": "req_01KWM6HNH8SHHVBC9SMWGJ0E9D"
}

Update partner app#

PATCH/v1/developer/partner/apps/{partner_app_id}Idempotent

Requires scope developer.partner_apps.write

Updates the API version for a partner app owned by the authenticated merchant. Any supported version can be selected.

Path parameters

partner_app_idstringRequired

Flint partner app ID.

Request body

api_versionstring
expected_api_versionstring

Apply api_version only if this matches the resource's current api_version. A mismatch returns HTTP 409. Requires api_version; null is not accepted.

Response · 200

Same response as Get partner app.

curl -X PATCH https://api.withflintpay.com/v1/developer/partner/apps/papp_01KEZF7C00D8DXK5AXR7NPRJ0J \
  -H "Flint-Version: 2026-09-07" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{
    "api_version": "2026-09-07"
  }'

List partner app installs#

GET/v1/developer/partner/apps/{partner_app_id}/installs

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

Returns installs for a partner app owned by the authenticated merchant.

Path parameters

partner_app_idstringRequired

Flint partner app ID.

Query parameters

page_sizeinteger

Page size, default 20, max 100.

page_tokenstring

Cursor returned by the previous list response.

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/apps/papp_01KEZF7C00D8DXK5AXR7NPRJ0J/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_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_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"
        }
      ],
      "granted_scopes": [
        "commerce.orders.read",
        "commerce.orders.write",
        "commerce.products.read",
        "commerce.bundles.read",
        "commerce.catalog.read"
      ],
      "installed_by_user_id": "usr_01KEZF7C00NQEV558W0ESKV30S",
      "merchant_id": "mer_01KEZF7C00MPP0T9S0KH5BB4CC",
      "partner_app_id": "papp_01KEZF7C00CRN13BTTQVZ1CEWS",
      "partner_app_install_id": "pinst_01KEZF7C00V5TD9V9QS2PK2VEE",
      "status": "active",
      "updated_at": "2026-03-18T20:06:00Z"
    }
  ],
  "next_page_token": "example",
  "request_id": "req_01KWM6JY3QVFM8KDF0537N33SC"
}

Get partner app install#

GET/v1/developer/partner/apps/{partner_app_id}/installs/{partner_app_install_id}

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

Returns a single install for the installing merchant or the partner app owner.

Path parameters

partner_app_idstringRequired

Flint partner app ID.

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 https://api.withflintpay.com/v1/developer/partner/apps/papp_01KEZF7C00D8DXK5AXR7NPRJ0J/installs/pinst_01KEZF7C00V5TD9V9QS2PK2VEE \
  -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_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_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"
      }
    ],
    "granted_scopes": [
      "commerce.orders.read",
      "commerce.orders.write",
      "commerce.products.read",
      "commerce.bundles.read",
      "commerce.catalog.read"
    ],
    "installed_by_user_id": "usr_01KEZF7C00NQEV558W0ESKV30S",
    "merchant_id": "mer_01KEZF7C00MPP0T9S0KH5BB4CC",
    "partner_app_id": "papp_01KEZF7C00CRN13BTTQVZ1CEWS",
    "partner_app_install_id": "pinst_01KEZF7C00V5TD9V9QS2PK2VEE",
    "status": "active",
    "updated_at": "2026-03-18T20:06:00Z"
  },
  "request_id": "req_01KWM61BVP6Y3ESWR3BHA76VG9"
}

Revoke environment grant#

POST/v1/developer/partner/apps/{partner_app_id}/installs/{partner_app_install_id}/environment-grants/{environment_grant_id}/revokeIdempotent

Requires scope developer.partner_apps.write

The installing merchant or partner app owner can revoke a single test or live environment grant for an install.

Path parameters

partner_app_idstringRequired

Flint partner app ID.

partner_app_install_idstringRequired

Flint partner app install ID.

environment_grant_idstringRequired

Flint environment grant ID.

Response · 200

Same response as Get partner app install.

curl -X POST https://api.withflintpay.com/v1/developer/partner/apps/papp_01KEZF7C00D8DXK5AXR7NPRJ0J/installs/pinst_01KEZF7C00V5TD9V9QS2PK2VEE/environment-grants/egrt_01JQPARTNERGRANTTEST123456/revoke \
  -H "Flint-Version: 2026-09-07" \
  -H "Authorization: Bearer YOUR_API_KEY"

Revoke partner app install#

POST/v1/developer/partner/apps/{partner_app_id}/installs/{partner_app_install_id}/revokeIdempotent

Requires scope developer.partner_apps.write

The installing merchant or partner app owner can revoke an install and all of its environment grants.

Path parameters

partner_app_idstringRequired

Flint partner app ID.

partner_app_install_idstringRequired

Flint partner app install ID.

Response · 200

Same response as Get partner app install.

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

Rotate partner app secret#

POST/v1/developer/partner/apps/{partner_app_id}/rotate-secretIdempotent

Requires scope developer.partner_apps.write

Rotates the client secret for a partner app owned by the authenticated merchant. The new client_secret is only returned once.

Path parameters

partner_app_idstringRequired

Flint partner app ID.

Response · 200

dataobjectRequired

A partner app's client ID and its new client secret after rotation.

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/developer/partner/apps/papp_01KEZF7C00D8DXK5AXR7NPRJ0J/rotate-secret \
  -H "Flint-Version: 2026-09-07" \
  -H "Authorization: Bearer YOUR_API_KEY"

List installed partner apps#

GET/v1/developer/partner/installs

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

Returns partner app installs and environment grants belonging to the authenticated merchant.

Query parameters

page_sizeinteger

Page size, default 20, max 100.

page_tokenstring

Cursor returned by the previous list response.

Response · 200

Same response as List partner app installs.

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_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_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"
        }
      ],
      "granted_scopes": [
        "commerce.orders.read",
        "commerce.orders.write",
        "commerce.products.read",
        "commerce.bundles.read",
        "commerce.catalog.read"
      ],
      "installed_by_user_id": "usr_01KEZF7C00NQEV558W0ESKV30S",
      "merchant_id": "mer_01KEZF7C00MPP0T9S0KH5BB4CC",
      "partner_app_id": "papp_01KEZF7C00CRN13BTTQVZ1CEWS",
      "partner_app_install_id": "pinst_01KEZF7C00V5TD9V9QS2PK2VEE",
      "status": "active",
      "updated_at": "2026-03-18T20:06:00Z"
    }
  ],
  "next_page_token": "example",
  "request_id": "req_01KWM6JY3QVFM8KDF0537N33SC"
}

Was this helpful?