vercel-logotype Logovercel-logotype Logo
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.

Security

Marketplace partner API authentication

User Authentication

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 verified 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

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.

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

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

  1. The provider constructs and redirects the user to the SSO URL
  2. Vercel validates the SSO request and confirms user access
  3. Upon successful validation, Vercel initiates an SSO redirect back to the provider
  4. 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
NameDescriptionType
installationIdThe 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
NameDescriptionType
installationIdThe 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
NameDescriptionType
installationIdThe 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
NameDescriptionType
installationIdThe 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
NameDescriptionType
installationIdThe 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
NameDescriptionType
installationIdThe 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
NameDescriptionType
installationIdThe ID of target installation. Example: "icfg_9bceb8ccT32d3U417ezb5c8p"string
resourceIdPartner-provided resource IDstring

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
NameDescriptionType
installationIdThe ID of target installation. Example: "icfg_9bceb8ccT32d3U417ezb5c8p"string
resourceIdPartner-provided resource IDstring

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
NameDescriptionType
installationIdThe ID of target installation. Example: "icfg_9bceb8ccT32d3U417ezb5c8p"string
resourceIdPartner-provided resource IDstring

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
NameDescriptionType
installationIdThe ID of target installation. Example: "icfg_9bceb8ccT32d3U417ezb5c8p"string
resourceIdPartner-provided resource IDstring

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
NameDescriptionType
productSlugThe 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
NameDescriptionType
installationIdThe ID of target installation. Example: "icfg_9bceb8ccT32d3U417ezb5c8p"string
resourceIdPartner-provided resource IDstring

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
NameDescriptionType
installationIdThe 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
NameDescriptionType
integrationConfigurationIdNonestring

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
NameDescriptionType
integrationConfigurationIdNonestring
memberIdNonestring

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
NameDescriptionType
integrationConfigurationIdNonestring

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
NameDescriptionType
integrationConfigurationIdNonestring

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
NameDescriptionType
integrationConfigurationIdNonestring

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
NameDescriptionType
integrationConfigurationIdNonestring
invoiceIdNonestring

Response

200
400
401
403
404
Attributes
JSON Schema
  • createdstringRequired
  • discountsarray
  • Properties
  • externalIdstring
  • invoiceDatestringRequired
  • invoiceIdstringRequired
  • invoiceNumberstring
  • 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
NameDescriptionType
integrationConfigurationIdNonestring
invoiceIdNonestring

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
NameDescriptionType
integrationConfigurationIdNonestring
integrationProductIdOrSlugNonestring
resourceIdNonestring

Response

201
400
401
403
404

No content

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 21, 2024
Previous
Approval Checklist
Next
Native Integration Flows