Native integration concepts

Native integrations allow a two-way connection between Vercel and third-party providers. This enables providers to embed their services into the Vercel ecosystem so that Vercel customers can subscribe to third-party products directly through the Vercel dashboard, providing several key benefits to the integration user:

• They do not need to create an account on your site.
• They can choose suitable billing plans for each product through the Vercel dashboard.
• Billing is managed through their Vercel account.

This document outlines core concepts, structure, and best practices for creating robust, scalable integrations that align with Vercel's ecosystem and user expectations.

Team installations are the foundation of native integrations, providing a secure and organized way to connect user teams with specific integrations. You can then enable centralized management and access control to integration resources through the Vercel dashboard.

Installations represent a connection between a Vercel team and your system. They are team-scoped, not user-scoped, meaning they belong to the entire team rather than the individual who installed them. Therefore, if the user who created an installation leaves the team, the installation remains active and accessible to other team members with appropriate permissions.

Because installations are tied to teams and not individual users, use the Get Account Information endpoint to get current team contact information rather than relying on the original installing user's details.

If a team uninstalls and then reinstalls your integration, Vercel creates a new installationId. Treat this as a completely new installation with no assumptions about previous configuration, billing, or resource states from the earlier installation.

Understanding the limits of team installation instances for all types of integrations can help you design a better integration architecture.

A Vercel team can only have one native integration installation at a time. If a team wants to install the integration again, they need to uninstall the existing installation first. This helps maintain clarity in billing and resource management.

A team can have both a native integration installation and a connectable account integration installation for the same integration if you've set up both on the same integration configuration. In this case, there are technically two installations, and you should treat each one as independent even if you can correlate them in your system.

Products represent the offerings available within an integration, allowing integration users to select and customize an asset such as "ACME Redis Database" or a service such as "ACME 24/7 support" that they would like to use and subscribe to. They provide a structured way to package and present integration capabilities to users.

Resources are the actual instances of products that integration users provision and utilize. They represent instances of products in your system, like databases or other infrastructure the user provisions in your service. Resources provide the flexibility and granularity needed for users to tailor the integration to their specific needs and project structures.

Resources track usage and billing at the individual resource level, giving you the ability to monitor and charge for each provisioned instance separately.

When working with resources, you'll use the installationId as the main identifier for connecting resources to a team's installation. Note that Vercel does not provide a teamId directly. Instead, use the Get Account Information endpoint with the installationId to retrieve current team contact information and other account details.

Integration users can add and manage resources in various ways. For example:

• Single resource: Using one resource such as one database for all projects.
• Per-project resources: Dedicating separate resources for each project.
• Environment-specific resources: Using separate resources for different environments (development, preview, production) within a project.

The diagram below illustrates the relationships between team installations, products, and resources:

• One installation can host multiple products and resources.
• One product can have multiple resource instances.
• Resources can be connected to multiple projects independently.

When a user connects a resource to a Vercel project, Vercel creates environment variables from the secrets your integration provides during provisioning or through the Update Resource Secrets endpoint.

These environment variables are the same across all projects connected to a resource. For example, if your integration provisions a database with a DATABASE_URL secret, every connected project receives the same DATABASE_URL variable.

When a user connects the same resource to multiple projects, or connects multiple resources of the same type to one project, environment variable names can collide. Prefixes solve this by adding a namespace to each variable name.

There are two ways to apply prefixes:

• Provider-defined prefixes: Include a prefix field in the secrets array when provisioning a resource or updating resource secrets. Vercel prepends this prefix to each secret name when creating environment variables.
• User-defined prefixes: When a user connects a resource to a project, they can set a custom prefix in the Custom Prefix field of the connection dialog. If set, this overrides any provider-defined prefix for that connection.

For example, if your integration returns a secret named PGHOST and the user sets a custom prefix of DB1, the resulting environment variable is DB1_PGHOST.

For secrets that start with NEXT_PUBLIC_, the prefix is inserted after NEXT_PUBLIC_ (for example, NEXT_PUBLIC_ACME_PGHOST instead of ACME_NEXT_PUBLIC_PGHOST). This preserves the Next.js client-side exposure behavior.

This is useful when a project needs to connect to two instances of the same resource type, such as a primary and replica database. Each connection can use a different prefix to avoid conflicts.

Billing and usage tracking are crucial aspects of native integrations that are designed to help you create a system of transparent billing based on resource utilization. It enables flexible pricing models and provides users with clear insights into their integration costs.

We recommend you implement resource-level billing, which is the default, to provide users with detailed cost breakdowns and enable more flexible pricing strategies.

To successfully implement your native integration, you'll need to handle several key flows:

• Storage product creation flow
• Data synchronization flows between Vercel and the provider
• Provider dashboard access
• Credential management
• Experimentation integrations flows
• Flows for resource handling with claim deployments