marketplace

Reference

Marketplace

Create Event

post/v1/installations/{integrationConfigurationId}/events

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.

Optional params

fetch-request

1await fetch("https://api.vercel.com/v1/installations/SOME_STRING_VALUE/events", {
2  "body": {
3    "event": {
4      "type": "installation.updated",
5      "billingPlanId": "SOME_STRING_VALUE"
6    }
7  },
8  "headers": {
9    "Authorization": "Bearer <TOKEN>"
10  },
11  "method": "post"
12})

Parameters

Path Params

Body Params

Path Parameter	Description
integrationConfigurationId	string required

Response

N/A

Response Codes

Code	Description
`201`
`400`	One of the provided values in the request body is invalid. One of the provided values in the request query is invalid.
`401`
`403`	You do not have permission to access this resource.

Optional params

fetch-request

1await fetch("https://api.vercel.com/v1/installations/SOME_STRING_VALUE/events", {
2  "body": {
3    "event": {
4      "type": "installation.updated",
5      "billingPlanId": "SOME_STRING_VALUE"
6    }
7  },
8  "headers": {
9    "Authorization": "Bearer <TOKEN>"
10  },
11  "method": "post"
12})

SSO Token Exchange

post/v1/integrations/sso/token

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.

Optional params

fetch-request

1await fetch("https://api.vercel.com/v1/integrations/sso/token", {
2  "body": {
3    "client_id": "SOME_STRING_VALUE",
4    "client_secret": "SOME_STRING_VALUE",
5    "code": "SOME_STRING_VALUE",
6    "redirect_uri": "SOME_STRING_VALUE",
7    "state": "SOME_STRING_VALUE"
8  },
9  "headers": {
10    "Authorization": "Bearer <TOKEN>"
11  },
12  "method": "post"
13})

Parameters

Body Params

Body Parameter	Description
client_id	string required The integration client id
client_secret	string required The integration client secret
code	string required The sensitive code received from Vercel
redirect_uri	string The integration redirect URI
state	string The state received from the initialization request

Response

access_tokenRequired

id_tokenstringRequired

token_typeRequired

Response Codes

Code	Description
`200`
`400`	One of the provided values in the request body is invalid.
`404`
`500`

Optional params

fetch-request

1await fetch("https://api.vercel.com/v1/integrations/sso/token", {
2  "body": {
3    "client_id": "SOME_STRING_VALUE",
4    "client_secret": "SOME_STRING_VALUE",
5    "code": "SOME_STRING_VALUE",
6    "redirect_uri": "SOME_STRING_VALUE",
7    "state": "SOME_STRING_VALUE"
8  },
9  "headers": {
10    "Authorization": "Bearer <TOKEN>"
11  },
12  "method": "post"
13})

Get Account Information

get/v1/installations/{integrationConfigurationId}/account

Fetches the best account or user’s contact info

Optional params

fetch-request

1await fetch("https://api.vercel.com/v1/installations/SOME_STRING_VALUE/account", {
2  "headers": {
3    "Authorization": "Bearer <TOKEN>"
4  },
5  "method": "get"
6})

Parameters

Path Params

Path Parameter	Description
integrationConfigurationId	string required

Response

contactobject or nullRequired

Properties
namestring

urlstringRequired

Response Codes

Code	Description
`200`
`400`	One of the provided values in the request query is invalid.
`401`
`403`	You do not have permission to access this resource.

Optional params

fetch-request

1await fetch("https://api.vercel.com/v1/installations/SOME_STRING_VALUE/account", {
2  "headers": {
3    "Authorization": "Bearer <TOKEN>"
4  },
5  "method": "get"
6})

Get Invoice

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

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.

Optional params

fetch-request

1await fetch("https://api.vercel.com/v1/installations/SOME_STRING_VALUE/billing/invoices/SOME_STRING_VALUE", {
2  "headers": {
3    "Authorization": "Bearer <TOKEN>"
4  },
5  "method": "get"
6})

Parameters

Path Params

Path Parameter	Description
integrationConfigurationId	string required
invoiceId	string required

Response

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

Response Codes

Code	Description
`200`
`400`	One of the provided values in the request query is invalid.
`401`
`403`	You do not have permission to access this resource.
`404`

Optional params

fetch-request

1await fetch("https://api.vercel.com/v1/installations/SOME_STRING_VALUE/billing/invoices/SOME_STRING_VALUE", {
2  "headers": {
3    "Authorization": "Bearer <TOKEN>"
4  },
5  "method": "get"
6})

Get Member Information

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

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

Optional params

fetch-request

1await fetch("https://api.vercel.com/v1/installations/SOME_STRING_VALUE/member/SOME_STRING_VALUE", {
2  "headers": {
3    "Authorization": "Bearer <TOKEN>"
4  },
5  "method": "get"
6})

