openai/marketplace

Vercel Marketplace

You are an expert in the Vercel Marketplace — the integration platform that connects third-party services to Vercel projects with unified billing, auto-provisioned environment variables, and one-click setup.

Consuming Integrations

Linked Project Preflight

Integration provisioning is project-scoped. Verify the repository is linked before running integration add.

# Check whether this directory is linked to a Vercel project
test -f .vercel/project.json && echo "Linked" || echo "Not linked"

# Link if needed
vercel link

If the project is not linked, do not continue with provisioning commands until linking completes.

Discovering Integrations

# Search the Marketplace catalog from CLI
vercel integration discover

# Filter by category
vercel integration discover --category databases
vercel integration discover --category monitoring

# List integrations already installed on this project
vercel integration list

For browsing the full catalog interactively, use the Vercel Marketplace dashboard.

Getting Setup Guidance

# Get agent-friendly setup guide for a specific integration
vercel integration guide <name>

# Include framework-specific steps when available
vercel integration guide <name> --framework <fw>

# Examples
vercel integration guide neon
vercel integration guide datadog --framework nextjs

Use --framework <fw> as the default discovery flow when framework-specific setup matters. The guide returns structured setup steps including required environment variables, SDK packages, and code snippets — ideal for agentic workflows.

Installing an Integration

# Install from CLI
vercel integration add <integration-name>

# Examples
vercel integration add neon          # Postgres database
vercel integration add upstash       # Redis / Kafka
vercel integration add clerk         # Authentication
vercel integration add sentry        # Error monitoring
vercel integration add sanity        # CMS
vercel integration add datadog       # Observability (auto-configures drain)

vercel integration add is the primary scripted/AI path. It installs to the currently linked project, auto-connects the integration, and auto-runs environment sync locally unless disabled.

If the CLI hands off to the dashboard for provider-specific completion, treat that as fallback:

vercel integration open <integration-name>

Complete the web step, then return to CLI verification (vercel env ls and local env sync check).

Auto-Provisioned Environment Variables

When you install a Marketplace integration from a linked project, Vercel automatically provisions the required environment variables for that project.

IMPORTANT: Provisioning delay after install. After installing a database integration (especially Neon), the resource may take 1–3 minutes to fully provision. During this window, connection attempts return HTTP 500 errors. Do NOT debug the connection string or code — just wait and retry. If local env sync was disabled or skipped, run vercel env pull .env.local --yes after a brief wait to get the finalized credentials.

# View environment variables added by integrations
vercel env ls

# Example: after installing Neon, these are auto-provisioned:
# POSTGRES_URL          — connection string
# POSTGRES_URL_NON_POOLING — direct connection
# POSTGRES_USER         — database user
# POSTGRES_PASSWORD     — database password
# POSTGRES_DATABASE     — database name
# POSTGRES_HOST         — database host

No manual .env file management is needed — the variables are injected into all environments (Development, Preview, Production) automatically.

Using Provisioned Resources

// app/api/users/route.ts — using Neon auto-provisioned env vars
import { neon } from "@neondatabase/serverless";

// POSTGRES_URL is auto-injected by the Neon integration
const sql = neon(process.env.POSTGRES_URL!);

export async function GET() {
  const users = await sql`SELECT * FROM users LIMIT 10`;
  return Response.json(users);
}

// app/api/cache/route.ts — using Upstash auto-provisioned env vars
import { Redis } from "@upstash/redis";

// KV_REST_API_URL and KV_REST_API_TOKEN are auto-injected
const redis = Redis.fromEnv();

export async function GET() {
  const cached = await redis.get("featured-products");
  return Response.json(cached);
}

Managing Integrations

# List installed integrations
vercel integration ls

# Check usage and billing for an integration
vercel integration balance <name>

# Remove an integration
vercel integration remove <integration-name>

Unified Billing

Marketplace integrations use Vercel's unified billing system:

• Single invoice: All integration charges appear on your Vercel bill
• Usage-based: Pay for what you use, scaled per integration's pricing model
• Team-level billing: Charges roll up to the Vercel team account
• No separate accounts: No need to manage billing with each provider individually

# Check current usage balance for an integration
vercel integration balance datadog
vercel integration balance neon

Building Integrations

Integration Architecture

Vercel integrations consist of:

1. Integration manifest — declares capabilities, required scopes, and UI surfaces
2. Webhook handlers — respond to Vercel lifecycle events
3. UI components — optional dashboard panels rendered within Vercel
4. Resource provisioning — create and manage resources for users

Scaffold an Integration

# Create a new integration project
npx create-vercel-integration my-integration

# Or start from the template
npx create-next-app my-integration --example vercel-integration

Integration Manifest

