--- title: "Purchase credits" method: POST path: "/v1/billing/buy" tags: ["billing"] --- # Purchase credits `POST /v1/billing/buy` ## Request - Base URL: `https://api.vercel.com` - URL: `https://api.vercel.com/v1/billing/buy` - Auth: HTTP bearer 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 - `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 - `alignBillingWithPlanChangeDate` false | true: Whether or not to reset the billing cycle - `couponRedemptionCode` string: The coupon redemption code to apply to the plan change - `effectiveDate` union, required - … - `externalPlanId` string: The ID of the external plan to change to - `orbSubscriptionId` string, required: The ID of the Orb subscription to change - `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 - `add` unknown[]: The price intervals to add to the subscription - … - `addAdjustments` unknown[]: The adjustment intervals to add to the subscription - … - `allowInvoiceCreditOrVoid` false | true: Whether to allow invoice credit or void - `edit` unknown[]: The price intervals to edit on the subscription - … - `editAdjustments` unknown[]: The adjustment intervals to edit on the subscription - … - `orbSubscriptionId` string, required: The ID of the Orb subscription to modify price intervals for - `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 - `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 - `externalPlanId` string, required: The external plan ID of the Orb plan to subscribe to - `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 - `lineItems` object[]: The line items that make up the Purchase Intent. - … - `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: 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 - `output` object, required - `pendingSubscriptionChangeId` string: The ID of the pending subscription change - `type` 'orb_subscription_intent', required - object: The configuration for a credit purchase - `options` object, required: Purchase configuration specific options - `fromPlan` object: The current plan being replaced by this purchase - … - `planId` string, required: The ID of the plan to subscribe to - `planItemPrices` object[]: The plan item prices to set for the subscription, independent of quantities - … - `planItemQuantities` object[]: The plan item quantities to set for the subscription - … - `rateVariantKey` string: The rate variant key to apply to the subscription - `output` object, required - `planChangeId` string: The committed Plan revision used to calculate the purchase price - `type` 'subscription', required - `createdAt` string, required: The datetime when the Purchase Intent was created. - `currency` 'miu' | 'usd', required: The currency for the purchase intent - `dispute` object: The dispute details, if any. - `amount` string, required: The disputed amount. - `createdAt` string, required: When the dispute was first recorded. - `currency` string, required: The dispute currency. - `id` string, required: The unique ID of the dispute entity. - `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. - `id` string, required: The unique ID of a Purchase Intent. Uses the format `pur_*` - `lineItems` object[]: The line items that make up the Purchase Intent. - `description` string, required: The description of the line item - `id` string, required: The ID of the line item - `metadata` object: Optional metadata for the line item - `name` string, required: The name of the line item - `productAlias` string: The alias of the product being purchased - `productId` string, required: The ID of the product being purchased - `quantity` string, required: The quantity of the line item - `refund` string: The amount of the line item that has been refunded - `unitAmount` string, required: The unit amount of the line item - `metadata` object: Optional metadata associated with the purchase intent - `ownerId` string, required: The ID of the owner of the Purchase Intent. - `provider` object, required - `currencyConversionRate` string: The currency conversion rate used by the provider - `resourceId` string, required: Provider resource id - `stripeSharedPaymentTokenUsed` false | true: Whether a Stripe Shared Payment Token was used for this purchase. Only applicable when type is stripe_invoice_immediate. - `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 - `refund` string: The amount of the purchase intent that has been refunded - `returnUrl` string: The URL to redirect to after the purchase is complete - `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. - object - `orbSubscriptionIntent` object, required - `configuration` union, required - object: Configuration for the Orb subscription intent. - `options` object, required - `productAlias` string, required: The alias of the product to set quantity for. - `quantity` number, required: The quantity to set for the plan item. - `output` object, required: Output returned after configuring an OrbSubscriptionIntent. - `changedResources` object[]: Resources that were changed as part of this intent. Tracks all logical changes including the primary change and any side effects. - … - `customerTimezone` string: The Orb customer's timezone when the intent was created. Omitted for legacy intents. - `effectiveBehavior` 'end_of_term' | 'immediate', required: When the subscription change should take effect. - `metadata` object: Optional metadata associated with the intent to update the Orb subscription with. - `orbPriceId` string, required: The Orb price ID for the subscription item being modified. - `pendingSubscriptionChangeId` string: The ID of the pending subscription change if there is one. - `pricingSource` 'copper' | 'orb', required: The source used as the authoritative price for this intent. - `productId` string, required: The product ID associated with this intent. - `referenceBillingPeriod` object: The canonical reference-product billing period at intent creation. Omitted for historical intents. - … - `type` 'set_plan_item_quantity', 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[], required - `output` object, required: Output returned after configuring an OrbSubscriptionIntent. - `changedResources` object[]: Resources that were changed as part of this intent. Tracks all logical changes including the primary change and any side effects. - … - `customerTimezone` string: The Orb customer's timezone when the intent was created. Omitted for legacy intents. - `effectiveBehavior` 'end_of_term' | 'immediate', required: When the subscription change should take effect. - `metadata` object: Optional metadata associated with the intent to update the Orb subscription with. - `orbPriceId` string, required: The Orb price ID for the subscription item being modified. - `pendingSubscriptionChangeId` string: The ID of the pending subscription change if there is one. - `pricingSource` 'copper' | 'orb', required: The source used as the authoritative price for this intent. - `productId` string, required: The product ID associated with this intent. - `referenceBillingPeriod` object: The canonical reference-product billing period at intent creation. Omitted for historical intents. - … - `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. - `changedResources` object[]: Resources that were changed as part of this intent. Tracks all logical changes including the primary change and any side effects. - … - `customerTimezone` string: The Orb customer's timezone when the intent was created. Omitted for legacy intents. - `effectiveBehavior` 'end_of_term' | 'immediate', required: When the subscription change should take effect. - `metadata` object: Optional metadata associated with the intent to update the Orb subscription with. - `orbPriceId` string, required: The Orb price ID for the subscription item being modified. - `pendingSubscriptionChangeId` string: The ID of the pending subscription change if there is one. - `pricingSource` 'copper' | 'orb', required: The source used as the authoritative price for this intent. - `productId` string, required: The product ID associated with this intent. - `referenceBillingPeriod` object: The canonical reference-product billing period at intent creation. Omitted for historical intents. - … - `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. - `changedResources` object[]: Resources that were changed as part of this intent. Tracks all logical changes including the primary change and any side effects. - … - `customerTimezone` string: The Orb customer's timezone when the intent was created. Omitted for legacy intents. - `effectiveBehavior` 'end_of_term' | 'immediate', required: When the subscription change should take effect. - `metadata` object: Optional metadata associated with the intent to update the Orb subscription with. - `orbPriceId` string, required: The Orb price ID for the subscription item being modified. - `pendingSubscriptionChangeId` string: The ID of the pending subscription change if there is one. - `pricingSource` 'copper' | 'orb', required: The source used as the authoritative price for this intent. - `productId` string, required: The product ID associated with this intent. - `referenceBillingPeriod` object: The canonical reference-product billing period at intent creation. Omitted for historical intents. - … - `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. - `changedResources` object[]: Resources that were changed as part of this intent. Tracks all logical changes including the primary change and any side effects. - … - `customerTimezone` string: The Orb customer's timezone when the intent was created. Omitted for legacy intents. - `effectiveBehavior` 'end_of_term' | 'immediate', required: When the subscription change should take effect. - `metadata` object: Optional metadata associated with the intent to update the Orb subscription with. - `orbPriceId` string, required: The Orb price ID for the subscription item being modified. - `pendingSubscriptionChangeId` string: The ID of the pending subscription change if there is one. - `pricingSource` 'copper' | 'orb', required: The source used as the authoritative price for this intent. - `productId` string, required: The product ID associated with this intent. - `referenceBillingPeriod` object: The canonical reference-product billing period at intent creation. Omitted for historical intents. - … - `type` 'adjust_plan_item_quantity', required - `createdAt` string, required: The ISO 8601 date-time that the intent was created. - `id` string, required: The ID of the Orb subscription intent with the format `orbsubint_`. - `orbSubscriptionId` string, required: The Orb subscription ID this intent is associated with. - `orbUpdate` union, required - object: How the subscription change is applied to Orb. - `mode` 'sync', required - object: How the subscription change is applied to Orb. - `mode` 'async', required - `status` 'canceled' | 'failed' | 'pending' | 'running', required - object: How the subscription change is applied to Orb. - `appliedAt` string, required: The ISO 8601 date-time that the subscription change was applied to Orb. - `mode` 'async', required - `status` 'succeeded', required - `ownerId` string, required: The owner ID for this intent (e.g., team or user ID). - `purchaseIntentId` string: Optional purchase intent ID if this is associated with a purchase. - `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. ## 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` - `409` - `410` - `500` ## Changes - **2026-10-28** `eb708f37d41f`: 1 breaking, 1 info - added `subschema #1, subschema #2` to the `oneOf[subschema #3]/orbSubscriptionIntent/configuration` response property `oneOf` list for the response status `200` - removed `subschema #1` from the `oneOf[subschema #3]/orbSubscriptionIntent/configuration` response property `oneOf` list for the response status `200` - **2026-10-20** `6a3a421e252e`: 3 info - added the optional property `oneOf[subschema #2]/purchaseIntent/configuration/oneOf[subschema #7]/options/fromPlan/additionalSubscriptions` to the response with the `200` status - added the optional property `oneOf[subschema #2]/purchaseIntent/configuration/oneOf[subschema #7]/options/fromPlan/planItemPrices` to the response with the `200` status - added the optional property `oneOf[subschema #2]/purchaseIntent/configuration/oneOf[subschema #7]/options/planItemPrices` to the response with the `200` status - **2026-09-29** `8ef4901ffe83`: 1 breaking, 1 info - added `subschema #1, subschema #2, subschema #3, subschema #4` to the `oneOf[subschema #3]/orbSubscriptionIntent/configuration` response property `oneOf` list for the response status `200` - removed `subschema #1, subschema #2, subschema #3, subschema #4` from the `oneOf[subschema #3]/orbSubscriptionIntent/configuration` response property `oneOf` list for the response status `200` - …earlier changes not shown [Operation history](https://skmtc.dev/vercel/apis/vercel-api/changes/v1/billing/buy/post.md) --- [API](https://skmtc.dev/vercel/apis/vercel-api.md) - [All operations](https://skmtc.dev/vercel/apis/vercel-api/llms.txt) - [OpenAPI document](https://skmtc.dev/vercel/apis/vercel-api/revisions/60686c0e1f6a?raw)