Native Integrations Rest API

Reference

Vercel Marketplace Rest API

Table of Contents

Learn how to authenticate and use the Marketplace API to set up your integration server for the base URL.

How it works

When a customer uses your integration, the communication happens in both directions:

Vercel calls the partner API
The partner calls the Vercel API

Vercel Marketplace Partner API

This authentication uses the OpenID Connect Protocol (OIDC). Vercel sends a JSON web token (JWT) signed with Vercel’s private key and verifiable using Vercel’s public JSON Web Key Sets (JWKS) available here.

User Auth OIDC token claims schema:

Attributes

JSON Schema

account_idstringRequired

audstringRequired
The ID of the target integration. Example: "oac_9f4YG9JFjgKkRlxoaaGG0y05"

installation_idstringRequired
The ID of target installation. Example: "icfg_9bceb8ccT32d3U417ezb5c8p"

issstringRequired
One of: https://marketplace.vercel.com

substringRequired
Denotes the User who is making the change (matches /^account:[0-9a-fA-F]+:user:[0-9a-fA-F]+$/)

user_avatar_urlstring
The user's public avatar URL

user_emailstring
The user's email address. For this property to have a value, your Marketplace integration must be opted in. Please reach out to Vercel Support to request access. Without access, this property will be undefined.

user_idstringRequired

user_namestring
The user's real name

user_rolestringRequired
One of: ADMIN | USER

System Authentication

System Auth OIDC token claims schema:

Attributes

JSON Schema

account_idstringRequired

audstringRequired
The ID of the target integration. Example: "oac_9f4YG9JFjgKkRlxoaaGG0y05"

installation_idstring or nullRequired
The ID of target installation. Example: "icfg_9bceb8ccT32d3U417ezb5c8p"

issstringRequired
One of: https://marketplace.vercel.com

substringRequired
Denotes the Account (or Team) who is making the change (matches /^account:[0-9a-fA-F]+$/), possibly null

Installations

API related to Installation operatinos

Upsert Installation

put /v1/installations/{installationId}

Security: User Authentication

Description:Create or update an installation

Parameters

Path

Header

Body

Name	Description	Type
`installationId`	The ID of target installation. Example: "icfg_9bceb8ccT32d3U417ezb5c8p"	`string`

Response

204

400

403

409

Description:

The installation was created successfully

No content

Get Installation

get /v1/installations/{installationId}

Security: System Authentication

Description:Get an installation

Parameters

Path

Name	Description	Type
`installationId`	The ID of target installation. Example: "icfg_9bceb8ccT32d3U417ezb5c8p"	`string`

Response

200

403

Description:

The installation

Attributes

JSON Schema

billingPlanobject
The billing plan for the installation. If not set, the installation is billed on resource level.

Properties

Update Installation

patch /v1/installations/{installationId}

Security: User Authentication

Description:Update an installation

Parameters

Path

Header

Body

Name	Description	Type
`installationId`	The ID of target installation. Example: "icfg_9bceb8ccT32d3U417ezb5c8p"	`string`

Response

204

400

403

409

Description:

The installation was updated successfully

No content

Delete Installation

delete /v1/installations/{installationId}

Security: User Authentication

Description:Deletes the Installation. The final deletion is postponed for 12 hours to allow for sending of final invoices. You can request immediate deletion by specifying {finalized:true} in the response.

Parameters

Path

Header

Name	Description	Type
`installationId`	The ID of target installation. Example: "icfg_9bceb8ccT32d3U417ezb5c8p"	`string`

Response

200

204

403

409

Description:

Installation deleted successfully

Attributes

JSON Schema

finalizedboolean
If true, the installation will be removed immediately. Otherwise, the installation will stay in the "delete pending" state for 12 hours awaiting for finalizing invoice(s).

Resources

API related to Resource operations

Provision Resource

post /v1/installations/{installationId}/resources

Security: User Authentication

Description:Provisions a Resource. This is a synchronous operation but the provisioning can be asynchronous as the Resource does not need to be immediately available however the secrets must be known ahead of time.

Parameters

Path

Header

Body

Name	Description	Type
`installationId`	The ID of target installation. Example: "icfg_9bceb8ccT32d3U417ezb5c8p"	`string`

Response

200

400

403

409

Description:

Return the newly provisioned resource

Attributes

JSON Schema

billingPlanobject
The billing plan for the resource. If not set, the resource is billed on installation level.

