Skip to content

:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.

26.8 KB
Raw Blame

title: Vercel integration sidebar: Handbook showTitle: true

A reference for understanding how the PostHog + Vercel Marketplace integration works end-to-end. Covers installation, billing, usage reporting, feature flag sync, SSO, and uninstall.

Key concepts

Before diving in, a few PostHog data model basics:

  • Organization contains one or more Teams (called "Projects" in the UI)
  • OrganizationIntegration stores Vercel credentials (access tokens, installation ID) scoped to the org. One per Vercel installation.
  • Integration is a per-team/project record for resource-level config (environment variables, product settings). Created when a Vercel resource is provisioned for a specific project.
  • BillingManager (ee/billing/billing_manager.py) is the intermediary PostHog uses to talk to the Billing service. It handles license validation, org syncing, and the actual HTTP calls.

Table of Contents

  1. High-level architecture
  2. Installation flows
  3. Billing & subscriptions
  4. Usage reporting
  5. Invoice lifecycle
  6. Payment failure & collections
  7. Feature flag & experiment sync
  8. SSO (single sign-on)
  9. Uninstall flow
  10. Monitoring
  11. Contacting Vercel support
  12. Key files reference

1. High-level architecture

graph LR
    Vercel["Vercel\nMarketplace + API"]
    PostHog["PostHog\n(posthog repo)"]
    Billing["Billing Service\n(billing repo)"]
    Stripe["Stripe"]

    Vercel -->|"Install / Uninstall\nInvoice paid webhook"| PostHog
    PostHog -->|"Sync feature flags\nSSO token exchange"| Vercel
    PostHog -->|"Create subscription\nCancel subscription"| Billing
    Billing -->|"Submit usage daily\nSubmit invoices"| Vercel
    Billing -->|"Create subscription\nGenerate invoices"| Stripe
    Stripe -->|"invoice.finalized\nwebhook"| Billing

The PostHog repo handles installation, SSO, feature flag sync, and webhooks from Vercel. The Billing repo handles subscription management, usage reporting to Vercel, and invoice submission. They communicate via internal HTTP APIs through BillingManager.


2. Installation flows

There are two ways a customer gets the Vercel integration:

A. Marketplace install (new customer)

A brand new user clicks "Add" in the Vercel Marketplace. PostHog creates everything from scratch.

sequenceDiagram
    actor User
    participant VM as Vercel Marketplace
    participant PH as PostHog
    participant BM as BillingManager
    participant Billing as Billing Service
    participant Stripe

    User->>VM: Click "Add Integration"
    VM->>PH: PUT /api/vercel/v1/installations/{id}
    Note right of PH: installation credentials, user info

    PH->>PH: Create Organization (if new)
    PH->>PH: Create Team (Project)
    PH->>PH: Create OrganizationIntegration

    PH->>BM: authorize(billing_provider="vercel")
    BM->>Billing: POST /api/activate/authorize
    Billing->>Billing: Set customer.billing_provider = "vercel"
    Billing->>Stripe: Create subscription
    Note right of Stripe: collection_method=send_invoice\nmetadata.billing_provider=vercel
    Stripe-->>Billing: subscription_id
    Billing-->>BM: {success: true, subscription_id}

    PH-->>VM: Installation complete
    VM-->>User: Redirect to PostHog

Key endpoint: PUT /api/vercel/v1/installations/{installation_id} in ee/api/vercel/vercel_installation.py

B. Connectable account (link existing PostHog org)

An existing PostHog customer links their org via OAuth. Billing stays with PostHog (no billing_provider change).

sequenceDiagram
    actor User
    participant VM as Vercel Marketplace
    participant PH as PostHog

    User->>VM: Click "Link Existing Account"
    VM->>PH: GET /connect/vercel/callback (Marketplace OAuth code, no state)
    PH->>PH: Exchange Marketplace code, keep the grant for the state (10 min TTL)
    PH-->>User: Redirect to Vercel's install page with a state, set a state cookie
    User->>VM: Continue on the install page
    VM->>PH: GET /connect/vercel/callback (install OAuth code + same state)
    PH->>PH: Reject unless the state matches this browser's cookie
    PH->>PH: Exchange install code, reject unless its Vercel user matches the Marketplace grant
    PH->>PH: Sign a link session with the Marketplace grant (10 min TTL)

    PH-->>User: Show org selection page
    User->>PH: Select org, POST /api/vercel/connect/complete
    PH->>PH: Validate session + cookie
    PH->>PH: Create OrganizationIntegration (type="connectable")
    PH-->>User: Redirect to next_url

