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 following two APIs are used for interaction and communication between the user, Vercel and the provider integration:

Vercel calls the provider API
The provider calls the Vercel API

Review Native Integration Concepts and Native Integration Flows to learn more.

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

Vercel API authentication

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

Authentication with SSO

Provider Initiated SSO

The integration provider can initiate the SSO process from their side. This helps to streamline the authentication process for users coming from the provider's platform and provides security when a user attempts to access a resource managed by a Vercel Marketplace integration.

To initiate SSO, an integration provider needs to construct a URL using the following format:

https://vercel.com/sso/integrations/{URLSlug}/{installationId}?{query}

Where:

URLSlug: The unique identifier for your integration in the Vercel Integrations Marketplace
installationId: The ID of the specific installation for the user
query: Optional query parameters to include additional information

Example

Let's say you have an AWS integration with the following details:

URLSlug: aws-marketplace-integration-demo
installationId: icfg_PSFtkFqr5djKRtOkNtOHIfSd
Additional parameter: resource_id=123456

The constructed URL would look like this:

https://vercel.com/sso/integrations/aws-marketplace-integration-demo/icfg_PSFtkFqr5djKRtOkNtOHIfSd?resource_id=123456

Flow

The provider constructs and redirects the user to the SSO URL
Vercel validates the SSO request and confirms user access
Upon successful validation, Vercel initiates an SSO redirect back to the provider
The user gains authenticated access to the requested resource

SSO Token Exchange

post /v1/integrations/sso/token

Description:During the autorization process, Vercel sends the user to the provider redirectLoginUrl, that includes the OAuth authorization code parameter. The provider then calls the SSO Token Exchange endpoint with the sent code and receives the OIDC token. They log the user in based on this token and redirects the user back to the Vercel account using deep-link parameters included the redirectLoginUrl. This is used to verify the identity of the user during the Open in Provider flow. Providers 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

Vercel Marketplace Partner API

Installations

API related to Installation operations

Upsert Installation

put /v1/installations/{installationId}

Security:UseUser Authenticationto secure this endpoint.

Description:Create or update an installation

Parameters

Path

Header

Body

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

Response

200

204

400

403

409

Description:

The installation was created successfully

Attributes

JSON Schema

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

Properties

Get Installation

get /v1/installations/{installationId}

Security:UseSystem Authenticationto secure this endpoint.

Description:Get an installation

Parameters

Path

Header

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:UseUser Authenticationto secure this endpoint.

Description:Update an installation

Parameters

Path

Header

Body

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

Response

200

204

400

403

409

Description:

The installation was updated successfully

Attributes

JSON Schema

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

Properties

Delete Installation

delete /v1/installations/{installationId}

Security:UseUser AuthenticationandSystem Authenticationto secure this endpoint.

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:UseUser Authenticationto secure this endpoint.

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:UseSystem Authenticationto secure this endpoint.

Description:Lists all Resources

Parameters

Path

Query

Header

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:UseSystem Authenticationto secure this endpoint.

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

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:UseUser Authenticationto secure this endpoint.

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:UseUser AuthenticationandSystem Authenticationto secure this endpoint.

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:UseUser Authenticationto secure this endpoint.

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:UseSystem Authenticationto secure this endpoint.

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

Header

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:UseSystem Authenticationto secure this endpoint.

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

Parameters

Path

Query

Header

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:UseSystem Authenticationto secure this endpoint.

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

Parameters

Path

Header

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

Marketplace

Get Account Information

get /v1/installations/{integrationConfigurationId}/account

Security:UsebearerTokento secure this endpoint.

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:UsebearerTokento secure this endpoint.

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:UsebearerTokento secure this endpoint.

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:UsebearerTokento secure this endpoint.

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:UsebearerTokento secure this endpoint.

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:UsebearerTokento secure this endpoint.

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:UsebearerTokento secure this endpoint.

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:UsebearerTokento secure this endpoint.

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

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-10-08: "Provision Resource" now passes through the externalId property from the external-id query parameter in the Deploy Button flow.
2024-10-04: "Upsert Installation" and "Update Installation" APIs now allow returning {billingPlan: BillingPlan} in the response. This is useful for installation level billing.
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 November 14, 2024

Approval Checklist

Native Integration Flows

Was this helpful?