Skip to content
Docs

Upsert Installation

Required
PUT/v1/installations/{installationId}
Create or update an installation
Vercel calls this endpoint when a customer installs your integration, sending credentials (access token), scopes, and account info. Store the installation ID, configure the account on your side, and save the access token for calling Vercel APIs.
/v1/installations/{installationId}
const response = await fetch('/v1/installations/installationId', {
  method: 'PUT',
  headers: {
    'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "scopes": [],
    "acceptedPolicies": "value",
    "credentials": {
      "access_token": "string",
      "token_type": "string"
    },
    "account": {
      "name": "Example Name",
      "url": "https://example.com",
      "contact": {
        "email": "user@example.com",
        "name": "Example Name"
      },
      "country": "string",
      "countrySource": "ip"
    },
    "parentAccount": {
      "name": "Example Name",
      "url": "https://example.com",
      "contact": {
        "email": "user@example.com",
        "name": "Example Name"
      }
    }
  }),
});


const data = await response.json();
console.log(data);
Response
{
  "billingPlan": {
    "id": "icfg_1234567890",
    "type": "prepayment",
    "name": "Example Name",
    "scope": "installation",
    "description": "string",
    "paymentMethodRequired": "true",
    "preauthorizationAmount": "123",
    "initialCharge": "string",
    "minimumAmount": "100.00",
    "maximumAmount": "100.00",
    "maximumAmountAutoPurchasePerPeriod": "100.00",
    "cost": "string",
    "details": [
      {
        "label": "string",
        "value": "string"
      }
    ],
    "highlightedDetails": [
      {
        "label": "string",
        "value": "string"
      }
    ],
    "quote": [
      {
        "line": "string",
        "amount": "100.00"
      }
    ],
    "effectiveDate": "2024-01-01T00:00:00Z",
    "disabled": "true"
  },
  "notification": {
    "level": "info",
    "title": "string",
    "message": "string",
    "href": "https://example.com"
  }
}
Errors
{
  "error": {
    "code": "validation_error",
    "message": "string",
    "user": {
      "message": "string",
      "url": "https://example.com"
    },
    "fields": [
      {
        "key": "string",
        "message": "string"
      }
    ]
  }
}

Authentication

AuthorizationUser Authentication

Default authentication mechanism

Path parameters

installationIdstringRequired

Header parameters

X-Vercel-AuthstringOptional
The auth style used in the request (system, user, etc)
Idempotency-KeystringOptional
A unique key to identify a request across multiple retries

Request

This endpoint expects an object.

scopesarrayRequired
acceptedPoliciesobjectRequired
Policies accepted by the customer. Example: { "toc": "2024-02-28T10:00:00Z" }
credentialsobjectRequired
The service-account access token to access marketplace and integration APIs on behalf of a customer's installation.
accountobjectRequired
The account information for this installation. Use Get Account Info API to re-fetch this data post installation.
parentAccountobjectOptional
For platform org-child installations (integration opt-in): the account information of the parent (root) team. Only present when the parent team has its own installation of this integration; join to it via the parent_account_id token claim.

Response

200The installation was created successfully
billingPlanobjectOptional
The billing plan for the installation. If not set, the installation is billed on resource level.
notificationobjectOptional
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.
204The installation was created successfully

Errors

400Input has failed validation
errorobjectRequired
403Operation failed because the authentication is not allowed to perform this operation
errorobjectRequired
409Operation failed because of a conflict with the current state of the resource
errorobjectRequired
Upsert Installation | Partner API