Key endpoints:

  • GET /connect/vercel/callback - OAuth callback (ee/api/vercel/vercel_connect.py)
  • GET /api/vercel/connect/session - Available orgs for linking
  • POST /api/vercel/connect/complete - Finalize the link

Note: Connectable installs do NOT call the billing service. The customer keeps their existing PostHog billing. On uninstall, the OrganizationIntegration record is simply deleted with no billing side effects.

C. Transfer to another Vercel team

A Vercel user can move a Marketplace install, with its resources, to another Vercel team (Vercel docs). The installation ID, its access token, the PostHog organization and its billing stay the same. Vercel enables transfers per integration, so ask in #posthog-vercel before relying on them.

  • Vercel calls GET /v1/installations/{id}/resources/{resourceId}/plans during the transfer, and the transfer stalls until that call succeeds.
  • Vercel does not call the installation endpoint. The integration-configuration.transferred webhook refreshes config.account (team name, dashboard URL, contact) from Vercel's account endpoint instead.
  • Connectable installs cannot be transferred, and the webhook handler leaves them unchanged.
  • The new team's contact becomes an Owner. If they signed in through Vercel before the webhook arrived, the webhook promotes them. If not, they become an Owner when they first sign in.
  • Members of the old team keep their PostHog access. Nothing removes them.

3. Billing & subscriptions

How Vercel billing differs

Vercel acts as the payment collector. PostHog still uses Stripe to track usage and generate invoices, but Stripe never charges the customer directly.

graph LR
    subgraph Normal PostHog Customer
        A1[Customer] -->|Card on file| A2[Stripe]
        A2 -->|charge_automatically| A3[Invoice paid]
    end

    subgraph Vercel Customer
        B1[Customer] -->|Pays through| B2[Vercel]
        B3[PostHog/Stripe] -->|send_invoice| B4[Invoice created\nstatus: open]
        B3 -->|Submit invoice| B2
        B2 -->|Webhook: invoice paid| B3
        B3 -->|pay out_of_band| B5[Invoice paid]
    end

How Vercel customers differ from regular customers

Aspect Vercel customer Regular PostHog customer
Signs up via Vercel Marketplace posthog.com
Pays through Vercel Stripe (card on file)
Stripe collection_method send_invoice charge_automatically
days_until_due 30 N/A
metadata.billing_provider "vercel" Not set
Invoice status "open" until Vercel webhook "paid" after card charge
Customer email noreply+vercel-{org_id}@posthog.com Real email
Communications Vercel handles PostHog sends
Daily usage Reported to Vercel + Stripe Stripe only
Invoice submission Submitted to Vercel after finalization Not needed
Feature flags Synced to Vercel Experimentation PostHog only
SSO Via Vercel (/login/vercel) PostHog login
Uninstall Resets to billing_provider=posthog N/A

The billing page also treats Vercel customers differently:

  • A banner says billing for the organization is managed by Vercel. The "View invoices in Vercel" button links to the Vercel invoices page when external_billing_provider_invoices_url is set.
  • The "Downgrade to free plan" card is hidden.
  • With an active subscription, add-ons, platform plan switches, and billing limits work as usual.
  • Without an active subscription, the page locks self-serve billing the same way it does for a paying partner, through selfServeBillingDisabledReason in billingLogic:
    • The upgrade hero and the add-on upgrade banner are hidden.
    • BillingUpgradeCTA, pay gate, and startup program upgrade buttons are disabled.
    • startPaymentEntryFlow and handleProductUpgrade show a toast and stop before they call api/billing/activate.
    • The banner, the toast, and the usage limit alert tell the customer to contact support to change their plan.

The billing service refuses these requests for Vercel customers with a 400 and the code billing_managed_by_provider:

  • POST /api/activate when the customer has no subscription
  • card authorization at POST /api/activate/authorize
  • GET /api/billing/portal

PostHog's api/billing/activate and api/billing/activate/authorize pass the refusal on as a 400 with billing's message and the same code. api/billing/portal redirects to the Vercel invoices page instead, and returns that 400 only when the organization's Vercel integration has no account URL.

The billing_provider field

On the Customer model (billing/models/customer.py):

  • Default: "posthog"
  • Set to "vercel" during marketplace installation
  • Reset to "posthog" on uninstall
  • Also stored in Stripe subscription metadata (survives provider reset for final invoice handling)

4. Usage reporting

PostHog reports usage to Vercel daily so it appears in the Vercel dashboard.

