Skip to content
Docs

Submit Invoice

POSThttps://api.vercel.com/v1/installations/{integrationConfigurationId}/billing/invoices
This endpoint allows the partner to submit an invoice to Vercel. The invoice is created in Vercel's billing system and sent to the customer. Depending on the type of billing plan, the invoice can be sent at a time of signup, at the start of the billing period, or at the end of the billing period.

Use the credentials.access_token we provided in the Upsert Installation body to authorize this request.
There are several limitations to the invoice submission:

1. A resource can only be billed once per the billing period and the billing plan.
2. The billing plan used to bill the resource must have been active for this resource during the billing period.
3. The billing plan used must be a subscription plan.
4. The interim usage data must be sent hourly for all types of subscriptions. See Send subscription billing and usage data API on how to send interim billing and usage data.
5. If provided, externalId must be unique for the installation.
Request
import { Vercel } from "@vercel/sdk";


const vercel = new Vercel({
  bearerToken: "<YOUR_BEARER_TOKEN_HERE>",
});


async function run() {
  const result = await vercel.marketplace.submitInvoice({
    integrationConfigurationId: "<id>",
    requestBody: {
      invoiceDate: new Date("2023-12-12T13:24:35.882Z"),
      period: {
        start: new Date("2024-10-20T02:46:19.279Z"),
        end: new Date("2025-06-06T21:30:28.107Z"),
      },
      items: [
        {
          billingPlanId: "<id>",
          name: "<value>",
          price: "469.29",
          quantity: 3808.42,
          units: "<value>",
          total: "<value>",
        },
        {
          billingPlanId: "<id>",
          name: "<value>",
          price: "469.29",
          quantity: 3808.42,
          units: "<value>",
          total: "<value>",
        },
      ],
    },
  });


  console.log(result);
}


run();
Response
{
  "invoiceId": "example_id",
  "test": "false",
  "validationErrors": []
}

Authentication

AuthorizationbearerToken

Default authentication mechanism

Path parameters

integrationConfigurationIdstringRequired

Body

application/json
externalIdstringOptional
Partner-provided invoice identifier. If provided, it must be unique for this installation.
invoiceDatestringRequired
Invoice date. Must be within the period's start and end.
memostringOptional
Additional memo for the invoice.
periodobjectRequired
Subscription period for this billing cycle.
itemsarrayRequired
discountsarrayOptional
finalbooleanOptional
Set this to true if this is the final invoice for the installation. Can only be set when the installation is pending deletion.
testobjectOptional
Test mode

Response

200Success
invoiceIdstringOptional
testbooleanOptional
validationErrorsarrayOptional

Errors

400One of the provided values in the request body is invalid. One of the provided values in the request query is invalid.
401The request is not authorized.
403You do not have permission to access this resource.
404Error
409Error
410Error