Tutorial

Create a Native Integration

Learn how to create a product for your Vercel native integration
Table of Contents

Creating a Native Integration is available on Pro plans

With a product, you allow a Vercel customer who has installed your integration to use specific features of your integration without having them leave the Vercel dashboard and create a separate account on your platform. You can create multiple products for each integration and each integration connects to Vercel through specific categories. Currently, only the storage category is available.

To create and list your products as a Vercel provider, you need to use a Vercel Team on a Pro plan

In this tutorial, you create a storage product for your native integration through the following steps:

  1. Before you can create a product, you must have an existing integration. Create a new Native Integration or use your existing one.

  2. In order to deploy the integration server, you should update your integration configuration to set the base URL to the integration server URL:

    1. Select the team you would like to use from the scope selector.
    2. From your dashboard, select the Integrations tab and then select the Integrations Console button.
    3. Select the integration you would like to use for the product.
    4. Find the base URL field in the Product section and set it to the integration server URL.
    5. Select Update.

    You can use this example Next.js application as a guide to create your integration server

    1. Select the integration you would like to use for the product from the Integrations Console
    2. Select Create Product from the Products card of the Product section
  3. You should now see the Create Product form. Fill in the following fields:

    1. Complete the Name, URL Slug, Visibility and Short Description fields
    2. Optionally update the following in the Metadata Schema field:
    • Edit the properties of the JSON schema to match the options that you are making available through the integration server.
    • Edit and check that the attributes of each property such as type matches your requirements.
    • Include the billing plan options that Vercel will send to your integration server when requesting the list of billing plans.
    • Use the Preview Form section to check your JSON schema as you update it.
    1. Select Apply Changes
  4. Add or update the Billing endpoints in your integration server so that the appropriate plans are pulled from your backend when Vercel calls these endpoints. Review the marketplace integration example for a sample billing plan route.

  5. To publish your product, you'll need to request for the new product to be approved:

    1. Check that your product integration follows our review guidelines
    2. Email integrations@vercel.com with your request to be reviewed for listing

    Once approved, Vercel customers can now add your product with the integration and select a billing plan.

When you first create your product, you will see a JSON schema in the Metadata Schema field of the product configuration options. You will edit this schema to match the options you want to make available in the Vercel integration dashboard to the customer who installs this product integration.

When the customer installs your product, Vercel collects data from this customer and sends it to your integration server based on the Metadata schema you provided in the product configuration. The schema includes properties specific to Vercel that allow the Vercel dashboard to understand how to render the user interface to collect this data from the customer.

As an example, use the following configuration to only show the name of the product:

{
  "type": "object",
  "properties": {},
  "additionalProperties": false,
  "required": []
}

See the endpoints for Provision or Update Resource for specific examples.

Property ui:controlProperty typeNotes
inputnumberNumber input
inputstringText input
togglebooleanToggle input
sliderarraySlider input. The items property of your array must have a type of number
selectstringDropdown input
multi-selectarrayDropdown with multi-select input. The items property of your array must have a type of string
vercel-regionstringVercel Region dropdown input. You can restrict the list of available regions by settings the acceptable regions in the enum property
multi-vercel-regionarrayVercel Region dropdown with multi-select input. You can restrict the list of available regions by settings the acceptable regions in the enum property of your items. Your items property must have type of string

This table shows the possible keys for the properties object that each represent a type of ui:control that is a form element to be used on the Vercel dashboard for this property.

See the full JSON schema for the Metadata Schema. You can add it to your code editor for autocomplete and validation.

You can add it to your editor configuration as follows:

{
  "$schema": "https://vercel.com/api/v1/integrations/marketplace/metadata-schema"
}
Last updated on September 17, 2024