sequenceDiagram
    participant Celery as Celery Task\nreport_daily_usage
    participant Usage as submit_usage_to_vercel
    participant Stripe
    participant Vercel as Vercel API

    Celery->>Usage: Trigger (2 min delay after daily report)

    Usage->>Usage: Get latest usage report
    Usage->>Stripe: Invoice.upcoming(subscription_id)
    Stripe-->>Usage: Upcoming invoice with line items

    Usage->>Vercel: POST usage submission
    Note right of Vercel: Payload includes:\n- Period usage (cumulative)\n- Daily usage (today only)\n- Billing line items with pricing

Usage payload structure

{
  "timestamp": "2025-01-15T14:30:00Z",
  "eod": "2025-01-14T23:59:59Z",
  "period": { "start": "...", "end": "..." },
  "billing": [
    {
      "billingPlanId": "price_xxx",
      "name": "Product Analytics",
      "price": "0.000025",
      "quantity": 123456,
      "units": "events",
      "total": "3.09"
    }
  ],
  "usage": [
    {
      "name": "Events",
      "type": "interval",
      "units": "events",
      "dayValue": 456,
      "periodValue": 12345
    }
  ]
}

Task location: billing/tasks/usage.py - submit_usage_to_vercel()


5. Invoice lifecycle

sequenceDiagram
    participant Stripe
    participant Billing as Billing Service
    participant Vercel as Vercel API

    Note over Stripe: End of billing period
    Stripe->>Billing: Webhook: invoice.finalized

    Billing->>Billing: Resolve billing provider\n(3-level fallback)
    Billing->>Billing: Format invoice (VercelFormatter)
    Billing->>Vercel: POST submit invoice
    Note right of Vercel: Includes line items,\ndiscounts, period, memo
    Vercel-->>Billing: {invoiceId: "mi_xxx"}
    Billing->>Billing: Store Vercel invoice ID\nin billing_provider_metadata

    Note over Vercel: Customer pays Vercel
    Vercel->>Billing: POST /api/billing/webhook/billing-provider
    Note right of Billing: {event_type, billing_provider,\nevent_data: {invoiceId}}

    Billing->>Billing: Find invoice by Vercel ID
    Billing->>Stripe: Invoice.pay(paid_out_of_band=True)
    Billing-->>Vercel: {status: "ok"}

Billing provider resolution (_resolve_billing_provider)

When an invoice is finalized, the system needs to determine which billing provider it belongs to. This uses a 3-level fallback chain:

  1. customer.billing_provider - the live value on the customer model
  2. subscription_details.metadata.billing_provider - snapshot from Stripe subscription metadata (set at subscription creation time)
  3. billing_provider_metadata.billing_provider - stored on the local Invoice model

This fallback chain is what makes the uninstall flow resilient. After uninstall, customer.billing_provider is already reset to "posthog", but the subscription metadata still says "vercel", so the final invoice is still submitted correctly.

Skipped invoices

Invoices with billing_reason == "subscription_create" are silently skipped. These are $0 setup invoices generated when the Stripe subscription is first created. If you're debugging why the "first invoice" never appeared in Vercel, this is why.

Webhook payload structure

The "invoice paid" webhook from Vercel:

{
  "event_type": "marketplace.invoice.paid",
  "billing_provider": "vercel",
  "event_data": {
    "invoiceId": "mi_xxx"
  }
}

Invoice submission data

{
  "externalId": "in_xxx",
  "invoiceDate": "2024-01-01T00:00:00Z",
  "period": { "start": "...", "end": "..." },
  "items": [
    {
      "billingPlanId": "price_xxx",
      "name": "PostHog - Product Analytics",
      "price": "0.000025",
      "quantity": 1000000,
      "units": "events",
      "total": "25.00"
    }
  ],
  "discounts": [{ "billingPlanId": "discount", "name": "Coupon: SAVE20", "amount": "5.00" }]
}

Key files:

  • billing/webhooks/stripe.py - submit_invoice_to_billing_provider() (triggered on invoice.finalized)
  • billing/billing_providers/clients/vercel_formatter.py - formats line items, discounts
  • billing/api/billing_provider_webhook.py - receives "invoice paid" from Vercel

6. Payment failure & collections

When a Vercel customer's payment fails, Vercel handles the initial retry and dunning communication. PostHog only needs to act after the retry window expires.