Properties
idstringRequired
The partner-specific ID of the resource

metadataobjectRequired
User-inputted metadata based on the registered metadata schema.

namestringRequired
User-inputted name for the resource.

notificationobject
Resource's active notification. Example: { "level": "warn", "title": "Database is nearing maximum planned size" }

Properties
productIdstringRequired
The partner-specific ID/slug of the product. Example: "redis"

secretsarrayRequired
Properties
statusstringRequired
One of: ready | pending | suspended | resumed | uninstalled | error

List Resources

get /v1/installations/{installationId}/resources

Security: System Authentication

Description:Lists all Resources

Parameters

Path

Query

Name	Description	Type
`installationId`	The ID of target installation. Example: "icfg_9bceb8ccT32d3U417ezb5c8p"	`string`

Response

200

403

Description:

Return a list of Resources for a given Installation

Attributes

JSON Schema

resourcesarrayRequired
Properties

Get Resource

get /v1/installations/{installationId}/resources/{resourceId}

Security: System Authentication

Description:Get a Resource

Parameters

Path

Name	Description	Type
`installationId`	The ID of target installation. Example: "icfg_9bceb8ccT32d3U417ezb5c8p"	`string`
`resourceId`	Partner-provided resource ID	`string`

Response

200

403

Description:

Return the resource

Attributes

JSON Schema

billingPlanobject
The billing plan for the resource. If not set, the resource is billed on installation level.

Properties
idstringRequired
The partner-specific ID of the resource

metadataobjectRequired
User-inputted metadata based on the registered metadata schema.

namestringRequired
User-inputted name for the resource.

notificationobject
Resource's active notification. Example: { "level": "warn", "title": "Database is nearing maximum planned size" }

Properties
productIdstringRequired
The partner-specific ID/slug of the product. Example: "redis"

statusstringRequired
One of: ready | pending | suspended | resumed | uninstalled | error

Update Resource

patch /v1/installations/{installationId}/resources/{resourceId}

Security: User Authentication

Description:Updates a resource

Parameters

Path

Header

Body

Name	Description	Type
`installationId`	The ID of target installation. Example: "icfg_9bceb8ccT32d3U417ezb5c8p"	`string`
`resourceId`	Partner-provided resource ID	`string`

Response

200

400

403

409

Description:

Return the updated resource

Attributes

JSON Schema

billingPlanobject
The billing plan for the resource. If not set, the resource is billed on installation level.

Properties
idstringRequired
The partner-specific ID of the resource

metadataobjectRequired
User-inputted metadata based on the registered metadata schema.

namestringRequired
User-inputted name for the resource.

notificationobject
Resource's active notification. Example: { "level": "warn", "title": "Database is nearing maximum planned size" }

Properties
productIdstringRequired
The partner-specific ID/slug of the product. Example: "redis"

statusstringRequired
One of: ready | pending | suspended | resumed | uninstalled | error

Delete Resource

delete /v1/installations/{installationId}/resources/{resourceId}

Security: User Authentication

Description:Uninstalls and de-provisions a Resource

Parameters

Path

Header

Name	Description	Type
`installationId`	The ID of target installation. Example: "icfg_9bceb8ccT32d3U417ezb5c8p"	`string`
`resourceId`	Partner-provided resource ID	`string`

Response

204

403

409

Description:

Resource deleted successfully

No content

Resource REPL

post /v1/installations/{installationId}/resources/{resourceId}/repl

Security: User Authentication

Description:The REPL is a command-line interface on the Store Details page that allows customers to directly interact with their resource. This endpoint is used to run commands on a specific resource.

Parameters

Path

Header

Body

Name	Description	Type
`installationId`	The ID of target installation. Example: "icfg_9bceb8ccT32d3U417ezb5c8p"	`string`
`resourceId`	Partner-provided resource ID	`string`

Response

200

403

Description:

Return result of running REPL command

Attributes

JSON Schema

array
Array

Billing

API related to Billing operations

List Billing Plans For Product

get /v1/products/{productSlug}/plans

Security: System Authentication

Description:

Vercel sends a request to the partner to return quotes for different billing plans for a specific Product.

Note: You can have this request triggered by Vercel before the integration is installed when the Product is created for the first time. In this case, OIDC will be incomplete and will not contain an account ID.

Parameters

Path

Query

Name	Description	Type
`productSlug`	The partner-specific ID/slug of the product. Example: "redis"	`string`

Response

200

400

403

409

