Manage Billing and Refunds for Integrations

When a Vercel user installs your native integration, you manage billing through the Vercel API billing endpoints. Each integration operates its own independent billing lifecycle, allowing Vercel users to configure different payment methods for each integration.

You can choose between two billing models:

• Installation-level billing: Charges apply to the entire installation. A single billing plan covers all resources provisioned under that installation.
• Resource-level billing: Charges are scoped to individual products or resources. Each resource can have its own billing plan.

You determine which model to use. You can only submit one invoice per resource per billing period, but a single invoice can include multiple line items for the same resource.

You control the billing cycle through the field in your API calls. There's no required day of the month for billing cycles to align across integrations. Each integration can bill on its own schedule.

Vercel users can configure a different payment method for each integration installation, independent of their Vercel plan payment method and other integrations.

Invoices move through several states as they're processed:

You have flexibility in how you structure charges. A single invoice can include multiple line items covering:

• Flat fees: Fixed monthly or periodic charges
• Usage-based charges: Costs calculated from actual resource consumption
• Tiered pricing: Different rate tiers (for example, tier 1 usage at one rate, tier 2 at another)

Each line item can specify a unit, quantity, rate, and detailed description. This gives Vercel users a clear breakdown of charges.

We recommend consolidating all resource billing under a single invoice and keeping resources on the same billing cycle. This reduces the number of invoices Vercel users receive each month, but it's not a requirement.

When working with billing data:

• Decimal precision: All monetary values use 2 decimal places
• Minimum threshold: Vercel won't send invoices totaling less than $0.50. You should still submit billing data for transparency so Vercel users can confirm no additional costs accrued

To bill customers, call the Vercel billing API endpoints. All requests require the from the Upsert Installation request body for authorization.

Call the Submit Billing Data endpoint () at least once a day, ideally once per hour.

This data is for display purposes only, helping Vercel users understand their expected charges throughout the billing period. Vercel does not generate invoices or process payments from this data. Actual billing happens only when you submit an invoice.

The following example shows a request with billing items and usage metrics:

At the end of a billing period, call the Submit Invoice endpoint () to charge the customer.

The following example shows a request with multiple line items:

We recommend including an in your invoice requests. This lets you tie invoices to your internal billing records for easier reconciliation.

The response includes an you can use to track status or request refunds.

To check invoice status, call the Get Invoice endpoint (). You can also subscribe to billing webhooks to receive real-time updates when invoice states change.

You can use test mode to validate your billing integration before going live. Test mode uses the object in the Submit Invoice API with a field:

• : Runs full validation including date checks, item validation, discount validation, and duplicate detection
• : Skips these validations

Outside of test mode, Vercel always runs validation and you cannot override it.

To test with live payment methods during the pre-launch phase:

1. Remove the object from your Submit Invoice calls
2. Submit the invoice
3. Wait for the and webhooks
4. Issue a refund using the Invoice Actions API

When you request a refund, Vercel handles it as follows:

1. If Vercel hasn't charged the invoice yet, it cancels the invoice
2. If Vercel already charged the invoice, it attempts to refund the original payment method
3. If the payment method isn't working, Vercel creates a support ticket
4. If anything goes wrong with the refund attempt, Vercel creates a support ticket

For invoices in status, a refund request will succeed and move the status to , then to once the funds are returned. Only invoices already in status are blocked from additional refund requests.

With installation-level billing, the installation goes through finalization after deletion. This gives you time to calculate any remaining charges and submit final invoices. Finalization follows these rules:

1. Open invoices exist: Vercel blocks finalization until invoices are settled. You can refund these invoices during this time.
2. Finalization window: By default, you have 24 hours after deletion to submit any final invoices. If you submit invoices during this window, the installation goes back to step 1. To skip this window, return in your Delete Installation endpoint response.
3. Installation finalized: Refunds must be processed manually through Vercel customer support.

Vercel handles all taxation since Vercel issues the invoices. You only submit raw service charges to the billing APIs. You don't need to calculate or add tax to your charges.

Only Vercel users with Owner or Billing roles can view invoices for your integration. They can view their invoices by:

1. Going to the Integrations tab in their Vercel dashboard
2. Selecting Manage next to your integration
3. Navigating to the Invoices section