sequenceDiagram
    participant Vercel as Vercel
    participant PH as PostHog
    participant Customer

    Note over Vercel: Invoice payment fails
    Vercel->>PH: Webhook: marketplace.invoice.notpaid
    Vercel->>Customer: Payment failure emails (dunning)
    Note over Vercel: 15-day retry window begins

    alt Customer pays during retry
        Vercel->>PH: Webhook: marketplace.invoice.paid
        Note over PH: No action needed
    else Retry window elapses
        Vercel->>PH: Webhook: marketplace.invoice.overdue
        PH->>Vercel: PATCH installation status: "suspended"
        PH->>Customer: Notification (email via Get Account Information)
        Note over PH: Wait at least 15 more days\nbefore any destructive action
    end

    alt Customer pays after suspension
        PH->>Vercel: PATCH installation status: "resumed"
        PH->>PH: Restore service
    end

Webhook events

Event Fired when Docs
marketplace.invoice.notpaid Invoice payment fails Vercel docs
marketplace.invoice.overdue 15-day retry window elapses without payment Vercel docs

During the 15-day retry window, Vercel owns all customer-facing payment failure communication. We do not need to send any dunning emails during that period.

Recommended response after overdue

Once the marketplace.invoice.overdue webhook fires:

  1. Suspend the installation - graceful, recoverable degradation (not data deletion)
  2. Notify the customer - use the Get Account Information endpoint to get contact info and send an email
  3. Wait at least 15 additional days before any destructive action (deleting data, removing resources). Degradation alone may prompt payment.

Suspension API

Suspend an entire installation:

PATCH /v1/installations/:integrationConfigurationId
{ "status": "suspended" }

Suspend individual resources:

PATCH /v1/installations/:integrationConfigurationId/resources/:resourceId
{ "status": "suspended" }

Add a notification banner (optional, shown in the Vercel dashboard):

{
  "notification": {
    "level": "error",
    "title": "Account suspended",
    "message": "Your invoice is past due. Please update your payment method.",
    "href": "https://your-billing-page.example.com"
  }
}

level supports info, warn, or error. Send notification: null to clear.

To resume after payment, set { "status": "resumed" }. Valid statuses: ready, pending, onboarding, suspended, resumed, uninstalled, error.

Suspension status is for display only within Vercel. To actually block access, you must also stop serving the customer on the PostHog side.

Tracking unpaid invoices

Track invoice status via the webhook lifecycle events (notpaid -> overdue -> paid). Alternatively, query the get-invoice endpoint against stored invoice IDs.


7. Feature flag & experiment sync

PostHog automatically syncs feature flags and experiments to Vercel's experimentation platform via Django signals.

sequenceDiagram
    participant Dev as Developer
    participant PH as PostHog
    participant Signal as Django Signal
    participant Vercel as Vercel API

    Dev->>PH: Create/Update Feature Flag
    PH->>Signal: post_save fired
    Signal->>Signal: Check if org has\nVercel integration
    Signal->>Vercel: POST create/update\nexperimentation item

    Dev->>PH: Delete Feature Flag
    PH->>Signal: post_save (soft delete) or\npost_delete (hard delete)
    Signal->>Vercel: DELETE experimentation item
  • Sync on save: VercelIntegration.sync_feature_flag_to_vercel() / sync_experiment_to_vercel()
  • Sync on delete: VercelIntegration.delete_feature_flag_from_vercel() / delete_experiment_from_vercel()
  • Soft deletes: The post_save handler checks instance.deleted and calls the delete method if the flag was soft-deleted. Hard deletes go through post_delete.
  • Safety: Wrapped in _safe_vercel_sync() to prevent DB transaction failures
  • Client: VercelAPIClient in ee/vercel/client.py with exponential backoff retry

8. SSO (single sign-on)

Vercel users can SSO into PostHog without a separate login.

An existing active PostHog account can link automatically when the signed Vercel SSO token contains a verified, matching email. Accounts with two-factor authentication or enforced domain SSO must complete PostHog login. The installation's verified-domain restrictions also apply before automatic linking. A stored mapping keeps its original account, and a removed organization member cannot regain access by retrying SSO.

sequenceDiagram
    actor User
    participant Vercel
    participant PH as PostHog

    User->>Vercel: Click "Open PostHog"
    Vercel->>PH: GET /login/vercel?code=xxx&state=yyy
    PH->>Vercel: Exchange SSO code for token response
    Vercel-->>PH: Token response (id_token JWT + access_token)
    PH->>PH: Validate id_token JWT, extract user/team claims
    PH->>PH: Find matching OrganizationIntegration
    PH->>PH: Log user in
    PH-->>User: Redirect to dashboard

Endpoints:

  • GET /login/vercel - SSO entry point (ee/api/vercel/vercel_sso.py)
  • GET /login/vercel/continue - For already-logged-in users

