--- title: provision-purchase product: vercel url: /docs/integrations/create-integration/marketplace-api/reference/partner/provision-purchase type: conceptual prerequisites: [] related: - /docs/integrations/create-integration/marketplace-api/reference/partner - /docs/integrations/create-integration/marketplace-api/reference - /docs/integrations/create-integration/native-integration summary: Learn about provision-purchase on Vercel. install_vercel_plugin: npx plugins add vercel/vercel-plugin --- # Provision Purchase **Status**: Optional **When to implement**: Needed only if your integration has billing plans with type "prepayment". Vercel calls this endpoint when a customer purchases prepaid credits. Provision the credit balance on your side, then report remaining balances back to Vercel through the Submit Prepayment Balances endpoint. Not needed for integrations that only use fixed or usage billing plan types. Vercel authenticates with [user authentication](/docs/integrations/create-integration/marketplace-api/reference/partner#user-authentication) ([system authentication](/docs/integrations/create-integration/marketplace-api/reference/partner#system-authentication) fallback). ```http POST /v1/installations/{installationId}/billing/provision ``` Optional endpoint, only required if your integration supports billing plans with type `prepayment`. ## Authentication **User Authentication**: This authentication uses the [OpenID Connect Protocol (OIDC)](https://auth0.com/docs/authenticate/protocols/openid-connect-protocol). Vercel sends a JSON web token (JWT) signed with Vercel’s private key and verifiable using Vercel’s public [JSON Web Key Sets](https://auth0.com/docs/secure/tokens/json-web-tokens/json-web-key-sets) (JWKS) available [here](https://marketplace.vercel.com/.well-known/jwks). User Auth OIDC token claims schema: ```json type=jsonschema { "type": "object", "properties": { "iss": { "type": "string", "enum": [ "https://marketplace.vercel.com" ] }, "aud": { "type": "string", "description": "The integration ID. Example: \"oac_9f4YG9JFjgKkRlxoaaGG0y05\"" }, "type": { "type": "string", "enum": [ "access_token", "id_token" ], "description": "The type of the token: id_token or access_token." }, "account_id": { "type": "string" }, "sub": { "type": "string", "description": "Denotes the User who is making the change (matches `/^account:[0-9a-fA-F]+:user:[0-9a-fA-F]+$/`)" }, "installation_id": { "type": "string", "description": "The ID of the installation. Example: \"icfg_9bceb8ccT32d3U417ezb5c8p\"" }, "user_id": { "type": "string" }, "user_role": { "type": "string", "enum": [ "ADMIN", "USER" ], "description": "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." }, "user_email": { "type": "string", "description": "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_name": { "type": "string", "description": "The user's real name" }, "user_avatar_url": { "type": "string", "description": "The user's public avatar URL" } }, "required": [ "iss", "aud", "account_id", "sub", "installation_id", "user_id", "user_role" ], "additionalProperties": false } ``` **System Authentication**: This authentication uses the [OpenID Connect Protocol (OIDC)](https://auth0.com/docs/authenticate/protocols/openid-connect-protocol). Vercel sends a JSON web token (JWT) signed with Vercel’s private key and verifiable using Vercel’s public [JSON Web Key Sets](https://auth0.com/docs/secure/tokens/json-web-tokens/json-web-key-sets) (JWKS) available [here](https://marketplace.vercel.com/.well-known/jwks). System Auth OIDC token claims schema: ```json type=jsonschema { "type": "object", "properties": { "iss": { "type": "string", "enum": [ "https://marketplace.vercel.com" ] }, "sub": { "type": "string", "description": "Denotes the Account (or Team) who is making the change (matches `/^account:[0-9a-fA-F]+$/`), possibly null" }, "aud": { "type": "string", "description": "The integration ID. Example: \"oac_9f4YG9JFjgKkRlxoaaGG0y05\"" }, "type": { "type": "string", "enum": [ "access_token", "id_token" ], "description": "The type of the token: id_token or access_token." }, "installation_id": { "type": "string", "nullable": true, "description": "The ID of the installation. Example: \"icfg_9bceb8ccT32d3U417ezb5c8p\"" }, "account_id": { "type": "string" } }, "required": [ "iss", "sub", "aud", "installation_id", "account_id" ], "additionalProperties": false } ``` ## Path Parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `installationId` | string | ✓ | | ## Header Parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `X-Vercel-Auth` | string | | The auth style used in the request (system, user, etc) | | `Idempotency-Key` | string | | A unique key to identify a request across multiple retries | ## Request Body **Content-Type**: `application/json` ```json { "invoiceId": "string" // required // ID of the invoice in Vercel proving the purchase of credits } ``` ## Responses ### 200 Return a timestamp alongside a list of balances for the installation with the most up-to-date values **Content-Type**: `application/json` ```json { "timestamp": "string" // required // Server time of your integration, used to determine the most recent data for race conditions & updates. Format is ISO 8601 YYYY-MM-DDTHH:mm:ss.SSSZ, "balances": [ // required "resourceId": "string" // Partner-provided resource ID, "credit": "string" // For overriding the USD default. A human-readable description of the credits the user currently has, e.g. "2,000 Tokens", "nameLabel": "string" // For overriding the USD default. The name of the credits, for display purposes, e.g. "Tokens", "currencyValueInCents": "number" // required // The dollar value of the credit balance, in USD and provided in cents, which is used to trigger automatic purchase thresholds. ] } ``` ### 400 Input has failed validation **Content-Type**: `application/json` ```json { "error": { // required "code": "string" // required, "message": "string" // required // System error message, "user": { "message": "string" // User-facing error message, if applicable, "url": "string" // URL to a user-facing help article, or a dashboard page for resolution, if applicable }, "fields": [ "key": "string" // required, "message": "string" ] } } ``` ### 403 Operation failed because the authentication is not allowed to perform this operation **Content-Type**: `application/json` ```json { "error": { // required "code": "string" // required, "message": "string" // required // System error message, "user": { "message": "string" // User-facing error message, if applicable, "url": "string" // URL to a user-facing help article, or a dashboard page for resolution, if applicable } } } ``` ### 409 Operation failed because of a conflict with the current state of the resource **Content-Type**: `application/json` ```json { "error": { // required "code": "string" // required, "message": "string" // required // System error message, "user": { "message": "string" // User-facing error message, if applicable, "url": "string" // URL to a user-facing help article, or a dashboard page for resolution, if applicable } } } ``` ### 422 Operation is well-formed, but cannot be executed due to semantic errors **Content-Type**: `application/json` ```json { "error": { // required "code": "string" // required, "message": "string" // required // System error message, "user": { "message": "string" // User-facing error message, if applicable, "url": "string" // URL to a user-facing help article, or a dashboard page for resolution, if applicable } } } ``` --- ## Related - [Marketplace API Reference](/docs/integrations/create-integration/marketplace-api/reference) - [Native Integration Concepts](/docs/integrations/create-integration/native-integration) --- [View full sitemap](/docs/sitemap)