Requirements for listing an Integration

Defining the content specs helps you create the main cover page of your integration. On the marketplace listing, the cover page looks like this.

The following requirements are located in the integrations console.

• Character Limit: 64
• Required: Yes

This is the integration title which appears on Integration overview. This title should be unique.

• Character Limit: 32
• Required: Yes

This will create the URL for your integration. It will be located at:

https://vercel.com/integrations/<slug>

• Character Limit: 64
• Required: Yes

The name of the integration owner, generally a legal name.

• Required: Yes

There are two types of email that you must provide:

• Contact email: This is the contact email for the owner of the integration. It will not be publicly visible and will only be used by Vercel to contact you.
• Support contact email: The support email for the integration. This email will be publicly listed and used by developers to contact you about any issues.

• Character Limit: 40
• Required: Yes

The integration tagline on the Marketplace card, and the Integrations overview in the dashboard.

• Required: Yes

The image displayed in a circle, that appears throughout the dashboard and marketing pages. Like all assets, it will appear in both light and dark mode.

You must make sure that the images adhere to the following dimensions and aspect ratios:

• Required: Yes

The category of your integration is used to help developers find your integration in the marketplace. You can choose from the following categories:

• Commerce
• Logging
• Databases
• CMS
• Monitoring
• Dev Tools
• Performance
• Analytics
• Experiments
• Security
• Searching
• Messaging
• Productivity
• Testing
• Observability
• Checks

• Required: Yes

The following URLs must be submitted as part of your application:

• Website: A URL to the website related to your integration
• Documentation URL: A URL for users to learn how to use your integration
• EULA URL: The URL to your End User License Agreement (EULA) for your integration. For more information about your required EULA, see the Integrations Marketplace Agreement, section 2.4.
• Privacy Policy URL: The URL to your Privacy Policy for your integration. For more information about your required privacy policy, see the Integrations Marketplace Agreement, section 2.4.

• Character Limit: 768
• Required: Yes

This is a long description about the integration. It should describe why and when a user may want to use this integration. Markdown is supported.

• Character Limit: 1024
• Required: No

Additional steps to install or configure your integrations. Include environment variables and their purpose. Markdown is supported.

• Required: Yes

These are a collection of images displayed on the carousel at the top of your marketplace listing. We require at least 1 image, but you can add up to 5. The images and text must be of high quality.

These gallery images will appear in both light and dark mode. Avoid long text, as it may not be legible on smaller screens.

Also consider the 20% safe zone around the edges of the image by placing the most important content of your images within the bounds. This will ensure that no information is cut when cropped.

Your media should adhere to the following dimensions and aspect ratios:

• Required: No

API Scopes define the level of access your integration will have to the Vercel REST API. When setting up a new integration, you need to:

• Select only the API Scopes that are essential for your integration to function
• Choose the appropriate permission level for each scope: None, Read, or Read/Write

After activation, your integration may collect specific user data based on the selected scopes. You are accountable for:

• The privacy, security, and integrity of this user data
• Compliance with Vercel's Shared Responsibility Model

Learn more about API scope permissions in the Extending Vercel documentation.

• Required: No

With your integration, you can listen for events on the Vercel platform through Webhooks. The following events are available:

The following events are available for deployments:

• deployment.created
• deployment.error
• deployment.canceled
• deployment.succeeded

The following events are available for configurations:

• integration-configuration.permission-upgraded
• integration-configuration.removed
• integration-configuration.scope-change-confirmed

The following events are available for domains:

• domain.created

The following events are available for projects:

• project.created
• project.removed

The following events are available for checks:

• deployment.ready
• deployment.check-rerequested

See the Webhooks documentation to learn more.

• Required: No

To allow the developer to configure an installed integration, you can specify a Configuration URL. This URL is used for the Configure button on each configuration page. Selecting this button will redirect the developer to your specified URL with a configurationId query parameter. See Interacting with Configurations to learn more.

If you leave the Configuration URL field empty, the Configure button will default to a Website button that links to the website URL you specified on integration settings.

• Required: If it's a product

The URL that points to the provider's integration server that implements the Marketplace Provider API. To interact with the provider's application, Vercel makes a request to the base URL appended with the path for the specific endpoint.

For example, if the base url is https://foo.bar.com/vercel-integration-server, Vercel makes a POST request to something like https://foo.bar.com/vercel-integration-server/v1/installations.

• Required: If it's a product

The URL where Vercel redirect users of the integration in the following situations:

• They open the link to the integration provider's dashboard from the Vercel dashboard
• They open a specific resource on the Vercel dashboard

This allows providers to automatically log users into their dashboard without asking them to log in.

• Required: No (It's a toggle which is disabled by default)
• Applies to a installation

When enabled, it allows the integration user to select a billing plan for their installation. The default installation-level billing plan is chosen by the partner. When disabled, the installation does not have a configurable billing plan.

If the billing for your integration happens at the team, organization or account level, enable this toggle to allow Vercel to fetch the installation-level billing plans. When the user selects an installation-level billing plan, you can then upgrade the plan for this team, account or organization when you provision the product.

The user can update this installation-level plan at any time from the installation detail page of the Vercel dashboard.

• Required:
  • Yes: If it's a connectable account integration or this is the first time you are creating a native integration
  • No: If you are adding a product to the integration. A different agreement may be needed for the first added product

You must agree to the Vercel terms before your integration can be published. The terms may differ depending the type of integration, connectable account or native.

• Required: Yes

The Redirect URL is an HTTP endpoint that handles the installation process by exchanging a code for an API token, serving a user interface, and managing project connections:

• Token Exchange: Exchanges a provided code for a Vercel REST API access token
• User Interface: Displays a responsive UI in a popup window during the installation
• Project Provisioning: Allows users to create new projects or connect existing ones in your system to their Vercel Projects
• Completion: Redirects the user back to Vercel upon successful installation

Usage Scenario: For installations initiated from the Vercel Marketplace.

• Post-Installation: After installation, the user is redirected to a page on your side to complete the setup
• Completion: Redirect the user to the provided next URL to close the popup and continue

Usage Scenario: When you're initiating the installation from your application.

• Starting Point: Use this URL to start the process: https://vercel.com/integrations/:slug/new - :slug is the name you added in the Create Integration form

Usage Scenario: For installations using the Vercel deploy button.

• Post-Installation: The user will complete the setup on your side
• Completion: Redirect the user to the provided next URL to proceed

If the integration is already installed in the selected scope during the deploy button flow, the redirect URL will be called with the most recent configurationId.

Make sure to store configurationId along with an access token such that if an existing configurationId was passed, you could retrieve the corresponding access token.