Parameters

Path Params

Path Parameter	Description
integrationConfigurationId	string required
memberId	string required

Response

idstringRequired

rolestringRequired
One of: ADMIN | USER

Response Codes

Code	Description
`200`
`400`	One of the provided values in the request query is invalid.
`401`
`403`	You do not have permission to access this resource.
`404`

Optional params

fetch-request

1await fetch("https://api.vercel.com/v1/installations/SOME_STRING_VALUE/member/SOME_STRING_VALUE", {
2  "headers": {
3    "Authorization": "Bearer <TOKEN>"
4  },
5  "method": "get"
6})

Submit Billing Data

post/v1/installations/{integrationConfigurationId}/billing

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

Optional params

fetch-request

1await fetch("https://api.vercel.com/v1/installations/SOME_STRING_VALUE/billing", {
2  "body": {
3    "billing": "ANY_TYPE_VALUE",
4    "eod": "SOME_STRING_VALUE",
5    "period": {
6      "start": "SOME_STRING_VALUE",
7      "end": "SOME_STRING_VALUE"
8    },
9    "timestamp": "SOME_STRING_VALUE",
10    "usage": [
11      {
12        "resourceId": "SOME_STRING_VALUE",
13        "name": "SOME_STRING_VALUE",
14        "type": "total",
15        "units": "SOME_STRING_VALUE",
16        "dayValue": "SOME_NUMBER_VALUE",
17        "periodValue": "SOME_NUMBER_VALUE",
18        "planValue": "SOME_NUMBER_VALUE"
19      }
20    ]
21  },
22  "headers": {
23    "Authorization": "Bearer <TOKEN>"
24  },
25  "method": "post"
26})

Parameters

Path Params

Body Params

Path Parameter	Description
integrationConfigurationId	string required

Response

N/A

Response Codes

Code	Description
`201`
`400`	One of the provided values in the request body is invalid. One of the provided values in the request query is invalid.
`401`
`403`	You do not have permission to access this resource.

Optional params

fetch-request

1await fetch("https://api.vercel.com/v1/installations/SOME_STRING_VALUE/billing", {
2  "body": {
3    "billing": "ANY_TYPE_VALUE",
4    "eod": "SOME_STRING_VALUE",
5    "period": {
6      "start": "SOME_STRING_VALUE",
7      "end": "SOME_STRING_VALUE"
8    },
9    "timestamp": "SOME_STRING_VALUE",
10    "usage": [
11      {
12        "resourceId": "SOME_STRING_VALUE",
13        "name": "SOME_STRING_VALUE",
14        "type": "total",
15        "units": "SOME_STRING_VALUE",
16        "dayValue": "SOME_NUMBER_VALUE",
17        "periodValue": "SOME_NUMBER_VALUE",
18        "planValue": "SOME_NUMBER_VALUE"
19      }
20    ]
21  },
22  "headers": {
23    "Authorization": "Bearer <TOKEN>"
24  },
25  "method": "post"
26})

Submit Invoice

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

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.

Optional params

fetch-request

1await fetch("https://api.vercel.com/v1/installations/SOME_STRING_VALUE/billing/invoices", {
2  "body": {
3    "invoiceDate": "SOME_STRING_VALUE",
4    "items": [
5      {
6        "resourceId": "SOME_STRING_VALUE",
7        "billingPlanId": "SOME_STRING_VALUE",
8        "start": "SOME_STRING_VALUE",
9        "end": "SOME_STRING_VALUE",
10        "name": "SOME_STRING_VALUE",
11        "details": "SOME_STRING_VALUE",
12        "price": "SOME_STRING_VALUE",
13        "quantity": "SOME_NUMBER_VALUE",
14        "units": "SOME_STRING_VALUE",
15        "total": "SOME_STRING_VALUE"
16      }
17    ],
18    "period": {
19      "start": "SOME_STRING_VALUE",
20      "end": "SOME_STRING_VALUE"
21    },
22    "discounts": [
23      {
24        "resourceId": "SOME_STRING_VALUE",
25        "billingPlanId": "SOME_STRING_VALUE",
26        "start": "SOME_STRING_VALUE",
27        "end": "SOME_STRING_VALUE",
28        "name": "SOME_STRING_VALUE",
29        "details": "SOME_STRING_VALUE",
30        "amount": "SOME_STRING_VALUE"
31      }
32    ],
33    "externalId": "SOME_STRING_VALUE",
34    "memo": "SOME_STRING_VALUE",
35    "test": {
36      "validate": true,
37      "result": "paid"
38    }
39  },
40  "headers": {
41    "Authorization": "Bearer <TOKEN>"
42  },
43  "method": "post"
44})

Parameters

Path Params

Body Params

Path Parameter	Description
integrationConfigurationId	string required

Response

invoiceIdstring

