Native integration concepts
As an integration provider, understanding how your service interacts with Vercel's platform will help you create and optimize your integration.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.
| Concept | Definition |
|---|---|
| Team installation | The primary connection between a user's team and a specific integration. |
installationId | The main partition key connecting the user's team to the integration. |
Understanding the limits of team installation instances for all types of integrations can help you design a better integration architecture.
| Metric | Limit |
|---|---|
| Native integration installation | A maximum of one installation instance of a specific provider's native integration per team. |
| Connectable account integration installation | A maximum of one installation instance of a specific provider's connectable account integration per team. |
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.
| Concept | Definition |
|---|---|
| Product | An offering that integration users can add to their native integration installation. A provider can offer multiple products through one integration. |
| Billing plan | Each product has an associated pricing structure that the provider specifies when creating products. |
Resources are the actual instances of products that integration users provision and utilize. They provide the flexibility and granularity needed for users to tailor the integration to their specific needs and project structures.
| Concept | Definition |
|---|---|
| Resource | A specific instance of a product provisioned in an installation. |
| Provisioning | Explicit creation and removal (de-provisioning) of resources by users. |
| Keysets | Independent sets of secrets for each resource. |
| Project connection | Ability to link resources to Vercel projects independently. |
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.
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.
| Concept | Definition |
|---|---|
| Resource-level billing | Billing and usage can be tracked separately for each resource. |
| Installation-level billing | Billing and usage for all resources can also be combined under one installation. |
| Billing plan and payment | A plan can be of type prepaid or subscription. You ensure that the correct plans are pulled from your backend with your integration server before you submit a product for review. |
We recommend you implement resource-level billing, which is the default, to provide users with detailed cost breakdowns and enable more flexible pricing strategies.
Was this helpful?