Multi-region: If the resource doesn't exist in the current region (e.g. US), PostHog proactively redirects to the other region (EU). This is a region check, not a failure fallback.


9. Uninstall flow

There are two uninstall paths depending on how the integration was installed:

Marketplace uninstall (billing involved)

sequenceDiagram
    actor User
    participant VM as Vercel Marketplace
    participant PH as PostHog
    participant BM as BillingManager
    participant Billing as Billing Service
    participant Stripe

    User->>VM: Uninstall PostHog integration
    VM->>PH: Webhook: integration.configuration-removed\n(HMAC-SHA1 signed)

    PH->>PH: Validate HMAC signature
    PH->>BM: deauthorize(billing_provider="vercel")
    BM->>Billing: POST /api/activate/authorize/uninstall

    Billing->>Billing: Validate billing_provider matches
    Billing->>Billing: Check for unpaid invoices

    alt Has unpaid invoices
        Billing-->>PH: 409 - OPEN_INVOICES
        PH-->>VM: 500 (all billing errors\nreturn generic 500 to Vercel)
    else No unpaid invoices
        Billing->>Stripe: Cancel subscription (invoice_now=True)
        Stripe-->>Billing: Final invoice generated
        Billing->>Billing: Queue final invoice submission\nto Vercel (Celery task with\nbilling_provider passed as arg)
        Billing->>Billing: Reset billing_provider to "posthog"
        Billing-->>BM: {success: true}
        BM-->>PH: success
        PH->>PH: Delete OrganizationIntegration
    end

Critical detail: The final invoice Celery task receives billing_provider as an explicit string argument at queue time (when it's still "vercel"). It does NOT read customer.billing_provider at execution time. This is why the reset to "posthog" doesn't break final invoice submission. As an additional safety net, the billing provider resolution fallback chain also protects against this — even if the Celery argument were lost, the subscription metadata still retains the original billing provider value.

Connectable uninstall (no billing)

For connectable integrations (linked existing accounts), the webhook handler simply deletes the OrganizationIntegration record. No billing service call is made since these customers keep their existing PostHog billing.

Key files:

  • ee/api/vercel/webhook_events.py - Webhook event handling
  • ee/vercel/integration.py - VercelIntegration.delete_installation()
  • billing/api/billing.py - Uninstall endpoint
  • billing/models/customer.py - cancel_billing_provider_subscription()

10. Monitoring

PostHog dashboard: Vercel Billing Integration - covers customer integrity, invoice lifecycle, usage reporting, submission gap tracking, and financial reconciliation.


11. Contacting Vercel support

For integration or billing issues that need Vercel's involvement, post in the shared Slack channel #posthog-vercel with a :ticket: reaction on the message. This flags it for the Vercel team to pick up.


12. Key files reference

PostHog repo (posthog/)

File Purpose
ee/api/vercel/vercel_installation.py Installation CRUD (PUT /api/vercel/v1/installations/{id})
ee/api/vercel/vercel_connect.py Connectable account OAuth flow
ee/api/vercel/vercel_sso.py SSO endpoints (/login/vercel)
ee/api/vercel/webhook_events.py Webhook event handling (/webhooks/vercel, served by posthog/ingress)
ee/api/vercel/vercel_resource.py Resource management (Vercel projects)
ee/api/vercel/vercel_product.py Product plans
ee/vercel/client.py VercelAPIClient - HTTP client for Vercel APIs
ee/vercel/integration.py VercelIntegration class - core logic (upsert, delete, sync flags)
ee/billing/billing_manager.py BillingManager - intermediary for all billing service calls
posthog/models/organization_integration.py OrganizationIntegration model (org-level, stores Vercel credentials)
posthog/models/integration/model.py Integration model (team/project-level resource record)

Billing repo (billing/)

File Purpose
api/activate.py BillingAuthorizeViewSet - authorize + deprecated uninstall redirect
api/billing.py Canonical uninstall endpoint (/api/billing/uninstall)
api/billing_provider_webhook.py Receives "invoice paid" webhook from Vercel
billing_providers/clients/vercel.py VercelClient - submits usage & invoices to Vercel
billing_providers/clients/vercel_api.py Low-level API calls via PostHog proxy
billing_providers/clients/vercel_formatter.py Formats invoices/usage for Vercel's API
models/customer.py billing_provider field, cancel_billing_provider_subscription()
tasks/usage.py submit_usage_to_vercel() daily task
webhooks/stripe.py submit_invoice_to_billing_provider() on invoice.finalized
constants/billing_provider.py BillingProvider enum, webhook event constants