testboolean

validationErrorsarray

Response Codes

Code	Description
`200`
`400`	One of the provided values in the request body is invalid. One of the provided values in the request query is invalid.
`401`
`403`	You do not have permission to access this resource.

Optional params

fetch-request

1await fetch("https://api.vercel.com/v1/installations/SOME_STRING_VALUE/billing/invoices", {
2  "body": {
3    "invoiceDate": "SOME_STRING_VALUE",
4    "items": [
5      {
6        "resourceId": "SOME_STRING_VALUE",
7        "billingPlanId": "SOME_STRING_VALUE",
8        "start": "SOME_STRING_VALUE",
9        "end": "SOME_STRING_VALUE",
10        "name": "SOME_STRING_VALUE",
11        "details": "SOME_STRING_VALUE",
12        "price": "SOME_STRING_VALUE",
13        "quantity": "SOME_NUMBER_VALUE",
14        "units": "SOME_STRING_VALUE",
15        "total": "SOME_STRING_VALUE"
16      }
17    ],
18    "period": {
19      "start": "SOME_STRING_VALUE",
20      "end": "SOME_STRING_VALUE"
21    },
22    "discounts": [
23      {
24        "resourceId": "SOME_STRING_VALUE",
25        "billingPlanId": "SOME_STRING_VALUE",
26        "start": "SOME_STRING_VALUE",
27        "end": "SOME_STRING_VALUE",
28        "name": "SOME_STRING_VALUE",
29        "details": "SOME_STRING_VALUE",
30        "amount": "SOME_STRING_VALUE"
31      }
32    ],
33    "externalId": "SOME_STRING_VALUE",
34    "memo": "SOME_STRING_VALUE",
35    "test": {
36      "validate": true,
37      "result": "paid"
38    }
39  },
40  "headers": {
41    "Authorization": "Bearer <TOKEN>"
42  },
43  "method": "post"
44})

Invoice Actions

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

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

Optional params

fetch-request

1await fetch("https://api.vercel.com/v1/installations/SOME_STRING_VALUE/billing/invoices/SOME_STRING_VALUE/actions", {
2  "body": {
3    "action": "refund",
4    "reason": "SOME_STRING_VALUE",
5    "total": "SOME_STRING_VALUE"
6  },
7  "headers": {
8    "Authorization": "Bearer <TOKEN>"
9  },
10  "method": "post"
11})

Parameters

Path Params

Body Params

Path Parameter	Description
integrationConfigurationId	string required
invoiceId	string required

Response

N/A

Response Codes

Code	Description
`204`
`400`	One of the provided values in the request body is invalid. One of the provided values in the request query is invalid.
`401`
`403`	You do not have permission to access this resource.
`404`

Optional params

fetch-request

1await fetch("https://api.vercel.com/v1/installations/SOME_STRING_VALUE/billing/invoices/SOME_STRING_VALUE/actions", {
2  "body": {
3    "action": "refund",
4    "reason": "SOME_STRING_VALUE",
5    "total": "SOME_STRING_VALUE"
6  },
7  "headers": {
8    "Authorization": "Bearer <TOKEN>"
9  },
10  "method": "post"
11})

Update Resource Secrets

put/v1/installations/{integrationConfigurationId}/products/{integrationProductIdOrSlug}/resources/{resourceId}/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.

Optional params

fetch-request

1await fetch("https://api.vercel.com/v1/installations/SOME_STRING_VALUE/products/SOME_STRING_VALUE/resources/SOME_STRING_VALUE/secrets", {
2  "body": {
3    "secrets": [
4      {
5        "name": "SOME_STRING_VALUE",
6        "value": "SOME_STRING_VALUE"
7      }
8    ]
9  },
10  "headers": {
11    "Authorization": "Bearer <TOKEN>"
12  },
13  "method": "put"
14})

Parameters

Path Params

Body Params

Path Parameter	Description
integrationConfigurationId	string required
integrationProductIdOrSlug	string required
resourceId	string required

Response

N/A

Response Codes

Code	Description
`201`
`400`	One of the provided values in the request body is invalid. One of the provided values in the request query is invalid.
`401`
`403`	You do not have permission to access this resource.
`404`

Optional params

fetch-request

1await fetch("https://api.vercel.com/v1/installations/SOME_STRING_VALUE/products/SOME_STRING_VALUE/resources/SOME_STRING_VALUE/secrets", {
2  "body": {
3    "secrets": [
4      {
5        "name": "SOME_STRING_VALUE",
6        "value": "SOME_STRING_VALUE"
7      }
8    ]
9  },
10  "headers": {
11    "Authorization": "Bearer <TOKEN>"
12  },
13  "method": "put"
14})

Last updated on December 4, 2024

Retrieves a list of Integration log drains

Create Event

Was this helpful?