Skip to content
Docs

Marketplace Partner API

Learn how to implement Partner API endpoints on your integration server. Vercel calls these endpoints to manage installations, handle user actions, and process billing for your native integration.

Select an endpoint from the sidebar to view complete documentation with request/response schemas, authentication requirements, and code examples.

How it works

When a user interacts with your integration, Vercel calls your Partner API endpoints on your integration server. You implement these endpoints to handle:

  • Installation lifecycle — Create, update, and delete installations when users add or remove your integration
  • Resource management — Provision and configure resources when users connect projects or add configuration
  • Billing operations — Handle invoice creation, usage reporting, and payment processing
  • User authentication — Validate and process user-initiated actions

Your integration also calls Vercel API endpoints to interact with Vercel resources like projects, deployments, and environment variables. See Native Integration Flows to understand how these APIs work together.

Authentication

Vercel authenticates requests to your Partner API endpoints using the methods below. You must validate authentication on every request to ensure requests come from Vercel.

User Authentication

This authentication uses the OpenID Connect Protocol (OIDC). Vercel sends a JSON web token (JWT) signed with Vercel’s private key and verifiable using Vercel’s public JSON Web Key Sets (JWKS) available here.
User Auth OIDC token claims schema:
{
  "type": "object",
  "properties": {
    "iss": {
      "type": "string",
      "enum": [
        "https://marketplace.vercel.com"
      ]
    },
    "aud": {
      "type": "string",
      "description": "The integration ID. Example: \"oac_9f4YG9JFjgKkRlxoaaGG0y05\""
    },
    "type": {
      "type": "string",
      "enum": [
        "access_token",
        "id_token"
      ],
      "description": "The type of the token: id_token or access_token."
    },
    "account_id": {
      "type": "string"
    },
    "parent_account_id": {
      "type": "string",
      "description": "For platform org-child installations (integration opt-in): the opaque account id of the parent (root) team. Identical to the `account_id` claim on the parent team’s own installation tokens."
    },
    "parent_installation_id": {
      "type": "string",
      "nullable": true,
      "description": "For platform org-child installations (integration opt-in): the parent team’s installation of this integration, or null when the parent has none."
    },
    "sub": {
      "type": "string",
      "description": "Denotes the User who is making the change (matches `/^account:[0-9a-fA-F]+:user:[0-9a-fA-F]+$/`)"
    },
    "installation_id": {
      "type": "string",
      "description": "The ID of the installation. Example: \"icfg_9bceb8ccT32d3U417ezb5c8p\""
    },
    "user_id": {
      "type": "string"
    },
    "user_role": {
      "type": "string",
      "enum": [
        "ADMIN",
        "USER"
      ],
      "description": "The `ADMIN` role, by default, is provided to users capable of installing integrations, while the `USER` role can be granted to Vercel users with the Vercel `Billing` or Vercel `Viewer` role, which are considered to be Read-Only roles."
    },
    "user_email": {
      "type": "string",
      "description": "The user's email address. This is included for all Marketplace integrations by default."
    },
    "user_email_verified": {
      "type": "boolean",
      "description": "Whether the user's email address has been verified."
    },
    "user_name": {
      "type": "string",
      "description": "The user's real name"
    },
    "user_avatar_url": {
      "type": "string",
      "description": "The user's public avatar URL"
    }
  },
  "required": [
    "iss",
    "aud",
    "account_id",
    "sub",
    "installation_id",
    "user_id",
    "user_role"
  ],
  "additionalProperties": false
}

System Authentication

This authentication uses the OpenID Connect Protocol (OIDC). Vercel sends a JSON web token (JWT) signed with Vercel’s private key and verifiable using Vercel’s public JSON Web Key Sets (JWKS) available here.
System Auth OIDC token claims schema:
{
  "type": "object",
  "properties": {
    "iss": {
      "type": "string",
      "enum": [
        "https://marketplace.vercel.com"
      ]
    },
    "sub": {
      "type": "string",
      "description": "Denotes the Account (or Team) who is making the change (matches `/^account:[0-9a-fA-F]+$/`), possibly null"
    },
    "aud": {
      "type": "string",
      "description": "The integration ID. Example: \"oac_9f4YG9JFjgKkRlxoaaGG0y05\""
    },
    "type": {
      "type": "string",
      "enum": [
        "access_token",
        "id_token"
      ],
      "description": "The type of the token: id_token or access_token."
    },
    "installation_id": {
      "type": "string",
      "nullable": true,
      "description": "The ID of the installation. Example: \"icfg_9bceb8ccT32d3U417ezb5c8p\""
    },
    "account_id": {
      "type": "string"
    },
    "parent_account_id": {
      "type": "string",
      "description": "For platform org-child installations (integration opt-in): the opaque account id of the parent (root) team. Identical to the `account_id` claim on the parent team’s own installation tokens."
    },
    "parent_installation_id": {
      "type": "string",
      "nullable": true,
      "description": "For platform org-child installations (integration opt-in): the parent team’s installation of this integration, or null when the parent has none."
    }
  },
  "required": [
    "iss",
    "sub",
    "aud",
    "installation_id",
    "account_id"
  ],
  "additionalProperties": false
}

