--- title: "Purchase credits" method: POST path: "/v1/billing/buy" tags: ["billing"] --- # Purchase credits `POST /v1/billing/buy` Purchases credits for a Vercel team using the default payment method on file. The purchase is charged immediately via Stripe invoice. Supported credit types are `v0`, `gateway`, and `agent`. The `amount` field specifies the number of credits to purchase and must be a positive integer. An optional `source` query parameter can be provided to identify the caller. Defaults to `api` if not specified. This is only available for Owner, Member, Developer, Security, and Billing roles for the supplied team. ## Query parameters - `source` string — The source of the purchase request. Defaults to `api` if not specified. - `teamId` string - `slug` string ## Request body - object - `item` object, required - `type` 'credits', required — The type of item to purchase. - `creditType` 'v0' | 'gateway' | 'agent', required — The type of credits to purchase. - `amount` integer, required — The amount of credits to purchase. ## Response `200` - union - object - `checkoutSessionId` string, required - `checkoutSessionUrl` string, required - object - `purchaseIntent` object, required — The created purchase intent - `id` string, required — The unique ID of a Purchase Intent. Uses the format `pur_*` - `configuration` union, required - object — The configuration for a credit purchase - `options` object, required — Purchase configuration specific options - `amount` string, required — The amount of currency to buy - `currency` 'ai_credits' | 'ai_gateway_credits' | 'copper_test_units' | 'v0_user_credits' | 'vercel_agent_credits', required — The currency being purchased - `expirationDate` string — The expiration date of the credits being purchased - `output` unknown, required - `type` 'credit_topup', required - object — The configuration for a credit purchase - `options` object, required - `items` object[], required - … - `orderId` string, required — The order ID of the domain name purchase - `output` unknown, required - `type` 'domain_name', required - object — The configuration for a credit purchase - `options` object, required - `effectiveDate` union, required - … - `orbSubscriptionId` string, required — The ID of the Orb subscription to change - `alignBillingWithPlanChangeDate` false | true — Whether or not to reset the billing cycle - `couponRedemptionCode` string — The coupon redemption code to apply to the plan change - `externalPlanId` string — The ID of the external plan to change to - `replacePrices` object[] — The prices to replace in the subscription - … - `output` object, required - `pendingSubscriptionChangeId` string, required — The ID of the pending subscription change - `type` 'orb_plan_change', required - object — The configuration for a credit purchase - `options` object, required - `output` object, required - `pendingSubscriptionChangeId` string, required — The ID of the pending subscription change - `type` 'orb_price_interval', required - object — The configuration for a credit purchase - `options` object, required - `externalPlanId` string, required — The external plan ID of the Orb plan to subscribe to - `addPrices` union[] — The prices to add to the subscription - … - `alignBillingWithSubscriptionStartDate` false | true — Whether to align the subscription start date with the billing subscription start date - `couponRedemptionCode` string — The coupon redemption code to apply to the subscription - `initialPhaseOrder` number — The initial phase order to use for the subscription - `metadata` object — Optional metadata to associate with the subscription - `removePrices` object[] — The prices to remove in the subscription - … - `replacePrices` object[] — The prices to replace in the subscription - … - `startDate` string — The start date of the subscription - `output` object, required - `pendingSubscriptionChangeId` string, required — The ID of the pending subscription change - `type` 'orb_subscription', required - object — The configuration for a credit purchase - `options` object, required - `orbCustomerId` string, required — The ID of the Orb customer to create - `orbExternalCustomerId` string, required — The external ID of the Orb customer to create - `orbExternalPlanId` string, required — The external ID of the Orb plan to create - `orbPendingSubscriptionChangeId` string, required — The ID of the pending subscription change - `orbPlanId` string, required — The ID of the Orb plan to create - `orbSubscriptionId` string, required — The ID of the Orb subscription to create - `lineItems` object[] — The line items that make up the Purchase Intent. - … - `output` object, required - `pendingSubscriptionChangeId` string, required — The ID of the pending subscription change - `type` 'orb_subscription_intent', required - `createdAt` string, required — The datetime when the Purchase Intent was created. - `currency` 'miu' | 'usd', required — The currency for the purchase intent - `ownerId` string, required — The ID of the owner of the Purchase Intent. - `provider` object, required - `resourceId` string, required — Provider resource id - `type` 'apple_in_app_purchase' | 'orb_ledger' | 'stripe_elements' | 'stripe_hosted' | 'stripe_invoice_deferred' | 'stripe_invoice_elements' | 'stripe_invoice_immediate' | 'tackle_aws_marketplace', required — The type of the purchase provider - `currencyConversionRate` string — The currency conversion rate used by the provider - `stripeSharedPaymentTokenUsed` false | true — Whether a Stripe Shared Payment Token was used for this purchase. Only applicable when type is stripe_invoice_immediate. - `status` 'failed' | 'pending' | 'succeeded', required — The status of the Purchase Intent. - `subtotal` string, required — The subtotal of the Purchase Intent. - `tax` string, required — The tax due on the Purchase Intent. - `total` string, required — The total balance due on the Purchase Intent. - `updatedAt` string, required — The datetime when the Purchase Intent was last updated. - `dispute` object — The dispute details, if any. - `id` string, required — The unique ID of the dispute entity. - `amount` string, required — The disputed amount. - `createdAt` string, required — When the dispute was first recorded. - `currency` string, required — The dispute currency. - `providerId` string, required — The external provider dispute ID (e.g. Stripe dispute ID). - `reason` string, nullable, required — The dispute reason. - `status` string, required — The dispute status. - `updatedAt` string, required — When the dispute was last updated. - `lineItems` object[] — The line items that make up the Purchase Intent. - `id` string, required — The ID of the line item - `description` string, required — The description of the line item - `name` string, required — The name of the line item - `productId` string, required — The ID of the product being purchased - `quantity` string, required — The quantity of the line item - `unitAmount` string, required — The unit amount of the line item - `metadata` object — Optional metadata for the line item - `productAlias` string — The alias of the product being purchased - `refund` string — The amount of the line item that has been refunded - `metadata` object — Optional metadata associated with the purchase intent - `refund` string — The amount of the purchase intent that has been refunded - `returnUrl` string — The URL to redirect to after the purchase is complete - object - `orbSubscriptionIntent` object, required - `id` string, required — The ID of the Orb subscription intent with the format `orbsubint_`. - `configuration` union, required - object — Configuration for the Orb subscription intent. - `options` object, required — Configuration input options for setting plan item quantity. - `productAlias` string, required — The alias of the product to set quantity for. - `quantity` number, required — The quantity to set for the plan item. - `resourceIds` string[] — The resource IDs for the plan item. Only set if SKU requires resource entitlements. - `output` object, required — Output returned after configuring an OrbSubscriptionIntent. - `effectiveBehavior` 'end_of_term' | 'immediate', required — When the subscription change should take effect. - `orbPriceId` string, required — The Orb price ID for the subscription item being modified. - `productId` string, required — The product ID associated with this intent. - `changedResources` object[] — Resources that were changed as part of this intent. Tracks all logical changes including the primary change and any side effects. - … - `metadata` object — Optional metadata associated with the intent to update the Orb subscription with. - `pendingSubscriptionChangeId` string — The ID of the pending subscription change if there is one. - `type` 'set_plan_item_quantity', required - object — Configuration for the Orb subscription intent. - `options` object, required — Configuration input options for increasing plan item quantity. - `productAlias` string, required — The alias of the product to increase quantity for. - `resourceIds` string[], required — The resource IDs to incrementally add. The quantity of the plan item will be increased by the number of resource IDs. - `output` object, required — Output returned after configuring an OrbSubscriptionIntent. - `effectiveBehavior` 'end_of_term' | 'immediate', required — When the subscription change should take effect. - `orbPriceId` string, required — The Orb price ID for the subscription item being modified. - `productId` string, required — The product ID associated with this intent. - `changedResources` object[] — Resources that were changed as part of this intent. Tracks all logical changes including the primary change and any side effects. - … - `metadata` object — Optional metadata associated with the intent to update the Orb subscription with. - `pendingSubscriptionChangeId` string — The ID of the pending subscription change if there is one. - `type` 'increase_plan_item_quantity', required - object — Configuration for the Orb subscription intent. - `options` object, required — Configuration input options for decreasing plan item quantity. - `productAlias` string, required — The alias of the product to decrease quantity for. - `resourceIds` string[], required — The resource IDs to decrementally remove. The quantity of the plan item will be decreased by the number of resource IDs. - `output` object, required — Output returned after configuring an OrbSubscriptionIntent. - `effectiveBehavior` 'end_of_term' | 'immediate', required — When the subscription change should take effect. - `orbPriceId` string, required — The Orb price ID for the subscription item being modified. - `productId` string, required — The product ID associated with this intent. - `changedResources` object[] — Resources that were changed as part of this intent. Tracks all logical changes including the primary change and any side effects. - … - `metadata` object — Optional metadata associated with the intent to update the Orb subscription with. - `pendingSubscriptionChangeId` string — The ID of the pending subscription change if there is one. - `type` 'decrease_plan_item_quantity', required - object — Configuration for the Orb subscription intent. - `options` object, required — Configuration input options for adjusting plan item quantity. - `addedResourceIds` string[], required — The resource IDs to incrementally add. The quantity of the plan item will be increased by the number of resource IDs. - `productAlias` string, required — The alias of the product to adjust quantity for. - `removedResourceIds` string[], required — The resource IDs to incrementally remove. The quantity of the plan item will be decreased by the number of resource IDs. - `output` object, required — Output returned after configuring an OrbSubscriptionIntent. - `effectiveBehavior` 'end_of_term' | 'immediate', required — When the subscription change should take effect. - `orbPriceId` string, required — The Orb price ID for the subscription item being modified. - `productId` string, required — The product ID associated with this intent. - `changedResources` object[] — Resources that were changed as part of this intent. Tracks all logical changes including the primary change and any side effects. - … - `metadata` object — Optional metadata associated with the intent to update the Orb subscription with. - `pendingSubscriptionChangeId` string — The ID of the pending subscription change if there is one. - `type` 'adjust_plan_item_quantity', required - `createdAt` string, required — The ISO 8601 date-time that the intent was created. - `orbSubscriptionId` string, required — The Orb subscription ID this intent is associated with. - `ownerId` string, required — The owner ID for this intent (e.g., team or user ID). - `status` 'failed' | 'pending' | 'succeeded', required — The status of the Orb subscription intent. - `updatedAt` string, required — The ISO 8601 date-time that the intent was last updated. - `purchaseIntentId` string — Optional purchase intent ID if this is associated with a purchase. ## Other responses - `400` — One of the provided values in the request query is invalid. - `401` — The request is not authorized. - `402` - `403` — You do not have permission to access this resource. - `404` - `410` - `500` --- [API](https://skmtc.net/vercel/apis/api.md) · [All operations](https://skmtc.net/vercel/apis/api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/vercel/api/versions/61d1ba3f6dac/schema)