When a customer uses your integration, the following two APIs are used for interaction and communication between the user, Vercel and the provider integration:
If an endpoint is marked as deprecated, it will remain in the specification for a period of time, after which it will be removed. The description on the endpoint will include how to migrate and use other endpoints for the same functionality.
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:
account_idstring
Required
audstring
Required
The integration ID. Example: "oac_9f4YG9JFjgKkRlxoaaGG0y05"
installation_idstring
Required
The ID of the installation. Example: "icfg_9bceb8ccT32d3U417ezb5c8p"
issstring
Required
One of: https://marketplace.vercel.com
substring
Required
Denotes the User who is making the change (matches /^account:[0-9a-fA-F]+:user:[0-9a-fA-F]+$/)
typestring
One of: access_token | id_token
The type of the token: id_token or access_token.
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_idstring
Required
user_namestring
The user's real name
user_rolestring
Required
One of: ADMIN | USER
The ADMIN role, by default, is provided to users capable of installing integrations, while the USER role can be granted to Vercel users with the Vercel Billing or Vercel Viewer role, which are considered to be Read-Only roles.
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:
account_idstring
Required
audstring
Required
The integration ID. Example: "oac_9f4YG9JFjgKkRlxoaaGG0y05"
installation_idstring or null
Required
The ID of the installation. Example: "icfg_9bceb8ccT32d3U417ezb5c8p"
issstring
Required
One of: https://marketplace.vercel.com
substring
Required
Denotes the Account (or Team) who is making the change (matches /^account:[0-9a-fA-F]+$/), possibly null
path: Indicates the area where the user should be redirected to after SSO. The possible values are: "billing", "usage", "onboarding", and "support".
url: The provider-specific URL to redirect the user to after SSO. Must be validated by the provider for validity. The data fields that are allowed to provide sso: URLs, such as Notification.href, will automatically propagate the provided URL in this parameter.
The provider should match the most appropriate part of their dashboard to the user's context.
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:
The billing plan for the installation. If not set, the installation is billed on resource level.
Properties
notificationobject or null
Installation's active notification. Example: { "level": "warn", "title": "Account is exceeding the maximum allowed storage no the current plan" }. Return null to remove any current installation notification.
The billing plan for the installation. If not set, the installation is billed on resource level.
Properties
notificationobject or null
Installation's active notification. Example: { "level": "warn", "title": "Account is exceeding the maximum allowed storage no the current plan" }. Return null to remove any current installation notification.
The billing plan for the installation. If not set, the installation is billed on resource level.
Properties
notificationobject or null
Installation's active notification. Example: { "level": "warn", "title": "Account is exceeding the maximum allowed storage no the current plan" }. Return null to remove any current installation notification.
Description:Deletes the Installation. The final deletion is postponed for 24 hours to allow for sending of final invoices. You can request immediate deletion by specifying {finalized:true} in the response.
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.
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.
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.
Description:Prepares to transfer resources from the current installation to a new one. The target installation to transfer resources to will not be known until the verify & accept steps.
Vercel uses this endpoint to provide a potential target for the transfer, and to request any necessary information for prerequisite setup to support the resources in the target team upon completion of the transfer. Multiple sources/teams may verify the same transfer. Only transfers that haven't been completed can be verified.
Important: The installation ID in the URL is the target installation ID, not the source one.
The new billing plan required for the transfer. This is only required when the current installation's billing plan is not sufficient (should never be the case for free-tier resources).
Finish the transfer process, expects any work required to move the resources from one installation to another on the provider's side is or will be completed successfully. Upon a successful response, the resource in Vercel will be moved to the target installation as well, maintaining its project connection. While the transfer is being completed, no other request to complete the same transfer can be processed. After the transfer has been completed, it cannot be completed again, nor can it be verified.
Important: The installation ID in the URL is the target installation ID, not the source one.
"The ADMIN role, by default, is provided to users capable of installing integrations, while the USER role can be granted to Vercel users with the Vercel Billing or Vercel Viewer role, which are considered to be Read-Only roles."
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. installation.updated event should be dispatched when an installation's billing plan is changed via the provider instead of Vercel.
Resource update 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. - A resource has been suspended due to a lack of use. The partner should dispatch a resource.updated event to notify Vercel to update the resource's status in Vercel's datastores.
Description:This endpoint imports (upserts) a resource to Vercel's installation. This may be needed if resources can be independently created on the partner's side and need to be synchronized to Vercel.
Description:Sends the billing and usage data. The partner should do this at least once a day and ideally once per hour. Use the credentials.access_token we provided in the Upsert Installation body to authorize this request.
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.
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.
Description:Sends the prepayment balances. The partner should do this at least once a day and ideally once per hour. Use the credentials.access_token we provided in the Upsert Installation body to authorize this request.
Description:This endpoint is deprecated and replaced with the endpoint Update Resource Secrets. 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.
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.
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. Providers should not persist the returned id_token in a database since the token will expire. See Authentication with SSO for more details.
Description:When the user enabled Edge Config syncing, then this endpoint can be used by the partner to push their configuration data into the relevant Edge Config.
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. Providers should not persist the returned id_token in a database since the token will expire. See Authentication with SSO for more details.
2025-10-21: Added new SSO deeplink parameter pr=url-to-pull-request to reference the pull request when known in the context.
2025-10-09: Additional vercel/update-installation and vercel/update-resource PATCH APIs.
2025-10-07: The new Resource.status value is now supported: onboarding. When used, Vercel will direct user to complete onboarding using SSO with path equal to "onboarding".
2025-09-17: The Delete Installation endpoint now provides reason field to indicate whether the installation is being deleted due to user action or due to other reasons.
2025-09-10: marketplace.member.changed webhook added for membership changes and removals.
2025-09-02: Create Resources Transfer Request, Validate Resources Transfer Request, and Accept Resources Transfer Request have been added to enable transferring resources between teams.
2025-06-20: Get Integration Resources, Get Integration Resource, and Delete Integration Resource have been added to the APIs available for providers to call on Vercel.
2025-06-20: The ADMIN and USER roles now have clearer explanations in the User Security section, associated with the user_role field.
2025-06-11: Installation.notification field can now be returned in the "Get Installation" API response, allowing for an active installation notification.
2025-05-21: We have updated the Secrets in Provision Resource response, Import Resource request, and Update Resource Secrets to include an environmentOverrides field per secret, allowing for different values on a per-environment level.
2025-05-06: Marketplace Webhooks now include the project.id and project.name in the payload of integration-resource.project-connected hooks, and project.id in integration-resource.project-disconnected hooks.
2025-03-13: The Provision Purchase endpoint now accepts "System" authentication, as well as "User" authentication. System authentication is used for automatic balance top-ups.
2025-03-12: The Upsert Installation endpoint now provides a new request field account: AccountInfo, that can be used in place of calling Get Account Info for the initial installation. The Get Account Info endpoint should continue to be called for all other use cases.
2025-03-12: The Update Resource Secrets By Id endpoint now accepts partial: boolean request field. When set to true, this call allows updating only the specified secrets, leaving the rest of the secrets unchanged.
2025-02-07: Prepayment plan-related endpoints have been added to documentation. See new fields added to billing plans, Provision Purchase endpoint, and Submit Prepayment Balances endpoint.
2025-02-05: The finalization period is extended to 24 hours in the "Delete Installation" API.
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-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-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.