// vercel-integration.json
{
  "name": "my-integration",
  "slug": "my-integration",
  "description": "Provides X for Vercel projects",
  "logo": "public/logo.svg",
  "website": "https://my-service.com",
  "categories": ["databases"],
  "scopes": {
    "project": ["env-vars:read-write"],
    "team": ["integrations:read-write"]
  },
  "installationType": "marketplace",
  "resourceTypes": [
    {
      "name": "database",
      "displayName": "Database",
      "description": "A managed database instance"
    }
  ]
}

Handling Lifecycle Webhooks

// app/api/webhook/route.ts
import { verifyVercelSignature } from "@vercel/integration-utils";

export async function POST(req: Request) {
  const body = await req.json();

  // Verify the webhook is from Vercel
  const isValid = await verifyVercelSignature(req, body);
  if (!isValid) {
    return Response.json({ error: "Invalid signature" }, { status: 401 });
  }

  switch (body.type) {
    case "integration.installed":
      // Provision resources for the new installation
      await provisionDatabase(body.payload);
      break;

    case "integration.uninstalled":
      // Clean up resources
      await deprovisionDatabase(body.payload);
      break;

    case "integration.configuration-updated":
      // Handle config changes
      await updateConfiguration(body.payload);
      break;
  }

  return Response.json({ received: true });
}

Provisioning Environment Variables

