Create a Native Integration

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.

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

1. Set up the integration

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

2. Deploy the integration server

   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

3. Add a new product

   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

4. Complete the fields and save

   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.
   3. Select Apply Changes

5. Update your integration server

   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.

6. Publish your product

   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 [email protected] 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.

You can add it to your editor configuration as follows:

{
  "$schema": "https://vercel.com/api/v1/integrations/marketplace/metadata-schema"
}