Security best practices

  • Verify token signatures — Always validate OIDC token signatures using Vercel's OIDC configuration
  • Check claims — Verify the aud claim matches your integration ID and the sub claim identifies the authenticated user or account
  • Validate user roles — For user authentication, always validate the user's role before performing actions

Base URL

Configure your integration's base URL when you create your integration in the Integration Console. All Partner API endpoints are relative to this base URL.

https://your-integration-server.com/api

Endpoint requirements

Of the 18 endpoints in the Partner API spec, 6 are required for every integration. The remaining 12 are optional and unlocked by specific features your integration supports. When getting started, implement the 6 required endpoints first, then add optional ones as your feature set grows.

Required All integrationsOptional Feature-dependentDeprecated Deprecated

Required endpoints

Every Marketplace integration must implement these six endpoints. Vercel calls them unconditionally during installation and resource lifecycle flows:

EndpointStatusWhen to implement
Upsert InstallationRequiredVercel calls this endpoint when a customer installs your integration, sending credentials (access token), scopes, and account info. Store the installation ID, configure the account on your side, and save the access token for calling Vercel APIs.
Delete InstallationRequiredVercel calls this endpoint when a customer uninstalls your integration and postpones deletion for 24 hours to allow final invoices unless you return finalized: true. Clean up any data, revoke tokens, and remove the installation record from your system.
Provision ResourceRequiredVercel calls this endpoint when a customer creates a resource. Return secrets and connection info immediately, even if full provisioning is async. This is the only resource endpoint whose response includes secrets, which become environment variables on connected projects.
Get ResourceRequiredVercel calls this endpoint to fetch the current state, secrets, and billing plan of a resource during dashboard rendering and resource sync.
Delete ResourceRequiredVercel calls this endpoint when a customer deletes a resource. Deprovision it and clean up any associated data on your side. Vercel does not call this endpoint during installation uninstall. Your Delete Installation handler handles resource cleanup when removing an installation.
List Billing Plans for ProductRequiredVercel calls this endpoint to display available plans when a customer creates a resource. Vercel may call it before any installation exists, so the OIDC token may not include an account ID. Return the list of plans with their pricing, features, and any usage limits.

Optional endpoints

These endpoints are unlocked by specific features. Implement them as your integration's feature set grows:

EndpointStatusWhen to implement
Update InstallationOptionalNeeded if customers can upgrade or downgrade their billing plan on an existing installation. Vercel sends the new billing plan ID in the request body and authenticates with user authentication.
Get InstallationOptionalRequired when Supports Installation Billing Plans is enabled in the Integration Console. Vercel calls this endpoint with system authentication to fetch installation state, including its current billing plan.
List Billing Plans for InstallationOptionalRequired when Supports Installation Billing Plans is enabled in the Integration Console. Vercel calls this endpoint with system authentication to get available plans for an existing installation, powering the plan-selection UI.
Update ResourceOptionalNeeded if customers can change a resource's billing plan, name, or metadata after provisioning. Vercel authenticates with user authentication.
List Billing Plans for ResourceOptionalNeeded if your integration supports plan changes for existing resources. Vercel calls this endpoint with system authentication to populate the plan-selection UI when a user changes a resource's billing plan.
Provision PurchaseOptionalNeeded only if your integration has billing plans with type "prepayment". Vercel calls this endpoint when a customer purchases prepaid credits. Provision the credit balance on your side, then report remaining balances back to Vercel through the Submit Prepayment Balances endpoint. Not needed for integrations that only use fixed or usage billing plan types. Vercel authenticates with user authentication (system authentication fallback).
Request Secrets RotationOptionalExpected for any integration that provisions resources with secrets. Vercel calls this endpoint when a user requests credential rotation through the dashboard, for example after a security incident. Return new credentials that Vercel stores as updated environment variables.
Resource REPLOptionalNeeded if your integration provides an interactive console or REPL experience. Vercel calls this endpoint to run commands or queries against a resource from the dashboard.
Create Resource TransferOptionalNeeded if your integration supports transferring resources between Vercel teams. Vercel calls this endpoint when a user initiates a resource transfer. Update ownership records on your side.

Deprecated endpoints

These endpoints are deprecated. New integrations do not need to implement them:

EndpointStatusWhen to implement
List ResourcesDeprecatedThis endpoint is deprecated. New integrations don't need to implement it. Vercel stores resource state locally after provisioning and uses Get Resource for per-resource lookups instead.

Next steps

  • Select an endpoint from the sidebar to view implementation details
  • Review Native Integration Flows to understand the complete integration lifecycle
  • See the Vercel API reference for endpoints you'll call from your integration