// lib/provision.ts
async function provisionEnvVars(
  installationId: string,
  projectId: string,
  credentials: { url: string; token: string },
) {
  const response = await fetch(
    `https://api.vercel.com/v1/integrations/installations/${installationId}/env`,
    {
      method: "POST",
      headers: {
        Authorization: `Bearer ${process.env.VERCEL_INTEGRATION_TOKEN}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        projectId,
        envVars: [
          {
            key: "MY_SERVICE_URL",
            value: credentials.url,
            target: ["production", "preview", "development"],
            type: "encrypted",
          },
          {
            key: "MY_SERVICE_TOKEN",
            value: credentials.token,
            target: ["production", "preview", "development"],
            type: "secret",
          },
        ],
      }),
    },
  );

  return response.json();
}

Integration CLI Commands

The vercel integration CLI supports these subcommands:

# Discover integrations in the Marketplace catalog
vercel integration discover
vercel integration discover --category <category>

# Get agent-friendly setup guide
vercel integration guide <name>
vercel integration guide <name> --framework <framework>

# Add (install) an integration
vercel integration add <name>

# List installed integrations
vercel integration list    # alias: vercel integration ls

# Check usage / billing balance
vercel integration balance <name>

# Open integration dashboard in browser (fallback when add redirects)
vercel integration open <name>

# Remove an integration
vercel integration remove <name>

Building integrations? Use npx create-vercel-integration to scaffold, then deploy your integration app to Vercel normally with vercel --prod. Publish to the Marketplace via the Vercel Partner Dashboard.

Common Integration Categories

| Category | Popular Integrations | Auto-Provisioned Env Vars | | --------------------- | --------------------------------------------- | --------------------------------------- | | Databases | Neon, Supabase, PlanetScale, MongoDB, Turso | POSTGRES_URL, DATABASE_URL | | Cache/KV | Upstash Redis | KV_REST_API_URL, KV_REST_API_TOKEN | | Auth | Clerk, Auth0, Descope | CLERK_SECRET_KEY, AUTH0_SECRET | | CMS | Sanity, Contentful, Storyblok, DatoCMS | SANITY_PROJECT_ID, CONTENTFUL_TOKEN | | Monitoring | Datadog, Sentry, Checkly, New Relic | SENTRY_DSN, DD_API_KEY | | Payments | Stripe | STRIPE_SECRET_KEY | | Feature Flags | LaunchDarkly, Statsig, Hypertune | LAUNCHDARKLY_SDK_KEY | | AI Agents & Services | CodeRabbit, Braintrust, Sourcery, Chatbase | varies by integration | | Video | Mux | MUX_TOKEN_ID, MUX_TOKEN_SECRET | | Messaging | Resend, Knock, Novu | RESEND_API_KEY | | Searching | Algolia, Meilisearch | ALGOLIA_APP_ID, ALGOLIA_API_KEY | | Commerce | Shopify, Swell, BigCommerce | SHOPIFY_ACCESS_TOKEN |

Observability Integration Path

Marketplace observability integrations (Datadog, Sentry, Axiom, Honeycomb, etc.) connect to Vercel's Drains system to receive telemetry. Understanding the data-type split is critical for correct setup.

Data-Type Split

| Data Type | Delivery Mechanism | Integration Setup | | ------------------ | ----------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | | Logs | Native drain (auto-configured by Marketplace install) | vercel integration add <vendor> auto-creates drain | | Traces | Native drain (OpenTelemetry-compatible) | Same — auto-configured on install | | Speed Insights | Custom drain endpoint only | Requires manual drain creation via REST API or Dashboard (https://vercel.com/dashboard/{team}/~/settings/log-drains) | | Web Analytics | Custom drain endpoint only | Requires manual drain creation via REST API or Dashboard (https://vercel.com/dashboard/{team}/~/settings/log-drains) |

Key distinction: When you install an observability vendor via the Marketplace, it auto-configures drains for logs and traces only. Speed Insights and Web Analytics data require a separate, manually configured drain pointing to a custom endpoint. See ⤳ skill: observability for drain setup details.

Agentic Flow: Observability Vendor Setup

Follow this sequence when setting up an observability integration:

1. Pick Vendor

# Discover observability integrations
vercel integration discover --category monitoring

# Get setup guide for chosen vendor
vercel integration guide datadog

2. Install Integration

# Install — auto-provisions env vars and creates log/trace drains
vercel integration add datadog

3. Verify Drain Created

# Confirm drain was auto-configured
curl -s -H "Authorization: Bearer $VERCEL_TOKEN" \
  "https://api.vercel.com/v1/drains?teamId=$TEAM_ID" | jq '.[] | {id, url, type, sources}'

Check the response for a drain pointing to the vendor's ingestion endpoint. If no drain appears, the integration may need manual drain setup — see ⤳ skill: observability for REST API drain creation.

4. Validate Endpoint

# Send a test payload to the drain
curl -X POST -H "Authorization: Bearer $VERCEL_TOKEN" \
  "https://api.vercel.com/v1/drains/<drain-id>/test?teamId=$TEAM_ID"

Confirm the vendor dashboard shows the test event arriving.

5. Smoke Log Check

# Trigger a deployment and check logs flow through
vercel logs <deployment-url> --follow --since 5m

# Check integration balance to confirm data is flowing
vercel integration balance datadog

Verify that logs appear both in Vercel's runtime logs and in the vendor's dashboard.

For drain payload formats and signature verification, see ⤳ skill: observability — the Drains section covers JSON/NDJSON schemas and x-vercel-signature HMAC-SHA1 verification.

Speed Insights + Web Analytics Drains

For observability vendors that also want Speed Insights or Web Analytics data, configure a separate drain manually:

# Create a drain for Speed Insights + Web Analytics
curl -X POST -H "Authorization: Bearer $VERCEL_TOKEN" \
  -H "Content-Type: application/json" \
  "https://api.vercel.com/v1/drains?teamId=$TEAM_ID" \
  -d '{
    "url": "https://your-vendor-endpoint.example.com/vercel-analytics",
    "type": "json",
    "sources": ["lambda"],
    "environments": ["production"]
  }'

Payload schema reference: See ⤳ skill: observability for Web Analytics drain payload formats (JSON array of {type, url, referrer, timestamp, geo, device} events).

Decision Matrix

| Need | Use | Why | | ----------------------------------------- | -------------------------------------------------- | ---------------------------------------------- | | Add a database to your project | vercel integration add neon | Auto-provisioned, unified billing | | Browse available services | vercel integration discover | CLI-native catalog search | | Get setup steps for an integration | vercel integration guide <name> --framework <fw> | Framework-specific, agent-friendly setup guide | | CLI redirects to dashboard during install | vercel integration open <name> | Fallback to complete provider web flow | | Check integration usage/cost | vercel integration balance <name> | Billing visibility per integration | | Build a SaaS integration | Integration SDK + manifest | Full lifecycle management | | Centralize billing | Marketplace integrations | Single Vercel invoice | | Auto-inject credentials | Marketplace auto-provisioning | No manual env var management | | Add observability vendor | vercel integration add <vendor> | Auto-creates log/trace drains | | Export Speed Insights / Web Analytics | Manual drain via REST API | Not auto-configured by vendor install | | Manage integrations programmatically | Vercel REST API | /v1/integrations endpoints | | Test integration locally | vercel dev | Local development server with Vercel features |

Cross-References

• Drain configuration, payload formats, signature verification → ⤳ skill: observability
• Drains REST API endpoints → ⤳ skill: vercel-api
• CLI log streaming (--follow, --since, --level) → ⤳ skill: vercel-cli
• Safe project setup sequencing (link, env pull, then run db/dev) → ⤳ skill:bootstrap
• Headless CMS integrations (Sanity, Contentful) → ⤳ skill:cms

Official Documentation

• Vercel Marketplace
• Building Integrations
• Integration CLI
• Integration Webhooks
• Environment Variables
• Drains Overview
• Drains Security