Description:

Return a list of billing plans

Attributes

JSON Schema

plansarrayRequired
Properties

List Billing Plans For Resource

get /v1/installations/{installationId}/resources/{resourceId}/plans

Security: System Authentication

Description:Returns the set of billing plans available to a specific Resource

Parameters

Path

Query

Name	Description	Type
`installationId`	The ID of target installation. Example: "icfg_9bceb8ccT32d3U417ezb5c8p"	`string`
`resourceId`	Partner-provided resource ID	`string`

Response

200

400

403

409

Description:

Return a list of billing plans for a resource

Attributes

JSON Schema

plansarrayRequired
Properties

List Billing Plans For Installation

get /v1/installations/{installationId}/plans

Security: System Authentication

Description:Returns the set of billing plans available to a specific Installation

Parameters

Path

Name	Description	Type
`installationId`	The ID of target installation. Example: "icfg_9bceb8ccT32d3U417ezb5c8p"	`string`

Response

200

403

409

Description:

Return a list of billing plans for an installation

Attributes

JSON Schema

plansarrayRequired
Properties

Vercel API

Security

bearerToken

This authentication uses the Vercel API authentication bearer token.

oauth2

Authorization URL: https://api.vercel.com/oauth/authorize
Token URL: https://api.vercel.com/oauth/access_token

Marketplace

Get Account Information

get /v1/installations/{integrationConfigurationId}/account

Security: bearerToken

Description:Fetches the best account or user’s contact info

Parameters

Path

Name	Description	Type
`integrationConfigurationId`	None	`string`

Response

200

400

401

403

Attributes

JSON Schema

contactobject or nullRequired

Properties
namestring

urlstringRequired

Get Member Information

get /v1/installations/{integrationConfigurationId}/member/{memberId}

Security: bearerToken

Description:Returns the member role and other information for a given member ID ("user_id" claim in the SSO OIDC token).

Parameters

Path

Name	Description	Type
`integrationConfigurationId`	None	`string`
`memberId`	None	`string`

Response

200

400

401

403

404

Attributes

JSON Schema

idstringRequired

rolestringRequired
One of: ADMIN | USER

Create Event

post /v1/installations/{integrationConfigurationId}/events

Security: bearerToken

Description:Partner notifies Vercel of any changes made to an Installation or a Resource. Vercel is expected to use list-resources and other read APIs to get the new state.

resource.updated event should be dispatched when any state of a resource linked to Vercel is modified by the partner.

Use cases:

- The user renames a database in the partner’s application. The partner should dispatch a resource.updated event to notify Vercel to update the resource in Vercel’s datastores.

Parameters

Path

Body

Name	Description	Type
`integrationConfigurationId`	None	`string`

Response

201

400

401

403

No content

Submit Billing Data

post /v1/installations/{integrationConfigurationId}/billing

Security: bearerToken

Description:Sends the billing and usage data. The partner should do this at least one a day and ideally once per hour.

Parameters

Path

Body

Name	Description	Type
`integrationConfigurationId`	None	`string`

Response

201

400

401

403

No content

Submit Invoice

post /v1/installations/{integrationConfigurationId}/billing/invoices

Security: bearerToken

Description: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.

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.

Parameters

Path

Body

Name	Description	Type
`integrationConfigurationId`	None	`string`

Response

200

400

401

403

Attributes

JSON Schema

invoiceIdstring

testboolean

validationErrorsarray

Get Invoice

get /v1/installations/{integrationConfigurationId}/billing/invoices/{invoiceId}

Security: bearerToken

Description:Get Invoice details and status for a given invoice ID.

See Billing Events with Webhooks documentation on how to receive invoice events. This endpoint is used to retrieve the invoice details.

Parameters

Path

Name	Description	Type
`integrationConfigurationId`	None	`string`
`invoiceId`	None	`string`

Response

200

400

401

403

404

Attributes

JSON Schema

createdstringRequired

discountsarray
Properties
externalIdstring

invoiceDatestringRequired

invoiceIdstringRequired

itemsarrayRequired
Properties
memostring

periodobjectRequired

Properties
refundReasonstring

refundTotalstring

statestringRequired
One of: pending | scheduled | invoiced | paid | notpaid | refund_requested | refunded

testbooleanRequired

totalstringRequired

updatedstringRequired

Invoice Actions

post /v1/installations/{integrationConfigurationId}/billing/invoices/{invoiceId}/actions

Security: bearerToken

Description:This endpoint allows the partner to request a refund for an invoice to Vercel. The invoice is created using the Submit Invoice API.

Parameters

Path

Body

Name	Description	Type
`integrationConfigurationId`	None	`string`
`invoiceId`	None	`string`

Response

204

400

401

403

404

No content

Update Resource Secrets

put /v1/installations/{integrationConfigurationId}/products/{integrationProductIdOrSlug}/resources/{resourceId}/secrets

Security: bearerToken

Description:This endpoint updates the secrets of a resource. If a resource has projects connected, the connected secrets are updated with the new secrets. The old secrets may still be used by existing connected projects because they are not automatically redeployed. Redeployment is a manual action and must be completed by the user. All new project connections will use the new secrets.

Use cases for this endpoint:

- Resetting the credentials of a database in the partner. If the user requests the credentials to be updated in the partner’s application, the partner post the new set of secrets to Vercel, the user should redeploy their application and the expire the old credentials.

Parameters

Path

Body

Name	Description	Type
`integrationConfigurationId`	None	`string`
`integrationProductIdOrSlug`	None	`string`
`resourceId`	None	`string`

Response

201

400

401

403

404

No content

Authentication

SSO Token Exchange

post /v1/integrations/sso/token

Description:Partner exchanges the OAuth authorization code for an OIDC token. A successful response from this endpoint means the partner can verify the identity of the requesting user during the Open in Partner flow. Partners should not persist the returned id_token in a database since the token will expire.

Parameters

Body

Response

200

400

404

500

Attributes

JSON Schema

access_tokenRequired

id_tokenstringRequired

token_typeRequired

Billing events with webhooks

Receive billing events with webhooks

You can receive the following events:

marketplace.invoice.created: the invoice was created and sent to the customer
marketplace.invoice.paid: the invoice was paid
marketplace.invoice.notpaid: the invoice was not paid after a grace period
- You can then take the appropriate action, such as suspending the resource

Changes

2024-09-06: "Delete Installation" API can optionally return {finalized: true} to signal that the installation can be removed immediately. Otherwise, the installation will wait for up to 12hr for any pending billing data to be submitted.
2024-08-27: Removed BillingPlan.maxResources field.
2024-08-20: Added AccountInfo.url field to the "Get Account Information" API.
2024-08-16: "Get Member Information" API.
2024-08-16: Documentation for API error responses (e.g. 400, 403) added.
2024-08-15: Added "Get Installation" and "List Billing Plans for Installation" API for installation-level billing. Added BillingPlan.scope attribute that determines installation or resource level billing for a billing plan.
2024-08-14: "Submit Invoice" and "Submit Billing Data" APIs no longer require resourceId for each item.
2024-08-14: "Submit Invoice" and "Submit Billing Data" APIs accept discounts fields.
2024-08-13: Resource.billingPlan is no longer required when the integration has installation-level billing enabled. If installation-level billing is not enabled in the Integration Console and this property is missing, the response will be treated as an error.
2024-08-09: Added the user_email to the User Authentication JWT claims.
2024-07-24: Added REPL endpoint.
2024-07-09: Removed BillingPlan.requiredPolicies? and ProvisionResourceRequest.acceptedPolicies fields until further notice. The only policies required/accepted for now are for the InstallIntegrationRequest.
2024-07-01: Resource.notification field for an optional active resource notification.
2024-07-01: BillingPlan.quote field is replaced with more generic BillingPlan.details and BillingPlan.cost fields.
2024-07-01: BillingPlan.paymentMethodRequired field as added to indicate free plans.
2024-06-16: The "Refund Invoice" API.
2024-06-03: The "Submit Invoice" and "Get Invoice" APIs.
2024-06-03: The negative amount statement for the BillingItem in the "Send invoice billing and usage data" endpoint is removed as not correct.
2024-05-30: The Vercel API routes using the /v1/integrations/marketplace/installations namespace were shortened to /v1/installations. The old, longer namespaced routes will continue to work as expected.
2024-05-23: BillingPlan.type value of "invoice" has been changed to "subscription".
2024-05-21: Resource.billingPlan type has been changed from string (for a plan ID) to a BillingPlan structure with the complete plan information. billingPlan: string for a plan ID has been changed to billingPlanId: string for consistency.
2024-05-21: BillingPlan.maxProducts has been renamed to maxResources.

Last updated on September 13, 2024

Approval Checklist

Was this helpful?